@sema-agent/core 7.26.0 → 7.26.1

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 7.26.1 — 2026-09-21
+
+### One store, one answer about one file; one lineage judgment at every station (#1003 + #1000; narrowing; +0 exports; @server)
+
+- **#1003 — the enumeration face judged less than the per-key read.** `FileSessionPolicyStore.getRules` validated a row's SHAPE (a `rev` of at least 1, a whole `gen`, string-array rule fields) and answered ABSENT with a disclosure when it failed; `listBySession` checked "a JSON object carrying our `__sid`" and cast. So one store answered two different things about one file: a row carrying `toolDeny: "rm"` or `rev: 0` was absent to the keyed read and served VERBATIM through the enumeration face that the cross-backend policy export and a deployment's session listing read.
+- **What changes.** The shape judgment is one function now, and both rules-serving faces run it, in the same order, with the same disclosure words. **Narrowing:** a malformed row is absent from `listBySession` and disclosed once through `onCorruptRead`, where it used to be returned. The tolerance is unchanged — one bad row does not void an enumeration. The enumeration attributes before it judges shape, so another session's malformed row is that session's fact rather than noise repeated in every other session's listing.
+- **Who is hurt.** A deployment that read `listBySession` expecting whatever is on disk (a characterization test, a backup differ) sees the row vanish and one extra disclosure. That is the point: nothing could ENFORCE that row, so nothing should have exported it either. The erase sweep and the ownership rebind are unaffected — they read a row's attribution, never its rules, so a malformed-rules row is still erasable and still travels with its key.
+- **#1000 — an absent `gen` meant three things.** `StoredSessionRules.gen` names the lineage a row's `rev` counts within, and the type says an absent one is generation 0. Three stations read it otherwise: the file store's stamp took a READ row carrying no `gen` for "no lineage" and opened a new generation over it; the live reader skipped the comparison unless BOTH rows carried the field; the inherited-gate merge read either side's absence as "same lineage, go ahead". A row of generation 1 could therefore pass for a continuation of a row that spelled its generation nowhere.
+- **What changes.** `continuesLineage(a, b)` is that judgment, in one place, absent = 0; all three stations read it, including the per-call handoff claim, which compared revs without asking at all. **Narrowing:** a live row of another generation no longer replaces the one a leg enforces or the one a checkpoint recorded. The file store's stamp continues a row it could READ and keeps the new generation for the case it was written for — bytes that exist and cannot be read as a row. That half is load-bearing for the other: without it, an upgraded deployment's first tightening over a pre-lineage row would open a generation the leg enforcing that very row would then refuse to follow.
+- **Who is hurt (@server).** A durable twin that does not persist `gen` while core's checkpoint recorded one has its live ancestor rows refused at the merge — fail-closed, the checkpoint's row stands. The repair is to carry the column; both bundled backends do. Absence still carries one other fact, and it is a different question: a backend that stamps no lineage at ALL offers its reader no recycle evidence, so the live reader keeps the older, weaker guard there (it watched the row vanish). What that guard cannot do at the MERGE, which has no observation channel, is recorded as KL-1003a.
+- **Three more from the adversarial round, same class.** (1) **An erase now ends the lineage of EVERY row it removes**, including a torn row belonging to another session. The sweep deletes every unparseable row it meets — that ruling stands — but it used to end the lineage only when the mark named the session being erased, so a foreign key lost its row and kept its generation: the key's next write found no file, continued a generation a leg still enforced, and was taken for that row at a higher rev (measured: the leg answered `allow`, now `deny`). One removal, one lineage transition; the "whose session is this" special case is gone. (2) **The no-lineage fallback reads the LIVE row.** Whether a backend stamps lineages at all is a fact about what it writes NOW; reading the ENFORCED row's absence the same way refused a legitimate generation-0 tightening forever after one transient gap — precisely the row the new file-store stamp produces on an upgraded deployment. A genuinely lineage-less recreation after an observed gap is still refused (pinned as the control). (3) **`listBySession` no longer casts a principal it cannot spell**: a `__principal` that is neither a string nor null is disclosed and skipped instead of shipped through a `string | undefined` seat. That is the enumeration's own attribution question — the keyed read never asks it, because its key comes from the caller.
+- Wire table: `docs/wire-consumption/unreleased-1003.md`. Export surface: `npm run handoff:diff v7.26.0 HEAD` = +0 / −0.
+### A rule-write outcome is READ, and every revision it carries is judged (#1007; behaviour NARROWING; +0 exports; @server @cli @client-core)
+- **What changed.** `apply`'s answer is DATA — a foreign backend, a deserialized reply, a twin compiled against another generation — and both write entries used to discriminate it by asking whether it carried `conflict` or `refused`, calling everything else a landing. `{}` satisfies that test, so a write nobody could confirm was reported as committed at revision `undefined` through a field the type says is a `number`; `null` threw the `in` operator out of an entry whose declared result union has no throwing arm. One reader (`readRuleWriteOutcome`, module-internal) now tells the arms apart once, for all three call sites (`addPersistedRule`, `removePersistedRule`, the sync round).
+- **What a revision is.** A non-negative safe integer. **Zero is a landing**: a session-scope add lands in a partition that has no revision of its own and the landing reports the durable revision unchanged, which is `0` for a bucket nothing has written yet. A string, a negative, a fraction, `NaN`, `null` or an absent `rev` is an answer nothing can read.
+- **Who is hurt.** A host whose rule backend answered a landing without a readable revision was being told `added` / `removed`; it is now told `failed` with `committed: "unknown"` and reconciles with `list()`. That is the narrowing: a false success becomes an honest indeterminate. **Compensation**: the add entry's indeterminate arm takes an evidence read-back, so a backend that really landed the write still reports `added` — only a backend that landed nothing, or cannot be read, reaches the failure. **Consumer matrix**: in-tree backends (file, in-memory, the session partition) are unaffected — each already answered a readable revision, pinned by the positive controls.
+- **Tags are judged by VALUE, not presence.** `{refused: null}` is not a refusal and `{conflict: false}` is not a decline; an answer carrying both tags is an answer about neither. Reading a tag by presence turned a malformed answer into a DEFINITE `committed: "no"`, which is the same over-claim one arm over.
+- **The landing report rides the same judgement.** A `sync` report that is not an object, or whose `droppedInbound` / `quarantined` are not lists of drop records, no longer reaches the sync round's walk (which threw a type error at a caller holding a committed write). The revision still proves the landing, so the landing stands and the lost report is DISCLOSED in the round's warnings.
+- **The session partition's answer is judged before translation.** `SessionRuleApplyResult` has two named arms (`{landed: true}` / `{refused: "session_ended"}`); the routing writer read it by absence of a refusal, so a host partition answering `{}` produced a well-formed landing at the caller's own revision. Exactly one arm now; anything else is a write face that failed, which the entries report as indeterminate.
+- **A readable revision is not evidence of a row.** The judgement above is about the ANSWER; a backend that reports a landing at a perfectly readable revision and writes nothing answers just as well as one that wrote. Both add doors (the record-less entry and the consent protocol's redemption) now WITNESS a reported landing before reporting it — the same read-back the indeterminate arm already took, asking the evidence face for THIS call's own dot, which is minted once and so identifies this call's work and nobody else's. Not seen ⇒ `committed: "unknown"`, never `"no"` (an eventually-consistent backend may converge later); the read-back itself failing ⇒ `unknown` as well. A backend that really wrote still lands, including when it under-reports its revision.
+- **Two smaller over-claims, same ticket.** The bundled file backend's read-back failure said "the change was not committed" about bytes it had not observed — it now says only that the store did not read back as the version just written, and that whether the change reached disk is unobservable from there. And a write-face accessor that THREW was reported as "nothing was written": the backend's own code had run on the seat whose purpose is to touch bytes, so that arm is now `unknown` (an ABSENT face keeps `no` — nothing ran).
+- **Backend authors**: `permissionRuleWriteContract` now asserts that every arm carrying a revision carries a readable one, and that a decline is tagged `conflict: true`. A backend answering `{}`, or tagging a decline with anything else, fails the kit — it was being certified as usable by an engine that reads its answers as unreadable.
+
+### `store.read_back_shape_judged` — one read-back rule across every store family (#1009; additive; +6 exports; @server @test)
+- **The sentence.** `@contract store.read_back_shape_judged` (`src/core/store-contracts/read-back-shape-contract.ts`, quoted for integrators in `docs/INTEGRATION-CORE.md` §5.0): every read a store answers — a single get and an enumeration alike — judges the SHAPE of what it read; a body that is not the shape the store writes reaches the caller as a refusal or as an absence carrying a disclosure that names the loss, never as an empty set, an empty object or a default. Which read-back failures a store TOLERATES is registered per store in §5.0, never inherited from another store's.
+- **The suite.** `storeReadBackShapeContract` (exported, vitest-free like its siblings) plants four corrupt-body forms — `not-an-object` / `missing-required` / `wrong-type` / `torn-json` (`CORRUPT_BODY_FORMS`) — and asks one mechanical question per form: does the corrupt read answer something OTHER than the empty read, and does it keep the planted bytes out of its answer. Clause 1 is the control: the empty and seeded reads must SUCCEED, answer differently, and the empty answer must be REPRODUCIBLE — which is what stops a face that throws at everything, a face that answers everything alike, and a face carrying a per-read id or timestamp from passing for free.
+- **Its ceiling is written down**: clause 2 proves the corrupt case is distinguishable, not that the distinguishing answer is correct. A backend with no bytes a foreign writer could damage declares that ONCE, at the subject, with a reason — never per attempt, where a planter that had simply gone blind could exempt a backend that still had bodies.
+- **The census** (`test/backlog1009-store-read-back-shape.test.ts`) carries a row for every kit in `src/core/store-contracts/`: bound, pending a named ticket, unbound with what is known, or not a store. A kit with no row reds — "nobody wrote one" and "there is nothing to write" may not look the same. Bound today: the durable permission-rule bucket's `list` / `readRaw` / `quarantined`, the unified `effective`, and `SessionPolicyStore.getRules`.
+- **One store took the fix the sentence asks for**: the durable rule bucket's `quarantined()` answered "the quarantine is empty" about a bucket it could not read — exactly the rows a person is being sent to look at. It now refuses the way `list()` does; an ABSENT bucket is still an empty quarantine.
+- **@server**: this is the sentence S-550 asked for. The SQL twin mounts the same suite against its own read faces; `docs/INTEGRATION-CORE.md` §5.0 is the clause-by-clause table.
+### The shell read station has a consumer face on the package root (#1010; additive; +20 exports; @cli)
+- **Before.** Everything the read boundary knows lived inside `src/tools/fs/`, so a downstream fence over the 24-grid decision table had to deep-import `dist/tools/fs/*.js` — a path the package's `exports` map does not promise and a directory re-arrangement breaks. A prior statement that this face was already on the root was wrong: the package root had zero of these names.
+- **After.** Twenty names on the root, and nothing else: the vocabulary (`SHELL_READ_FINDINGS`, `SHELL_READ_SEATS`, `SHELL_READ_FINDING_RANK`, `SHELL_READ_DECISION` — the closed sets already registered in `docs/CLOSED-SETS.md`), thirteen shape types (`ShellReadVerdict`, `ShellReadBoundary`, `ShellReadPlan`, `EstablishedRead`, `ReadEstablishment`, …), and ONE call: `judgeShellRead({ command, env, boundary, seat })` → `{ plan, establishment, verdict, offer? }`.
+- **The one call is not a second judgment.** The station's pipeline is now written once and has two entries: the gate input's judge leg, and this one. They differ only in bookkeeping — the gate remembers an admission, the consumer face brings its own establisher — so the verdict a consumer reads is the verdict the gate applies, `offer` included (the verdict's grant candidate through the gate's own `normalizeReadRootCandidate`). Pinned against the real lane (`runToolGate` + the station over a `NodeExecutionEnv` and a real directory) on ten command shapes × three seats.
+- **The steps between stay private** (`planShellReads`, the establisher, `judgeEstablishedPlan`, `foldShellReadFindings`, `decideShellRead`, `readRootGrantCandidateOf`, `judgeShellReadLexically`): they are the station's working, not its answer, and they are free to move. A fence that needs one should name the grid and why the one call is not enough.
+- **Which `ExecutionEnv` an offline judgment may use** — `docs/INTEGRATION-CORE.md` §9. `NodeExecutionEnv` over a temporary directory is the supported face: the same adapter production runs on. `StubExecutionEnv` reads LEXICALLY (measured: a symlink inside the roots pointing out reads `none`/`vouch` under it where the real env reads `outside_roots`/`mandated`; a pattern it cannot expand reads `unestablishable` where the real env names the targets), and `judgeShellReadLexically` is a third reading again — on a pattern that expands onto such a symlink it vouches. Core ships no in-memory filesystem fixture: a third derivation of `realpath`/glob semantics is a third place for them to be wrong.
+- **What the one call does NOT carry: a deadline.** Bounding an environment-facing wait and substituting a fail-closed verdict is the gate FOLD's policy (`withGateTimeout` + the station's `unanswered` arm), not the station's — the station has never held one on either entry. So a stalling filesystem adapter, or a `boundary.alsoInside` promise that never settles, stalls this call where a run would refuse; `signal` reaches the environment's own `canonicalPath` / `listDir` and is advisory, not a deadline (measured: an already-aborted signal still answers). A consumer wanting the gate's posture races its own deadline and reads the row the fold reads, `SHELL_READ_DECISION.unestablishable[seat]`. Recorded as `KL-1010a`; a second deadline inside the library would be a second place deciding it, and would turn a slow-but-correct filesystem's true answer into a fail-closed one with nobody having asked.
+- **Who is hurt / compensation / consumers.** Nobody: 0 exports removed, 0 changed kind, no gate decision moves, no wire key changes. Deep `dist/tools/fs/*.js` imports keep working. @cli L-467 moves its fence to the root face at its own pace. Wire table: `docs/wire-consumption/unreleased-1010.md`. Export surface: `npm run handoff:diff v7.26.0 HEAD` = +20 / −0.
+
+### Merge-tree adversarial round: two fixes (R1 #1000 × erase; R2 #1014 the traversal grant)
+- **R1.** The erase sweep ends a torn row's lineage for EVERY torn row it removes, and the row always goes (a crash artifact must not outlive a delete that reported success): a mark that names no session is bumped as found; a torn row with NO mark leaves a lost-lineage tombstone (`{__hwm: 0, __gen: 0, __lineage: "lost"}`) in the mark's place — without evidence a minted generation could repeat one a leg still enforces (round 2: an erased-once key's enforced row is already generation 1) — and a torn row whose mark is corrupt leaves that mark as it is. A write to a key carrying the tombstone, or an unreadable row and no mark, is refused (`SessionPolicyError("corrupt")`) rather than guessed; deleting the mark is the operator's restart, as the mark's own contract says. Before the fix a session-less mark was skipped (the recreation continued the enforced generation) and a missing one was minted.
+- **R2 (#1014).** A traversal's root-grant offer names what the environment said the target IS, not what its provenance was: `EstablishedRead.node` (`"directory" | "file"`, set only by the walk — the root by its own listing, a member by whether the walk listed it) and `readRootGrantCandidateOf` grants a file through its containing directory. Before the fix `grep -R needle /abs/file.txt` and a recursive read descending a link onto an outside file offered the FILE as a directory grant (`{ dir: …/report.txt }`); a link onto a directory is still granted as that directory (control). The same derivation serves the gate and `judgeShellRead`, so both faces change together.
+
+
 ## 7.26.0 — 2026-09-21
 
 ### Six root exports the neighbours were hand-copying (#995; additive; +6 exports; @server @cli @client-core)

package/dist/core/permission-rule-provider.js

@@ -121,7 +121,12 @@ function routingWriter(durable, session) {
                 throw e;
             }
             const outcome = await session.apply(scope.sessionId, { behavior: delta.behavior, rule: delta.rule, tool: delta.tool, match: delta.match, command: delta.command, add: delta.add });
-            return "refused" in outcome ? { refused: "session_ended", rev: opts.expectedRev } : { rev: opts.expectedRev };
+            const answered = outcome !== null && typeof outcome === "object" ? outcome : {};
+            const landed = answered.landed === true;
+            const sealed = answered.refused === "session_ended";
+            if (landed !== sealed)
+                return landed ? { rev: opts.expectedRev } : { refused: "session_ended", rev: opts.expectedRev };
+            throw new Error(`the session rule partition answered the ${delta.kind} with ${landed ? "both of its arms at once" : "neither of its two arms"} (landed / refused) — nothing here can say whether the authorization landed; reconcile by reading the session's rules`);
         },
     };
 }

