Root 2.1 kernel API

The frozen 34-symbol ABI 1.4 caller contract, refusal codes and process-crash durability limits.

Final contract for ABI 1.4, annotated tag root-2.1. Source citations are relative to its RURAL commit 4e84fec244a29f348946ec006894c51df87290b7; line numbers describe that commit, not the earlier draft worktrees. RN-08 checked the tag target on 9 November 2026; the earlier pre-rewrite citation is superseded. Signature review remains pending after the history rewrite. This document resolves draft decisions from landed code; it does not close the remaining evidence gates recorded in I-01.

Root 2.1 is process-crash durable, NOT power-loss durable. Successful durable operations sync before acknowledging; uncertain publication poisons the handle. The isolated block-device harness is deferred. SIGKILL/torn-write evidence and bounded formal checks do not qualify physical power-loss ordering (src/storage/receipt_log.zig:2626, src/storage/receipt_log.zig:2720, docs/grove/results/R-12b.md:6, docs/grove/results/R-12.md:212).

Frozen surface and caller contract#

Exactly 34 symbols, with the argument/return declarations, pointer nullability, fixed array extents and struct layouts in the cited header frozen verbatim. rural_grove_abi_version() returns 0x00010004; phase-1 builds remain a distinct 26-symbol ABI 1.0 (src/grove_abi.zig:72, include/rural_grove.h:67). The groups contain 5 lifecycle, 1 memory, 7 arena, 11 map, 4 log, 3 CAS/key and 3 storage operations. The previous draft's “Map (12)” heading was incorrect.

Normative layout: opaque rural_grove_engine; rural_grove_buf is nullable uint8_t *ptr, then size_t len; rural_grove_cas_op is nullable constant key pointer, size_t key_len, int32_t has_expected, uint8_t expected[34], int32_t has_new, uint8_t new_value[34]. Use native C alignment, not packed layouts. Hashes are 34 bytes and canonical leaves 48 bytes (include/rural_grove.h:8, include/rural_grove.h:26, include/rural_grove.h:61).

Calls are serialized per engine. The caller holds a mutex across call plus last_error, an entire paginated scan, and exclusive close. Pointers cover their extents; null byte pointers require zero length. Output objects are valid, aligned and mutually disjoint. Use disjoint input/output storage to satisfy both the general comment and the older CAS-specific restriction. No output borrows an engine. Free each returned buffer exactly once even after failure (including fsck). New APIs clear buffer/handle/more on failure; scan preserves generation. last_error requires a valid handle and cannot diagnose a failed open that published none (include/rural_grove.h:29, include/rural_grove.h:121, src/grove_abi.zig:85, src/grove_abi.zig:371).

Return codes (ABI 1.4)#

Busy and wrong-node are distinct in the same C return space (RF-173 resolved). A failed competing open returns 8 without a handle; wrong-node returns 11. Malformed node input is 3, and stored identity damage is 10. Never treat every code 8 as busy. The ABI has no global last_error for open failures (include/rural_grove.h:39, src/grove_abi.zig:78, src/grove_abi.zig:98).

Refusals and admission#

Fsck vocabulary and opaque namespace#

Read-only report fields include schema_version, format_version, complete, clean, verdict, embedder_namespace, coverage, counts, scratch, first_failure, commit_slots, truncation flags and findings. Finding fields are path, offset, category, severity, invariant. Retained-list truncation does not change verdict/count semantics (src/storage/grove_fsck.zig:67, src/storage/grove_fsck.zig:98, src/storage/grove_fsck.zig:126).

Only the root directory .embedder/ is opaque; similarly named nested objects or a root file/symlink are not namespaces. Within fsck's documented coverage, all non-opaque store bytes are kernel-owned and inspected; unknown root entries prevent a clean verdict. Supplied typed tree roots are checked; fsck does not infer application tree roots or semantic supersession edges from arbitrary blobs/CAS digests (src/storage/grove_fsck.zig:156, src/storage/grove_fsck.zig:1353, src/storage/grove_fsck.zig:1477).

Slot publication, best-effort frames and locks#

A/B slots are independent whole envelopes, version 2 kind 11. Select the valid identity-bound slot with greatest generation; equal valid generations or a present pair with no valid member refuse corruption. One valid slot suffices. Both absent is allowed only for first publication, not normal load (src/storage/grove_commit.zig:40, src/storage/grove_commit.zig:59, src/storage/grove_commit.zig:90). The writer validates generation+1, overwrites the other slot at offset zero without truncation or a rename, then follows:

sync frames and candidate pages -> whole slot overwrite -> file fsync (including fdatasync barrier) -> parent-directory sync -> memory publication -> acknowledgement (src/storage/grove_commit.zig:179, src/storage/grove_commit.zig:195, src/storage/grove_commit.zig:208, src/storage/grove_commit.zig:214, src/storage/receipt_log.zig:2632, src/storage/receipt_log.zig:2644). RuralSlots is bounded evidence for this ordering, with independent-file/checksum/durable-payload assumptions; it is not an unbounded implementation proof (docs/grove/results/F-01.md:7, docs/grove/results/F-01.md:77).

The local durable-best-effort stream appends/syncs a kind-11 frame carrying the next candidate N+1, before publishing its slot. Complete durable but unacknowledged N+1 may be recovered; a torn N+1 falls back while preserving acknowledged N. Durable mode and imported peer streams write zero such frames. Fsck validates their metadata and reports bytes beyond selected COMMIT as unacknowledged (src/storage/receipt_log.zig:2624, src/storage/receipt_log.zig:2708, src/storage/receipt_log.zig:2717, src/storage/receipt_log.zig:2725, src/storage/grove_commit.zig:93, src/storage/grove_fsck.zig:1269). The frozen C open selects explicit durable configuration; the best-effort rule also describes internal storage behavior (src/grove_abi.zig:326).

One lock per store root, held per handle. Rural's root LOCK owns store exclusion, acquired exclusively and nonblocking before classification of FORMAT/bootstrap/legacy data; fsck uses the same existing inode and exclusive fence. Competing opens return busy 8 in both the same and other processes. Legacy compatibility also holds owner.lock against old writers. No lock inode is removed. Close/error unwind explicitly unlocks the owning description before closing it, so fork-inherited descriptors cannot prolong that handle's lock. After close returns, a valid root can be reopened by any process unless another live owner acquired it. An embedder CLI lock only serializes its CLI and never owns the store-use fact (include/rural_grove.h:44, src/grove_abi.zig:244, src/grove_abi.zig:296, src/grove_abi.zig:310, src/grove_abi.zig:365, src/storage/grove_fsck.zig:1523).

Post-tag changes, limits and evidence#

D-R45's change rule: additive only after the tag. A changed symbol gets a _v2 suffix; the old symbol stays. No frozen symbol, argument/struct field, existing enum value, verdict word or category is removed before Root 3. New codes append; additions increment the minor version while major remains 1. The appended WRONG_NODE 11 is part of this freeze, ABI 1.4, not a post-tag addition (include/rural_grove.h:23, src/grove_abi.zig:72; freeze policy recorded in docs/grove/results/I-01.md).

Known limits: the frozen 1.0 binary refusing a format-2 store leaves one empty mode-0600 regular file owner.lock. This is a harness tolerance only; fsck reports it as an unknown root entry, and the operator may delete it.

Known limits: RuralMajority remains a skeleton, outside Root 2.1 proof claims (formal/RuralMajority.tla:6). Chunked writes are not exposed through the GROVE binding; ordinary large puts are not chunked evidence (G-02c result and M-5 transcript, referenced by the collector). R-20 heads journal is post-tag: R-14 measured 470,040 bytes/CAS against 65,536, with idle-host timing and R-21 sync attribution unqualified (docs/grove/results/R-14.md:5, docs/grove/results/R-14.md:169). Power-loss qualification remains deferred.

Run zsh scripts/root21_evidence.zsh <absent-outdir> at the annotated tag commit. It emits EVIDENCE.md/evidence.json with exact commands, actual exits/counts, log hashes, source/archive identities and honest MAIN/reference rows. Set GROVE_WORKTREE for offline fresh GROVE creation/full comparison; ROOT21_DOGFOOD_STORES supplies newline-separated closed roots for read-only fsck, and ROOT21_FORMAL_CACHE supplies a prepopulated verified pinned jar cache. No network download or live-store migration is performed. R-14 numbers and the M-5 transcript are explicitly identified historical references, not relabelled current runs. I-01's retained pre-tag collection does not prove the rewritten tag commit; remaining MAIN items require matching evidence. Tag signature review remains pending. The collector only prints a signing command and never executes it.