@sema-agent/core 7.25.1 → 7.26.1

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
@@ -221,6 +257,19 @@ export interface RuleSyncJoinDelta {
  * calling layer, and closes identically for every caller.
  */
 export type RuleWriteDelta = RuleAddDelta | RuleTightenAddDelta | RuleDeleteDelta | RuleSyncJoinDelta;
+/**
+ * The refusal every backend owes a delta whose `kind` is outside {@link RuleWriteDelta} — minted here so
+ * the two bundled backends (and an out-of-repo twin) answer an unnamed operation with ONE sentence
+ * instead of each guessing.
+ *
+ * The parameter is `never` on purpose: the only way to reach it is from a `default` arm the type system
+ * has already proved unreachable, so the factory doubles as the compile-time fence (a fifth arm added to
+ * the union stops satisfying `never` and reds at every backend's switch, naming the missing word). The
+ * runtime half is not decoration — a delta arrives as DATA (a foreign caller, a replayed record, a
+ * deserialized join), and the alternative to throwing is folding an unnamed kind as whichever arm
+ * an if/else chain happens to end with: a write nobody defined, landed under a name nobody checked.
+ */
+export declare function unknownRuleWriteDeltaError(delta: never): Error;
 /**
  * The backend write face. Exported as part of the BACKEND CONTRACT (ruled 2026-08-10) so an
  * out-of-repo store implementation hangs the same face the file backend does, instead of mirroring the
@@ -531,6 +580,22 @@ export declare function ruleStoreChecksum(payload: unknown): Promise<string>;
  */
 export declare const REMOVAL_LIVENESS_WORDS: readonly ["yes", "no", "unknown"];
 export type RemovalLiveness = (typeof REMOVAL_LIVENESS_WORDS)[number];
+/**
+ * What a terminal write FAILURE may claim about the bytes — the failure half of the honesty
+ * {@link RemovalLiveness} keeps on the success half, spelled ONCE and read by every write entry here.
+ *
+ * `"no"` = the store ITSELF answered: a face that cannot write at all, a target the type face refuses,
+ * a read that failed before any write, a refused preflight, an epoch seal, a compare-and-set that lost
+ * every attempt. Each of those is the store saying nothing landed, so saying it is a fact.
+ * `"unknown"` = the apply THREW, which proves nothing either way (a backend can commit and then lose
+ * its acknowledgement), or the read-back that would have settled it could not be taken.
+ *
+ * The word exists because the caller's two branches — retry, or reconcile with `list()` — are not
+ * derivable from the failure PROSE. A consumer reading the strength out of the sentence is parsing a
+ * message written for a person, and every such reader has to be updated by hand when the sentence is.
+ */
+export declare const RULE_WRITE_COMMITTED_WORDS: readonly ["no", "unknown"];
+export type RuleWriteCommitted = (typeof RULE_WRITE_COMMITTED_WORDS)[number];
 /**
  * The result of a removal.
  *
@@ -548,21 +613,32 @@ export type RemoveResult =
     rev: number;
     stillLive: RemovalLiveness;
 }
-/** Nothing to remove — including a repeated delete. No empty tombstone is minted. */
+/** Nothing to remove — including a repeated delete. No empty tombstone is minted. `stillLive` is the
+ *  SAME read-back the `removed` arm reports, taken at the same point in the call ({@link
+ *  readRuleLiveness}): "there was nothing to remove" is a statement about the snapshot this call read,
+ *  and an approval landing after it leaves the rule standing. Both 200-shaped arms therefore carry the
+ *  word, from one source. It is a LATER OBSERVATION, not an atomic absence: `rev` is the revision the
+ *  decision was taken at, the word is what a second look saw, and the store may change again right
+ *  after — `yes` beside a `no-op` is the honest pair, not a contradiction. */
  | {
     status: "no-op";
     rev: number;
+    stillLive: RemovalLiveness;
 }
-/** Terminal failure, in one of two strengths the `error` text distinguishes — word for word the dual of
- *  {@link AddResult}'s. When the STORE answered every attempt (the compare-and-set simply lost), the
- *  read-back confirms nothing was written and the text says so plainly. When the apply THREW, a missing
+/** Terminal failure, in one of two strengths — word for word the dual of {@link AddResult}'s, and
+ *  `committed` is the word for it ({@link RuleWriteCommitted}), so the strength is READ, not parsed out
+ *  of the sentence. When the STORE answered every attempt (the compare-and-set simply lost), nothing
+ *  landed: `committed: "no"`, and the read-back confirms it in the text. When the apply THREW, a missing
  *  tombstone cannot tell a write that never landed from one whose evidence a paired collection erased
  *  (`collectBelowFrontier` recycles a tombstone together with the adds it covered), so that outcome is
- *  reported INDETERMINATE and the caller reconciles with `list()` rather than retrying blind. When the
- *  read-back itself failed, `error` says so and the caller reconciles with `list()` too. */
+ *  `committed: "unknown"`, reported INDETERMINATE, and the caller reconciles with `list()` rather than
+ *  retrying blind. When the read-back itself failed, the word is the one the apply earned — a throw
+ *  leaves it `unknown`, an answered compare-and-set stays `no`, because an unreadable store cannot
+ *  un-answer what the store already said. */
  | {
     status: "failed";
     error: string;
+    committed: RuleWriteCommitted;
 };
 /**
  * Remove a persisted rule.
@@ -602,7 +678,7 @@ export type RuleAddLanding = {
  | {
     landed: false;
     reason: string;
-    committed: "no" | "unknown";
+    committed: RuleWriteCommitted;
 };
 /**
  * Land ONE add — the terminal write both doors take (the consent protocol's redemption and the
@@ -652,10 +728,13 @@ export type AddResult =
  *  survives the tombstone a concurrent removal laid on it — but a sync collection can erase even
  *  that, so a dot it cannot find is reported INDETERMINATE rather than as a confirmed nothing, and
  *  the caller reconciles with `list()` instead of retrying blind (a blind retry mints a fresh dot and
- *  can reinstate a restriction somebody had just removed). */
+ *  can reinstate a restriction somebody had just removed). `committed` ({@link RuleWriteCommitted}) is
+ *  which of the two this is, as a WORD — the landing's own answer, passed through rather than re-derived,
+ *  so this entry and the consent protocol's door cannot disagree about a write they both took. */
  | {
     status: "failed";
     error: string;
+    committed: RuleWriteCommitted;
 };
 /**
  * Add a persisted rule in ONE step, with no approval record.

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

@@ -5,6 +5,75 @@ 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`);
+}
 export const PERMISSION_RULE_WRITER = "__semaPermissionRuleWriter";
 export function writerOf(store) {
     const w = store[PERMISSION_RULE_WRITER];
@@ -394,6 +463,50 @@ export async function ruleStoreChecksum(payload) {
     return `sha256:${createHash("sha256").update(canonicalize(payload), "utf8").digest("hex")}`;
 }
 export const REMOVAL_LIVENESS_WORDS = ["yes", "no", "unknown"];
+export const RULE_WRITE_COMMITTED_WORDS = ["no", "unknown"];
+function resolveRuleWriter(store) {
+    let w;
+    try {
+        w = writerOf(store);
+    }
+    catch (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", 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();
+        if (after.unreadable !== undefined)
+            throw new Error(after.unreadable);
+        return ruleIdentityStands(after.rules, identity) ? "yes" : "no";
+    }
+    catch {
+        return "unknown";
+    }
+}
 const REMOVE_MAX_ATTEMPTS = 8;
 export async function removePersistedRule(opts) {
     const behavior = opts.behavior;
@@ -401,7 +514,7 @@ export async function removePersistedRule(opts) {
     const scope = structuredClone(opts.scope);
     const target = opts.principal;
     if (!isRuleBehavior(behavior)) {
-        return { status: "failed", error: `removePersistedRule: behavior ${escapeForDisclosure(behavior)} is not one of ${["deny", "ask", "allow"].join("/")} — refusing to name a rule identity nothing can carry` };
+        return { status: "failed", error: `removePersistedRule: behavior ${escapeForDisclosure(behavior)} is not one of ${["deny", "ask", "allow"].join("/")} — refusing to name a rule identity nothing can carry`, committed: "no" };
     }
     const identity = { behavior, rule, scope };
     const owner = typeof target === "string" ? { kind: "principal", principal: target } : structuredClone(target);
@@ -410,80 +523,92 @@ export async function removePersistedRule(opts) {
         return {
             status: "failed",
             error: "unsupported.session_scope_store: a session-scope rule cannot be removed through the persisted-store entry — session authorizations live in the session's own overlay and end with the session (design/382 §4.3)",
+            committed: "no",
         };
     }
     if (owner.kind === "local-owner" && provider.forLocalOwner === undefined) {
-        return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be removed through it" };
+        return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be removed through it", committed: "no" };
     }
     const store = owner.kind === "local-owner" ? provider.forLocalOwner() : provider.forPrincipal(owner.principal);
-    const writer = writerOf(store);
-    if (writer === undefined) {
-        return { status: "failed", error: "the resolved permission-rule store has no write face — rules cannot be removed through it" };
+    const face = resolveRuleWriter(store);
+    if ("unavailable" in face) {
+        return { status: "failed", error: `${face.unavailable} — rules cannot be removed through it`, committed: face.committed };
     }
+    const writer = face.writer;
     let snapshot;
     try {
         snapshot = await store.effective();
     }
     catch (err) {
-        return { status: "failed", error: `could not read the permission-rule store: ${errText(err)}` };
+        return { status: "failed", error: `could not read the permission-rule store: ${errText(err)}`, committed: "no" };
     }
     if (snapshot.unreadable !== undefined)
-        return { status: "failed", error: `could not read the permission-rule store: ${snapshot.unreadable}` };
+        return { status: "failed", error: `could not read the permission-rule store: ${snapshot.unreadable}`, committed: "no" };
     const live = snapshot.rules.filter((r) => sameRuleIdentity(r, identity));
     const removedDots = live.flatMap((r) => r.adds.map((a) => a.dot));
     if (removedDots.length === 0)
-        return { status: "no-op", rev: snapshot.rev };
-    const tombstone = { behavior, rule, scope, removedDots, deletedBy: await writer.nextDot() };
+        return { status: "no-op", rev: snapshot.rev, stillLive: await readRuleLiveness(store, identity) };
+    let deletedBy;
+    try {
+        deletedBy = await writer.nextDot();
+    }
+    catch (err) {
+        return { status: "failed", error: `could not mint the removal's delete dot: ${errText(err)}`, committed: "no" };
+    }
+    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` };
+            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 (!("conflict" in res)) {
-                let stillLive;
-                try {
-                    const after = await store.effective();
-                    if (after.unreadable !== undefined)
-                        throw new Error(after.unreadable);
-                    stillLive = after.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) ? "yes" : "no";
-                }
-                catch {
-                    stillLive = "unknown";
-                }
-                return { status: "removed", rev: res.rev, stillLive };
+            if (reading.kind === "unreadable") {
+                settlement = "unknown";
+                lastError = `the permission-rule store answered the write unreadably: ${reading.why}`;
+                break;
             }
-            expectedRev = res.rev;
+            if (reading.kind === "landed") {
+                return { status: "removed", rev: reading.rev, stillLive: await readRuleLiveness(store, identity) };
+            }
+            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 = 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);
         if (landed) {
-            return { status: "removed", rev: after.rev, stillLive: applyTombstones(after.rules, after.tombstones).some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) ? "yes" : "no" };
+            return { status: "removed", rev: after.rev, stillLive: ruleIdentityStands(applyTombstones(after.rules, after.tombstones), identity) ? "yes" : "no" };
         }
         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,
         };
     }
     catch (err) {
-        return { status: "failed", error: `${reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()` };
+        return {
+            status: "failed",
+            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,
+        };
     }
 }
 const RULE_ADD_MAX_ATTEMPTS = 8;
@@ -519,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" };
 }
@@ -532,41 +668,43 @@ export async function addPersistedRule(opts) {
     const scope = structuredClone(opts.scope);
     const target = opts.principal;
     if (!isRuleBehavior(behavior)) {
-        return { status: "failed", error: `addPersistedRule: behavior ${escapeForDisclosure(behavior)} is not one of ${["deny", "ask", "allow"].join("/")} — refusing to name a rule identity nothing can carry` };
+        return { status: "failed", error: `addPersistedRule: behavior ${escapeForDisclosure(behavior)} is not one of ${["deny", "ask", "allow"].join("/")} — refusing to name a rule identity nothing can carry`, committed: "no" };
     }
     if (behavior === "allow") {
         return {
             status: "failed",
             error: "addPersistedRule: an allow cannot be written through this entry — a standing approval is a person's yes and takes a consent record (prepare → confirm → redeem); this entry writes the tightening direction (deny/ask) only",
+            committed: "no",
         };
     }
     if (!isValidConsentScope(scope)) {
-        return { status: "failed", error: `addPersistedRule: ${escapeForDisclosure(JSON.stringify(scope))} is not a valid rule scope — refusing to write a row nothing can read back` };
+        return { status: "failed", error: `addPersistedRule: ${escapeForDisclosure(JSON.stringify(scope))} is not a valid rule scope — refusing to write a row nothing can read back`, committed: "no" };
     }
     const parsed = parseRuleText(ruleText, behavior);
     if ("reject" in parsed)
-        return { status: "failed", error: `addPersistedRule: ${parsed.reject.code}: ${parsed.reject.message}` };
+        return { status: "failed", error: `addPersistedRule: ${parsed.reject.code}: ${parsed.reject.message}`, committed: "no" };
     const identity = { behavior, rule: parsed.rule.rule, scope };
     const owner = typeof target === "string" ? { kind: "principal", principal: target } : structuredClone(target);
     const provider = opts.provider;
     if (owner.kind === "local-owner" && provider.forLocalOwner === undefined) {
-        return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be added through it" };
+        return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be added through it", committed: "no" };
     }
     const store = owner.kind === "local-owner" ? provider.forLocalOwner() : provider.forPrincipal(owner.principal);
-    const writer = writerOf(store);
-    if (writer === undefined) {
-        return { status: "failed", error: "the resolved permission-rule store has no write face — rules cannot be added through it" };
+    const face = resolveRuleWriter(store);
+    if ("unavailable" in face) {
+        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;
     let snapshot;
     try {
         snapshot = await store.effective(query);
     }
     catch (err) {
-        return { status: "failed", error: `could not read the permission-rule store: ${errText(err)}` };
+        return { status: "failed", error: `could not read the permission-rule store: ${errText(err)}`, committed: "no" };
     }
     if (snapshot.unreadable !== undefined)
-        return { status: "failed", error: `could not read the permission-rule store: ${snapshot.unreadable}` };
+        return { status: "failed", error: `could not read the permission-rule store: ${snapshot.unreadable}`, committed: "no" };
     if (snapshot.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)))
         return { status: "no-op", rev: snapshot.rev };
     let dot;
@@ -574,7 +712,7 @@ export async function addPersistedRule(opts) {
         dot = await writer.nextDot();
     }
     catch (err) {
-        return { status: "failed", error: `could not mint the add's dot: ${errText(err)}` };
+        return { status: "failed", error: `could not mint the add's dot: ${errText(err)}`, committed: "no" };
     }
     const landing = await landRuleAdd({
         store,
@@ -593,7 +731,7 @@ export async function addPersistedRule(opts) {
     if (landing.landed)
         return { status: "added", rev: landing.rev, dot };
     if (landing.committed === "no")
-        return { status: "failed", error: landing.reason };
+        return { status: "failed", error: landing.reason, committed: landing.committed };
     try {
         let rev;
         let rows;
@@ -613,10 +751,10 @@ export async function addPersistedRule(opts) {
             quarantinedRows.some((q) => sameDot(q.add.dot, dot));
         return stood
             ? { status: "added", rev, dot }
-            : { status: "failed", error: `${landing.reason}; the store retains no trace of this add, which cannot tell a write that never landed from one whose evidence was collected — the outcome is indeterminate, reconcile with list()` };
+            : { status: "failed", error: `${landing.reason}; the store retains no trace of this add, which cannot tell a write that never landed from one whose evidence was collected — the outcome is indeterminate, reconcile with list()`, committed: landing.committed };
     }
     catch (err) {
-        return { status: "failed", error: `${landing.reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()` };
+        return { status: "failed", error: `${landing.reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()`, committed: landing.committed };
     }
 }
 export function errText(err) {
@@ -666,35 +804,44 @@ export class InMemoryDurableRulePartition {
             delta = structuredClone(delta);
             if (opts.expectedRev !== this.rev)
                 return { conflict: true, rev: this.rev };
-            if (delta.kind === "redemption-add") {
-                assertWriteDeltaScopeDurable(delta);
-                assertRedemptionNotQuarantined(this.quarantinedRows, delta);
-                this.rules = foldDelta(this.rules, delta);
-            }
-            else if (delta.kind === "tighten-add") {
-                assertWriteDeltaScopeDurable(delta);
-                this.rules = foldDelta(this.rules, delta);
-            }
-            else if (delta.kind === "tighten-delete") {
-                assertWriteDeltaScopeDurable(delta);
-                assertDeleteDeltaCarriesNoAdd(delta);
-                this.tombstones = [...this.tombstones, delta.tombstone];
-            }
-            else {
-                const { next, report } = applySyncJoin({
-                    actor: this.actor,
-                    counter: this.counter,
-                    rules: this.rules,
-                    tombstones: this.tombstones,
-                    quarantined: this.quarantinedRows,
-                    ...(this.observedVector !== undefined ? { observedVector: this.observedVector } : {}),
-                }, delta, this.now());
-                this.rules = next.rules;
-                this.tombstones = next.tombstones;
-                this.quarantinedRows = next.quarantined;
-                this.observedVector = next.observedVector;
-                this.rev += 1;
-                return { rev: this.rev, sync: report };
+            switch (delta.kind) {
+                case "redemption-add": {
+                    assertWriteDeltaScopeDurable(delta);
+                    assertRedemptionNotQuarantined(this.quarantinedRows, delta);
+                    this.rules = foldDelta(this.rules, delta);
+                    break;
+                }
+                case "tighten-add": {
+                    assertWriteDeltaScopeDurable(delta);
+                    this.rules = foldDelta(this.rules, delta);
+                    break;
+                }
+                case "tighten-delete": {
+                    assertWriteDeltaScopeDurable(delta);
+                    assertDeleteDeltaCarriesNoAdd(delta);
+                    this.tombstones = [...this.tombstones, delta.tombstone];
+                    break;
+                }
+                case "sync-join": {
+                    const { next, report } = applySyncJoin({
+                        actor: this.actor,
+                        counter: this.counter,
+                        rules: this.rules,
+                        tombstones: this.tombstones,
+                        quarantined: this.quarantinedRows,
+                        ...(this.observedVector !== undefined ? { observedVector: this.observedVector } : {}),
+                    }, delta, this.now());
+                    this.rules = next.rules;
+                    this.tombstones = next.tombstones;
+                    this.quarantinedRows = next.quarantined;
+                    this.observedVector = next.observedVector;
+                    this.rev += 1;
+                    return { rev: this.rev, sync: report };
+                }
+                default: {
+                    const unhandled = delta;
+                    throw unknownRuleWriteDeltaError(unhandled);
+                }
             }
             this.rev += 1;
             return { rev: this.rev };

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);