package/dist/core/permission-rule-store.d.ts

@@ -128,6 +128,42 @@ export type RuleWriteOutcome = PutResult | {
     refused: "session_ended";
     rev: number;
 };
+/**
+ * What a caller may conclude from one {@link RuleWriteOutcome} — the arms told apart ONCE, here.
+ *
+ * `unreadable` is the arm the union cannot spell: an `apply` answer is DATA (a foreign backend, a
+ * deserialized reply, a twin compiled against another generation), so "it was not a conflict and not a
+ * refusal" is not a proof that it landed.
+ */
+export type RuleWriteReading = {
+    kind: "landed";
+    rev: number;
+    sync?: RuleSyncLandingReport; /** The landing stands; its report does not. */
+    reportUnreadable?: string;
+} | {
+    kind: "conflict";
+    rev: number;
+} | {
+    kind: "refused";
+    refused: string;
+}
+/** The store ANSWERED, and nothing in the answer says what happened. Never a landing, never a
+ *  confirmed nothing: the write may have committed and lost its acknowledgement, so the reading a
+ *  caller renders from this arm is the indeterminate one and the reconciliation is `list()`. */
+ | {
+    kind: "unreadable";
+    why: string;
+};
+/**
+ * A revision is a COUNT the store advances, so this is the whole of what one may be. Zero is a revision:
+ * a session-scope add lands in a partition that has none of its own and the landing reports the durable
+ * revision unchanged, which is `0` for a durable bucket nothing has written yet.
+ *
+ * Exported because the acceptance kit judges the same thing about a backend's answer, and two copies of
+ * "what a revision is" is exactly the drift the contract-sentence discipline exists to stop.
+ */
+export declare function isRuleRevision(rev: unknown): rev is number;
+export declare function readRuleWriteOutcome(res: RuleWriteOutcome): RuleWriteReading;
 /** Authorization accompanying an add: the redemption that produced it. Carrying the record id makes the
  *  add's logical operation identity checkable at the backend, not just at the caller. A v1 caller
  *  carries `principal`; the local-owner path (design/182 §4.5) carries `owner` instead — never both

package/dist/core/permission-rule-store.js

@@ -5,6 +5,71 @@ import { thrownText } from "./thrown-value.js";
 export function sameRuleOwner(a, b) {
     return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
 }
+export function isRuleRevision(rev) {
+    return typeof rev === "number" && Number.isSafeInteger(rev) && rev >= 0;
+}
+function outcomeWord(value) {
+    if (value === undefined)
+        return "no revision at all";
+    if (value === null)
+        return "a null revision";
+    if (typeof value === "number")
+        return `the number ${String(value)}, which is not a revision`;
+    return `a ${typeof value} where a revision belongs`;
+}
+function isReadableDrop(drop) {
+    if (drop === null || typeof drop !== "object")
+        return false;
+    const dot = drop.dot;
+    if (dot === null || typeof dot !== "object")
+        return false;
+    return typeof dot.actor === "string" && typeof dot.counter === "number" && typeof drop.reason === "string";
+}
+function readSyncReport(sync) {
+    if (sync === undefined)
+        return {};
+    if (sync === null || typeof sync !== "object")
+        return { unreadable: `the landing carried a ${sync === null ? "null" : typeof sync} where its sync report belongs` };
+    for (const member of ["droppedInbound", "quarantined"]) {
+        const value = sync[member];
+        if (value === undefined)
+            continue;
+        if (!Array.isArray(value))
+            return { unreadable: `the landing's sync report carried a ${typeof value} as \`${member}\`, which a reader cannot walk` };
+        const bad = value.findIndex((row) => !isReadableDrop(row));
+        if (bad !== -1)
+            return { unreadable: `the landing's sync report carried a \`${member}\` entry (#${String(bad)}) that is not a drop record, so what was dropped cannot be read` };
+    }
+    return { report: sync };
+}
+export function readRuleWriteOutcome(res) {
+    if (res === null || typeof res !== "object") {
+        return { kind: "unreadable", why: `the store answered ${res === null ? "null" : `a ${typeof res}`} where a write outcome belongs` };
+    }
+    const tagged = res;
+    const refusal = tagged.refused;
+    const conflict = tagged.conflict;
+    if (refusal !== undefined && conflict !== undefined) {
+        return { kind: "unreadable", why: "the store answered a refusal and a decline at once, and an answer that is two arms is not an answer about either" };
+    }
+    if (refusal !== undefined) {
+        return typeof refusal === "string" && refusal !== ""
+            ? { kind: "refused", refused: refusal }
+            : { kind: "unreadable", why: `the store tagged its answer as a refusal and named it with a ${refusal === null ? "null" : typeof refusal}, so which refusal it is cannot be read` };
+    }
+    if (conflict !== undefined) {
+        if (conflict !== true)
+            return { kind: "unreadable", why: `the store tagged its answer as a decline with \`${String(conflict)}\`, which does not say a compare-and-set lost` };
+        return isRuleRevision(tagged.rev)
+            ? { kind: "conflict", rev: tagged.rev }
+            : { kind: "unreadable", why: `the store declined the write with ${outcomeWord(tagged.rev)}, so the revision to re-anchor the next attempt to is unknown` };
+    }
+    if (!isRuleRevision(tagged.rev)) {
+        return { kind: "unreadable", why: `the store answered neither a conflict nor a refusal, and carried ${outcomeWord(tagged.rev)} — a landing reports the revision it committed at, so this answer cannot say whether the write landed` };
+    }
+    const { report, unreadable } = readSyncReport(tagged.sync);
+    return { kind: "landed", rev: tagged.rev, ...(report !== undefined ? { sync: report } : {}), ...(unreadable !== undefined ? { reportUnreadable: unreadable } : {}) };
+}
 export function unknownRuleWriteDeltaError(delta) {
     const kind = delta?.kind;
     return new Error(`the permission-rule store cannot apply a write delta of kind ${escapeForDisclosure(typeof kind === "string" ? kind : String(kind))} — the write face folds exactly four named arms (redemption-add, tighten-add, tighten-delete, sync-join), and an unnamed one is refused rather than read as any of them`);
@@ -405,13 +470,32 @@ function resolveRuleWriter(store) {
         w = writerOf(store);
     }
     catch (err) {
-        return { unavailable: `the permission-rule store's write face could not be acquired (${errText(err)})` };
+        return { unavailable: `the permission-rule store's write face could not be acquired (${errText(err)})`, committed: "unknown" };
     }
-    return w === undefined ? { unavailable: "the resolved permission-rule store has no write face" } : { writer: w };
+    return w === undefined ? { unavailable: "the resolved permission-rule store has no write face", committed: "no" } : { writer: w };
 }
 function ruleIdentityStands(rules, identity) {
     return rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r));
 }
+async function witnessRuleAdd(store, writer, delta) {
+    const identity = { behavior: delta.behavior, rule: delta.rule, scope: delta.scope };
+    const dot = delta.add.dot;
+    try {
+        if (delta.scope.kind === "session") {
+            const view = await store.effective({ sessionId: delta.scope.sessionId });
+            if (view.unreadable !== undefined)
+                return { unreadable: view.unreadable };
+            return { seen: view.rules.some((r) => sameRuleIdentity(r, identity) && r.adds.some((a) => sameDot(a.dot, dot))), rev: view.rev };
+        }
+        const raw = await writer.readRaw();
+        const inRows = raw.rules.some((r) => sameRuleIdentity(r, identity) && r.adds.some((a) => sameDot(a.dot, dot)));
+        const inQuarantine = (raw.quarantined ?? []).some((q) => sameDot(q.add.dot, dot));
+        return { seen: inRows || inQuarantine, rev: raw.rev };
+    }
+    catch (err) {
+        return { unreadable: errText(err) };
+    }
+}
 async function readRuleLiveness(store, identity) {
     try {
         const after = await store.effective();
@@ -448,7 +532,7 @@ export async function removePersistedRule(opts) {
     const store = owner.kind === "local-owner" ? provider.forLocalOwner() : provider.forPrincipal(owner.principal);
     const face = resolveRuleWriter(store);
     if ("unavailable" in face) {
-        return { status: "failed", error: `${face.unavailable} — rules cannot be removed through it`, committed: "no" };
+        return { status: "failed", error: `${face.unavailable} — rules cannot be removed through it`, committed: face.committed };
     }
     const writer = face.writer;
     let snapshot;
@@ -474,30 +558,35 @@ export async function removePersistedRule(opts) {
     const tombstone = { behavior, rule, scope, removedDots, deletedBy };
     let expectedRev = snapshot.rev;
     let lastError = "";
-    let applyThrew = false;
+    let settlement = "no";
     for (let attempt = 0; attempt < REMOVE_MAX_ATTEMPTS; attempt++) {
         try {
-            const res = await writer.apply({ kind: "tighten-delete", tombstone }, { expectedRev });
-            if ("refused" in res) {
-                return { status: "failed", error: `the store refused the tombstone (${res.refused}) — nothing was removed`, committed: "no" };
+            const reading = readRuleWriteOutcome(await writer.apply({ kind: "tighten-delete", tombstone }, { expectedRev }));
+            if (reading.kind === "refused") {
+                return { status: "failed", error: `the store refused the tombstone (${reading.refused}) — nothing was removed`, committed: "no" };
+            }
+            if (reading.kind === "unreadable") {
+                settlement = "unknown";
+                lastError = `the permission-rule store answered the write unreadably: ${reading.why}`;
+                break;
             }
-            if (!("conflict" in res)) {
-                return { status: "removed", rev: res.rev, stillLive: await readRuleLiveness(store, identity) };
+            if (reading.kind === "landed") {
+                return { status: "removed", rev: reading.rev, stillLive: await readRuleLiveness(store, identity) };
             }
-            expectedRev = res.rev;
+            expectedRev = reading.rev;
         }
         catch (err) {
-            applyThrew = true;
+            settlement = "unknown";
             lastError = errText(err);
             break;
         }
     }
-    const reason = applyThrew
+    const reason = settlement === "unknown"
         ? lastError !== ""
             ? lastError
             : "the permission-rule store threw while applying the tombstone, with no message"
         : `optimistic-concurrency retries exhausted after ${REMOVE_MAX_ATTEMPTS} attempts`;
-    const committed = applyThrew ? "unknown" : "no";
+    const committed = settlement;
     try {
         const after = await writer.readRaw();
         const landed = after.tombstones.some((t) => t.deletedBy.actor === tombstone.deletedBy.actor && t.deletedBy.counter === tombstone.deletedBy.counter);
@@ -506,7 +595,7 @@ export async function removePersistedRule(opts) {
         }
         return {
             status: "failed",
-            error: applyThrew
+            error: settlement === "unknown"
                 ? `${reason}; the store retains no tombstone for this removal, which cannot tell a write that never landed from one whose evidence was collected — the outcome is indeterminate, reconcile with list()`
                 : `${reason} (read-back confirms no tombstone was written)`,
             committed,
@@ -515,7 +604,7 @@ export async function removePersistedRule(opts) {
     catch (err) {
         return {
             status: "failed",
-            error: applyThrew
+            error: settlement === "unknown"
                 ? `${reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()`
                 : `${reason}; the read-back also failed (${errText(err)}), but every attempt was answered by the store, so nothing was written`,
             committed,
@@ -555,10 +644,21 @@ export async function landRuleAdd(args) {
         catch (err) {
             return { landed: false, reason: `the permission-rule store refused the write: ${errText(err)}`, committed: "unknown" };
         }
-        if ("refused" in res)
+        const reading = readRuleWriteOutcome(res);
+        if (reading.kind === "refused")
             return { landed: false, reason: SESSION_ENDED_REFUSAL, committed: "no" };
-        if (!("conflict" in res))
-            return { landed: true, rev: res.rev };
+        if (reading.kind === "unreadable")
+            return { landed: false, reason: `the permission-rule store answered the write unreadably: ${reading.why}`, committed: "unknown" };
+        if (reading.kind === "landed") {
+            const witness = await witnessRuleAdd(args.store, args.writer, args.delta);
+            if ("unreadable" in witness) {
+                return { landed: false, reason: `the permission-rule store reported a landing at revision ${String(reading.rev)}, and the read-back that would have witnessed it could not be taken (${witness.unreadable})`, committed: "unknown" };
+            }
+            if (!witness.seen) {
+                return { landed: false, reason: `the permission-rule store reported a landing at revision ${String(reading.rev)}, and a read-back of this add's own dot finds no trace of it — a revision says the ANSWER was well formed, not that a row exists, so nothing here can say the write landed`, committed: "unknown" };
+            }
+            return { landed: true, rev: reading.rev };
+        }
     }
     return { landed: false, reason: `optimistic-concurrency retries exhausted after ${RULE_ADD_MAX_ATTEMPTS} attempts`, committed: "no" };
 }
@@ -592,7 +692,7 @@ export async function addPersistedRule(opts) {
     const store = owner.kind === "local-owner" ? provider.forLocalOwner() : provider.forPrincipal(owner.principal);
     const face = resolveRuleWriter(store);
     if ("unavailable" in face) {
-        return { status: "failed", error: `${face.unavailable} — rules cannot be added through it`, committed: "no" };
+        return { status: "failed", error: `${face.unavailable} — rules cannot be added through it`, committed: face.committed };
     }
     const writer = face.writer;
     const query = scope.kind === "session" ? { sessionId: scope.sessionId } : undefined;

package/dist/core/permission-rule-sync.js

@@ -1,5 +1,5 @@
 import { escapeForDisclosure, isRuleBehavior, parseRuleText } from "./permission-rule-model.js";
-import { applyTombstones, errText, joinFrontiers, joinRuleStates, normalizePersistedRule, ruleSyncVector, sameRuleIdentity, screenRuleSyncState, writerOf, } from "./permission-rule-store.js";
+import { applyTombstones, errText, joinFrontiers, joinRuleStates, normalizePersistedRule, readRuleWriteOutcome, ruleSyncVector, sameRuleIdentity, screenRuleSyncState, writerOf, } from "./permission-rule-store.js";
 import { emitTrace } from "./trace.js";
 export const PERMISSION_RULE_SYNC_PATH = "/v1/permission-rules/sync";
 export const LOCAL_OWNER_UNSYNCABLE_CODE = "permission_rules.local_owner_unsyncable";
@@ -174,11 +174,12 @@ export async function syncPermissionRules(opts) {
                 warnings: [...warnings, `the store refused the sync landing: ${escapeForDisclosure(errText(err))} — nothing landed, the local state is unchanged`],
             });
         }
-        if ("conflict" in res) {
+        const reading = readRuleWriteOutcome(res);
+        if (reading.kind === "conflict") {
             current = await writer.readRaw();
             continue;
         }
-        if ("refused" in res) {
+        if (reading.kind === "refused" || reading.kind === "unreadable") {
             return disclose({
                 ok: false,
                 pushed: { addDots: raw.rules.reduce((n, r) => n + r.adds.length, 0), tombstones: raw.tombstones.length },
@@ -186,7 +187,12 @@ export async function syncPermissionRules(opts) {
                 resurrected: [],
                 dropped,
                 rev: current.rev,
-                warnings: [...warnings, `the store refused the sync landing (${res.refused}) — nothing landed, the local state is unchanged`],
+                warnings: [
+                    ...warnings,
+                    reading.kind === "refused"
+                        ? `the store refused the sync landing (${reading.refused}) — nothing landed, the local state is unchanged`
+                        : `the store answered the sync landing unreadably: ${reading.why} — this round is not reported as landed; re-read before trusting the local state`,
+                ],
             });
         }
         const landedRaw = await writer.readRaw();
@@ -211,7 +217,10 @@ export async function syncPermissionRules(opts) {
         const tombKeyOf = (t) => JSON.stringify([t.behavior, t.rule, t.scope.kind, t.scope.kind === "project" ? t.scope.root : t.scope.kind === "session" ? t.scope.sessionId : null, dotKeyOf(t.deletedBy)]);
         const preTombs = new Set(current.tombstones.map(tombKeyOf));
         const newTombstones = landedRaw.tombstones.filter((t) => !preTombs.has(tombKeyOf(t))).length;
-        const landedReport = res.sync;
+        const landedReport = reading.sync;
+        if (reading.reportUnreadable !== undefined) {
+            warnings.push(`${reading.reportUnreadable} — the join landed, but what it dropped or quarantined cannot be reported from this round`);
+        }
         for (const d of landedReport?.droppedInbound ?? []) {
             if (!dropped.some((x) => x.dot.actor === d.dot.actor && x.dot.counter === d.dot.counter && x.reason === d.reason))
                 dropped.push(d);

package/dist/core/runner/prepare-inherited-gate.d.ts

@@ -41,7 +41,7 @@ import { type HookEnvCapabilities, type Hooks } from "../hooks.js";
 import type { LockedPreflight } from "../locked-config.js";
 import type { OwnOrgAdmissionVerdict } from "../memory-admission.js";
 import type { DelegationContentSafety } from "../memory-engine/delegation-provenance.js";
-import type { SessionPermissionRules } from "../session-policy-store.js";
+import { type SessionPermissionRules } from "../session-policy-store.js";
 import type { SessionStore } from "../session.js";
 import { type OnAsk } from "../tool-policy.js";
 import type { ApproverPosture, RunnerDeps, RuntimeCaps, ShellGateDoctrine, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";

package/dist/core/runner/prepare-inherited-gate.js

@@ -2,6 +2,7 @@ import { forkGovernanceDenial, resolveDelegationEntryCaps } from "../../agents/s
 import { isLiveQuestionFace } from "../ask-question.js";
 import { parentSpecSeatOf } from "../parent-spec-seat.js";
 import { createPreToolUseConstraintPolicy } from "../hooks.js";
+import { continuesLineage } from "../session-policy-store.js";
 import { StubExecutionEnv } from "../stub-env.js";
 import { askApproverIdentity, durableMandateSourceOf } from "../tool-policy.js";
 import { attachRebuiltDenialTrackers, createDenialLimitStop } from "./denial-limit-arms.js";
@@ -21,7 +22,7 @@ export function prepareInheritedGate(input) {
             return [...seedRules];
         const merged = seedRules.map((s) => {
             const live = liveRules.find((l) => l.sessionId === s.sessionId && l.principal === s.principal);
-            const sameLineage = live === undefined || live.gen === undefined || s.gen === undefined || live.gen === s.gen;
+            const sameLineage = live === undefined || continuesLineage(live, s);
             return live !== undefined && sameLineage && live.rev >= s.rev ? live : s;
         });
         const extras = liveRules.filter((l) => !seedRules.some((s) => s.sessionId === l.sessionId && s.principal === l.principal));

package/dist/core/runner/session-rule-policy.d.ts

@@ -1,7 +1,7 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import type { ToolEffect } from "../types.js";
 import { type NamedToolPolicy } from "../tool-policy.js";
-import type { SessionPermissionRules, SessionPolicyStore, StoredSessionRules } from "../session-policy-store.js";
+import { type SessionPermissionRules, type SessionPolicyStore, type StoredSessionRules } from "../session-policy-store.js";
 /** Tool names whose write target is the `file_path`/`path` arg ({@link fileArgPath}).
  *
  *  REF-B3 — the ONE definition of that narrower set. Production consumer today:

package/dist/core/runner/session-rule-policy.js

@@ -1,5 +1,6 @@
 import { canonicalizeTarget, isWinFormPath, pathFamilyOf, writeTargetPath } from "../../tools/fs/safety.js";
 import { createCoarseCommandNamePolicy, namespacedCoveringEntries, namespacedCoveringHit } from "../tool-policy.js";
+import { continuesLineage } from "../session-policy-store.js";
 import { thrownText } from "../thrown-value.js";
 import { ruleDenialSentence } from "../rule-denial-sentence.js";
 import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, gateWaitFailureOf, withGateTimeout } from "../gate-bounded-await.js";
@@ -61,13 +62,11 @@ export function createLiveSessionRules(store, floor, hooks) {
             return enforced;
         }
         if (enforced.rev > 0) {
-            if (live.gen !== undefined && enforced.gen !== undefined) {
-                if (live.gen !== enforced.gen) {
-                    announce(`session ${JSON.stringify(floor.sessionId)} has a rules row of a new lineage (generation ${live.gen}, rev ${live.rev}), which does not continue the row this leg enforces (generation ${enforced.gen})`);
-                    return enforced;
-                }
+            if (!continuesLineage(live, enforced)) {
+                announce(`session ${JSON.stringify(floor.sessionId)} has a rules row of a new lineage (generation ${live.gen}, rev ${live.rev}), which does not continue the row this leg enforces (generation ${enforced.gen})`);
+                return enforced;
             }
-            else if (vanished) {
+            if (vanished && live.gen === undefined) {
                 announce(`session ${JSON.stringify(floor.sessionId)} has a new rules row at rev ${live.rev} after the row this leg enforced was deleted, and its backend carries no lineage to continue it by`);
                 return enforced;
             }
@@ -89,7 +88,7 @@ export function createLiveSessionRules(store, floor, hooks) {
         if (handedRead !== undefined) {
             handed.delete(toolCallId);
             const claimed = await handedRead;
-            if (claimed.rev >= enforced.rev)
+            if (continuesLineage(claimed, enforced) && claimed.rev >= enforced.rev)
                 return claimed;
         }
         const p = read(signal);

package/dist/core/session-policy-store.d.ts

@@ -131,6 +131,24 @@ export declare function normalizeRules(rules: SessionPermissionRules): SessionPe
  * allowDirs: removing confinement, or adding a dir not within some prior dir, loosens (coarse raw containment).
  */
 export declare function loosenReasons(prior: SessionPermissionRules, next: SessionPermissionRules): string[];
+/**
+ * Does row `a` belong to the SAME lineage as row `b` — the one question every reader asks before it compares
+ * two rows' `rev`, asked in ONE place so a `gen` that is ABSENT cannot mean three different things at three
+ * stations. It means what {@link StoredSessionRules.gen} says it means: generation ZERO. A row that spells
+ * `gen: 0` and a row that omits it are therefore the same row's generation, and a row of generation 1 does not
+ * continue either of them — which is the case the readings used to disagree on, each treating absence as
+ * "unknown, so do not judge" and letting a recreated row pass for a continuation of the one it enforced.
+ *
+ * ABSENCE STILL CARRIES ONE OTHER FACT, and it is a different question: a backend that stamps no lineage at
+ * ALL gives its reader no recycle evidence, so a reader that has one of its own (it watched the row vanish)
+ * keeps using it. That test asks whether the FIELD is there, never what it compares to, and it is the caller's
+ * to make — this predicate answers only "same lineage or not".
+ */
+export declare function continuesLineage(a: {
+    gen?: number;
+}, b: {
+    gen?: number;
+}): boolean;
 /** strip any caller-passed `rev` from a rules object so the store is the sole authority on it. */
 export declare function stripRev(rules: SessionPermissionRules): SessionPermissionRules;
 /**

package/dist/core/session-policy-store.js

@@ -69,6 +69,9 @@ export function loosenReasons(prior, next) {
     }
     return reasons;
 }
+export function continuesLineage(a, b) {
+    return (a.gen ?? 0) === (b.gen ?? 0);
+}
 export function stripRev(rules) {
     const { ...rest } = rules;
     delete rest.rev;

package/dist/core/store-contracts/permission-rule-write-contract.js

@@ -1,5 +1,5 @@
 import assert from "node:assert";
-import { PERMISSION_RULE_WRITER } from "../permission-rule-store.js";
+import { PERMISSION_RULE_WRITER, isRuleRevision } from "../permission-rule-store.js";
 import { beginContract } from "./contract-harness.js";
 const GLOBAL = { kind: "global" };
 function add(actor, counter) {
@@ -18,6 +18,15 @@ async function rawShape(part) {
     const tombs = raw.tombstones.map((t) => `${t.behavior}|${t.rule}|${t.deletedBy.actor}#${t.deletedBy.counter}`).sort();
     return JSON.stringify({ rev: raw.rev, dots, tombs });
 }
+function assertDecline(outcome, what) {
+    const answer = (outcome ?? {});
+    assert.equal(answer.conflict, true, `${what} must answer \`conflict: true\` — a decline tagged with anything else is an answer the engine reads as unreadable, so a kit accepting it certifies a backend the engine cannot use`);
+    assert.equal(answer.refused, undefined, `${what} must not wear the refusal tag as well — an answer that is two arms is an answer about neither`);
+}
+function assertRevision(outcome, what) {
+    const rev = outcome?.rev;
+    assert.ok(isRuleRevision(rev), `${what} must carry a revision — a non-negative safe integer — and this answer carried ${rev === undefined ? "none at all" : `a ${typeof rev}`}`);
+}
 export async function permissionRuleWriteContract(hooks) {
     const { run, settle } = beginContract(hooks.runAssertion);
     run("the named arms land, a landing ADVANCES the revision, and a spent revision is ANSWERED (positive control)", async () => {
@@ -27,19 +36,23 @@ export async function permissionRuleWriteContract(hooks) {
         const held = (await part.list()).rev;
         const first = await writer.apply({ kind: "tighten-add", ...IDENTITY, add: a1 }, { expectedRev: held });
         assert.ok(!("conflict" in first) && !("refused" in first), "a well-formed tighten-add must land");
+        assertRevision(first, "the tighten-add landing");
         const afterAdd = await part.list();
         assert.deepEqual(liveDots(afterAdd.rules), new Set([`deny|${IDENTITY.rule}|kit#1`]), "the added dot must be visible through list()");
         assert.ok(afterAdd.rev > held, "a landed write must ADVANCE the revision — a constant one is not a fence, it is a number");
         assert.equal((await part[PERMISSION_RULE_WRITER].readRaw()).rev, afterAdd.rev, "every face must report ONE revision");
         const rawBefore = await rawShape(part);
         const stale = await writer.apply({ kind: "tighten-add", ...IDENTITY, add: add("kit", 2) }, { expectedRev: held });
-        assert.ok("conflict" in stale, "a spent expectedRev must answer `conflict`, not throw and not land");
+        assertDecline(stale, "a spent expectedRev");
+        assertRevision(stale, "the declining conflict");
         const staleDelete = await writer.apply({ kind: "tighten-delete", tombstone: tombstoneFor([a1], { actor: "kit", counter: 8 }) }, { expectedRev: held });
-        assert.ok("conflict" in staleDelete, "a spent expectedRev must answer `conflict` on the delete arm too");
+        assertDecline(staleDelete, "a spent expectedRev on the delete arm");
+        assertRevision(staleDelete, "the declining conflict on the delete arm");
         assert.equal(await rawShape(part), rawBefore, "a declined write must move nothing — rows, tombstones or revision");
         const beforeDelete = (await part.list()).rev;
         const removed = await writer.apply({ kind: "tighten-delete", tombstone: tombstoneFor([a1], { actor: "kit", counter: 9 }) }, { expectedRev: beforeDelete });
         assert.ok(!("conflict" in removed) && !("refused" in removed), "a well-formed tighten-delete must land");
+        assertRevision(removed, "the tighten-delete landing");
         assert.deepEqual(liveDots((await part.list()).rules), new Set(), "the tombstoned dot must leave the live view");
         assert.ok((await part.list()).rev > beforeDelete, "a landed delete must advance the revision too");
         const raw = await part[PERMISSION_RULE_WRITER].readRaw();

package/dist/core/store-contracts/read-back-shape-contract.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The CROSS-STORE read-back rule (`@contract store.read_back_shape_judged`, quoted for integrators in
+ * `docs/INTEGRATION-CORE.md` §5.0) and the acceptance suite that pins it. Kit form as the sibling kits
+ * (see `permission-rule-write-contract.ts`): no test framework, no skip hook.
+ */
+import { type ContractAssertionRunner } from "./contract-harness.js";
+/**
+ * @contract store.read_back_shape_judged — every read a store answers, a single get and an enumeration
+ * alike, judges the SHAPE of what it read before answering: a body that is not the shape this store
+ * writes is CORRUPT, and a corrupt body is answered in the store's own corrupt vocabulary — a loud
+ * refusal, or an absence that carries a disclosure naming the loss — never as an empty set, an empty
+ * object or a default value, because an answer a caller cannot tell apart from "there is nothing here"
+ * turns a recoverable incident into a silent one. Which read-back failures a store TOLERATES (an
+ * enumeration that skips one unreadable row and serves the rest, a torn trailing write read as absent)
+ * is a per-store fact registered beside that store's own contract, never assumed from another store's.
+ */
+export declare const CORRUPT_BODY_FORMS: readonly ["not-an-object", "missing-required", "wrong-type", "torn-json"];
+/** One way a persisted body can fail to be the shape its store writes. */
+export type CorruptBodyForm = (typeof CORRUPT_BODY_FORMS)[number];
+export interface ReadBackShapeSubject {
+    /** Declared ONCE per subject, and only by a backend that keeps no bytes a foreign writer could damage
+     *  (a process-local map holding objects it minted itself). Never per attempt: a planter that cannot
+     *  find bytes it knows exist must FAIL rather than exempt its backend. */
+    readonly unplantable?: string;
+    /** Plant ONE corrupt body of `form`, with `sentinel` inside the planted bytes wherever the form allows
+     *  (that is how clause 3 detects a body handed straight back). No declining return: a backend with no
+     *  bodies declares that at the subject, and a planter that cannot find bytes it knows exist THROWS. */
+    plant: (form: CorruptBodyForm, sentinel: string) => Promise<void>;
+    /** Perform the read under test. THROWING IS AN ANSWER — the loud refusal — and is not a suite failure. */
+    read: () => Promise<unknown>;
+    /** Write ONE well-formed row — clause 1's subject. */
+    seed: () => Promise<void>;
+    close?: () => void;
+}
+export interface StoreReadBackShapeHooks {
+    /** The face under test, named as a reader would name it (`"FileCheckpointStore.get"`). Failure text only. */
+    face: string;
+    /** Open a FRESH, EMPTY store and return its subject. Called once per observation; teardown is `close`. */
+    open: () => Promise<ReadBackShapeSubject>;
+    runAssertion?: ContractAssertionRunner;
+}
+/**
+ * Run the read-back shape suite over ONE read face. Throws (assert) on the first violated clause.
+ *
+ * Clauses: (1) a seeded row and an empty store both ANSWER, answer differently, and the empty answer is
+ * REPRODUCIBLE — a face that throws at everything, answers everything alike, or carries incidental data
+ * (a read id, a timestamp) proves nothing by differing under corruption;
+ * (2) each of the four {@link CORRUPT_BODY_FORMS}, planted, is answered differently from an empty store;
+ * (3) and the answer never contains the planted bytes.
+ *
+ * CEILING: clause 2 proves the corrupt case is DISTINGUISHABLE, not that the distinguishing answer is
+ * right — a face answering one invalid row where a good read answers rows passes. Whether the store then
+ * named the loss correctly is judged by its own section in §5.0, by a person; the four forms are a
+ * fixture set, not the space of corrupt bodies.
+ */
+export declare function storeReadBackShapeContract(hooks: StoreReadBackShapeHooks): Promise<void>;