@sema-agent/core 5.21.0 → 5.22.0

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

@@ -0,0 +1,186 @@
+import assert from "node:assert";
+import { collectBelowFrontier, joinRuleStates, ruleSyncVector } from "../permission-rule-store.js";
+import { beginContract } from "./contract-harness.js";
+const GLOBAL = { kind: "global" };
+function add(actor, counter, origin = "user") {
+    return { dot: { actor, counter }, origin, createdAt: "2026-01-01T00:00:00.000Z" };
+}
+function rule(text, adds, scope = GLOBAL) {
+    const m = /^Bash\((.+?)(:\*)?\)$/.exec(text);
+    if (m === null || m[1] === undefined)
+        throw new Error(`contract fixture rule "${text}" is not a Bash(...) form`);
+    return { rule: text, tool: "Bash", match: m[2] !== undefined ? "prefix" : "exact", command: m[1], scope, adds };
+}
+function tomb(text, removed, deletedBy, scope = GLOBAL) {
+    return {
+        rule: text,
+        scope,
+        removedDots: removed.map(([actor, counter]) => ({ actor, counter })),
+        deletedBy: { actor: deletedBy[0], counter: deletedBy[1] },
+    };
+}
+function state(rules = [], tombstones = []) {
+    return { rules, tombstones };
+}
+function liveDots(s) {
+    const out = new Set();
+    for (const r of s.rules) {
+        const removed = s.tombstones.filter((t) => t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
+        for (const a of r.adds) {
+            if (!removed.some((d) => d.actor === a.dot.actor && d.counter === a.dot.counter))
+                out.add(`${r.rule}|${a.dot.actor}#${a.dot.counter}`);
+        }
+    }
+    return out;
+}
+function sameScope(a, b) {
+    return a.kind === "global" ? b.kind === "global" : b.kind === "project" && a.root === b.root;
+}
+function allDots(s) {
+    return new Set(s.rules.flatMap((r) => r.adds.map((a) => `${r.rule}|${a.dot.actor}#${a.dot.counter}`)));
+}
+export async function permissionRuleSyncContract(hooks = {}) {
+    const join = hooks.join ?? joinRuleStates;
+    const collect = hooks.collect ?? collectBelowFrontier;
+    const vector = hooks.vector ?? ruleSyncVector;
+    const { run, settle } = beginContract(hooks.runAssertion);
+    const samples = () => [
+        state(),
+        state([rule("Bash(ls)", [add("a", 1)])]),
+        state([rule("Bash(ls)", [add("b", 1)]), rule("Bash(git status)", [add("b", 2)])]),
+        state([rule("Bash(ls)", [add("a", 1)])], [tomb("Bash(ls)", [["a", 1]], ["a", 2])]),
+        state([rule("Bash(pwd)", [add("c", 5)], { kind: "project", root: "/repo" })], [tomb("Bash(date)", [["d", 9]], ["c", 6])]),
+    ];
+    run("join is idempotent: a ⊔ a = a (M11)", async () => {
+        for (const s of samples())
+            assert.deepStrictEqual(join(s, s), join(s, join(s, s)), "a ⊔ a must equal (a ⊔ a) ⊔ a");
+        for (const s of samples())
+            assert.deepStrictEqual(liveDots(join(s, s)), liveDots(s), "a ⊔ a must not change the live view");
+    });
+    run("join is commutative: a ⊔ b = b ⊔ a", async () => {
+        const pool = samples();
+        for (const a of pool)
+            for (const b of pool)
+                assert.deepStrictEqual(join(a, b), join(b, a));
+    });
+    run("join is associative and order/repetition independent (M12)", async () => {
+        const [, a, b, c] = samples();
+        assert.ok(a && b && c);
+        const one = join(join(a, b), c);
+        const two = join(a, join(b, c));
+        const three = join(join(c, a), join(b, a));
+        assert.deepStrictEqual(one, two);
+        assert.deepStrictEqual(one, three);
+    });
+    run("M1: a single-sided add propagates", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1)])]), state());
+        assert.ok(liveDots(merged).has("Bash(ls)|a#1"));
+    });
+    run("M2: a multi-dot delete covers every observed dot", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1), add("a", 2)])], [tomb("Bash(ls)", [["a", 1], ["a", 2]], ["a", 3])]), state());
+        assert.strictEqual(liveDots(merged).size, 0, "both observed dots must be dead");
+        assert.strictEqual(merged.tombstones.length, 1);
+        assert.strictEqual(merged.tombstones[0]?.removedDots.length, 2, "the tombstone must carry BOTH observed dots");
+    });
+    run("M3: concurrent approvals of the same text coexist under their own dots", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1)])]), state([rule("Bash(ls)", [add("b", 1)])]));
+        assert.deepStrictEqual(liveDots(merged), new Set(["Bash(ls)|a#1", "Bash(ls)|b#1"]));
+        assert.strictEqual(merged.rules.length, 1, "one logical rule, two adds — not two rule rows");
+    });
+    run("M4: add-wins — an add the deleter never observed survives the tombstone", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1)])], [tomb("Bash(ls)", [["a", 1]], ["a", 2])]), state([rule("Bash(ls)", [add("b", 7)])]));
+        assert.deepStrictEqual(liveDots(merged), new Set(["Bash(ls)|b#7"]), "dot a#1 dead, unobserved b#7 alive");
+    });
+    run("M5: deletes on both sides union to cover everything", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1)])], [tomb("Bash(ls)", [["a", 1]], ["a", 2])]), state([rule("Bash(ls)", [add("b", 7)])], [tomb("Bash(ls)", [["b", 7]], ["b", 8])]));
+        assert.strictEqual(liveDots(merged).size, 0);
+    });
+    run("M6: a deliberate re-add under a NEW dot survives the old tombstone", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1), add("a", 3)])], [tomb("Bash(ls)", [["a", 1]], ["a", 2])]), state());
+        assert.deepStrictEqual(liveDots(merged), new Set(["Bash(ls)|a#3"]));
+    });
+    run("M7: a double delete is idempotent — distinct deletedBy tombstones both stand, semantics equal", async () => {
+        const a = state([rule("Bash(ls)", [add("a", 1)])], [tomb("Bash(ls)", [["a", 1]], ["a", 2])]);
+        const b = state([rule("Bash(ls)", [add("a", 1)])], [tomb("Bash(ls)", [["a", 1]], ["b", 5])]);
+        const merged = join(a, b);
+        assert.strictEqual(merged.tombstones.length, 2, "two delete intents, two identities — neither is dropped");
+        assert.strictEqual(liveDots(merged).size, 0);
+        assert.deepStrictEqual(join(a, b), join(b, a));
+    });
+    run("M8: partially-observed deletes union to full coverage — each tombstone honest about its own view", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1), add("a", 2)])], [tomb("Bash(ls)", [["a", 1], ["a", 2]], ["a", 3])]), state([rule("Bash(ls)", [add("a", 1)])], [tomb("Bash(ls)", [["a", 1]], ["b", 1])]));
+        assert.strictEqual(liveDots(merged).size, 0, "the union of observations must cover both dots");
+    });
+    run("M9: provenance rides each add and follows the surviving dot", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1, "imported-cc")])], [tomb("Bash(ls)", [["a", 1]], ["a", 2])]), state([rule("Bash(ls)", [add("b", 7, "user")])]));
+        const survivor = merged.rules.find((r) => r.rule === "Bash(ls)");
+        assert.ok(survivor);
+        const liveAdds = survivor.adds.filter((x) => !merged.tombstones.some((t) => t.removedDots.some((d) => d.actor === x.dot.actor && d.counter === x.dot.counter)));
+        assert.strictEqual(liveAdds.length, 1);
+        assert.strictEqual(liveAdds[0]?.origin, "user", "the display origin must be the SURVIVING add's own, not a folded one");
+    });
+    run("M10: replaying the same dot is deduplicated by identity", async () => {
+        const merged = join(state([rule("Bash(ls)", [add("a", 1)])]), state([rule("Bash(ls)", [add("a", 1)])]));
+        assert.strictEqual(merged.rules[0]?.adds.length, 1);
+    });
+    run("M13: a tombstone whose (rule, scope) is locally absent is kept — arriving before its add is legal", async () => {
+        const merged = join(state(), state([], [tomb("Bash(ls)", [["a", 1]], ["a", 2])]));
+        assert.strictEqual(merged.tombstones.length, 1);
+        const then = join(merged, state([rule("Bash(ls)", [add("a", 1), add("a", 4)])]));
+        assert.deepStrictEqual(liveDots(then), new Set(["Bash(ls)|a#4"]), "the pre-arrived tombstone must cover a#1 when it lands");
+    });
+    run("tombstone-union (r1-F3): same identity, differing removedDots ⇒ the union, both orders", async () => {
+        const a = state([], [tomb("Bash(ls)", [["a", 1]], ["a", 9])]);
+        const b = state([], [tomb("Bash(ls)", [["a", 2]], ["a", 9])]);
+        const ab = join(a, b);
+        assert.strictEqual(ab.tombstones.length, 1, "same (rule, scope, deletedBy) is ONE identity");
+        assert.deepStrictEqual(new Set(ab.tombstones[0]?.removedDots.map((d) => `${d.actor}#${d.counter}`)), new Set(["a#1", "a#2"]), "the union — a one-sided pick can drop an observed removal");
+        assert.deepStrictEqual(ab, join(b, a));
+    });
+    run("metadata re-projection (r2-F2): a record whose stored fields contradict its rule text is refused, both orders", async () => {
+        const forged = { rule: "Bash(ls)", tool: "Bash", match: "prefix", command: "rm -rf /", scope: GLOBAL, adds: [add("z", 1)] };
+        const clean = state([rule("Bash(git status)", [add("a", 1)])]);
+        const ab = join(state([forged]), clean);
+        const ba = join(clean, state([forged]));
+        assert.ok(!allDots(ab).has("Bash(ls)|z#1"), "the forged record must not survive the join");
+        assert.deepStrictEqual(ab, ba, "refusal must preserve commutativity");
+        assert.ok(allDots(ab).has("Bash(git status)|a#1"), "refusing one record must not disturb the rest");
+    });
+    run("single-validator door: an illegal rule shape (bare-interpreter prefix) cannot ride a join", async () => {
+        const merged = join(state([rule("Bash(node:*)", [add("z", 1)])]), state());
+        assert.strictEqual(allDots(merged).size, 0, "Bash(node:*) must be refused by the shared validator inside the join");
+    });
+    run("identity keys are collision-free: roots and actors containing spaces keep DISTINCT tombstone identities, and the covered add stays dead through an identity join", async () => {
+        const scopeA = { kind: "project", root: "/x" };
+        const scopeB = { kind: "project", root: "/x a" };
+        const s = state([rule("Bash(ls)", [add("v", 1)], scopeA), rule("Bash(ls)", [add("w", 1)], scopeB)], [
+            { rule: "Bash(ls)", scope: scopeA, removedDots: [{ actor: "v", counter: 1 }], deletedBy: { actor: "a 1", counter: 2 } },
+            { rule: "Bash(ls)", scope: scopeB, removedDots: [{ actor: "w", counter: 1 }], deletedBy: { actor: "1", counter: 2 } },
+        ]);
+        const merged = join(s, state());
+        assert.strictEqual(merged.tombstones.length, 2, "two distinct delete intents must both survive — a colliding key folds one away");
+        assert.strictEqual(liveDots(merged).size, 0, "both covered adds must stay dead");
+        assert.deepStrictEqual(join(merged, merged), merged, "idempotence must hold with space-carrying roots/actors");
+    });
+    run("state vector: max over add dots ∪ deletedBy ∪ removedDots (§5.1)", async () => {
+        const v = vector(state([rule("Bash(ls)", [add("a", 3)])], [tomb("Bash(git status)", [["a", 7], ["b", 2]], ["c", 4])]));
+        assert.deepStrictEqual(v, { a: 7, b: 2, c: 4 });
+    });
+    run("paired collection: a fully-below tombstone leaves WITH its covered adds; a partial one stays (§5.1)", async () => {
+        const s = state([rule("Bash(ls)", [add("a", 1)]), rule("Bash(pwd)", [add("a", 2), add("b", 9)])], [tomb("Bash(ls)", [["a", 1]], ["a", 3]), tomb("Bash(pwd)", [["a", 2], ["b", 9]], ["a", 4])]);
+        const { state: out, collectedTombstones } = collect(s, { a: 5 });
+        assert.strictEqual(collectedTombstones, 1, "only the fully-below pair is collectable (b#9 is above the frontier)");
+        assert.ok(!allDots(out).has("Bash(ls)|a#1"), "the covered add leaves WITH its tombstone — never one without the other");
+        assert.ok(allDots(out).has("Bash(pwd)|b#9"), "an above-frontier dot must never be collected");
+        assert.strictEqual(out.tombstones.length, 1, "the partially-below tombstone stays");
+        assert.deepStrictEqual(liveDots(out), liveDots(s));
+    });
+    run("collection + rejoin does not resurrect: the recycled pair stays gone through further joins", async () => {
+        const s = state([rule("Bash(ls)", [add("a", 1)])], [tomb("Bash(ls)", [["a", 1]], ["a", 2])]);
+        const { state: collected } = collect(s, { a: 2 });
+        const rejoined = join(collected, collected);
+        assert.strictEqual(liveDots(rejoined).size, 0);
+        assert.strictEqual(allDots(rejoined).size, 0, "neither the add nor the tombstone may reappear from a self-join");
+    });
+    await settle();
+}

package/dist/core/task-notification.d.ts

@@ -82,8 +82,11 @@ export interface TaskNotificationPayload {
     recentSteps?: import("../agents/subagent-steps.js").SubagentStep[];
     /** Residual lane D (core half) — files the child mutated with edit counts. Background-agent lane only. */
     editedFiles?: import("../agents/subagent-steps.js").SubagentEditedFile[];
-    /** Residual lane E — `true` when the child can be revived via SendMessage (retained + not user-stopped).
-     *  Lets the parent decide continue-vs-restart without trial-and-error. Background-agent lane only. */
+    /** Residual lane E — `true` when the child can be revived via SendMessage: a live retained session that
+     *  was not killed, OR a NAMED durable row that no USER stop closed (a parent teardown / reap / host
+     *  death is what the durable revival lane recovers from). Judged by the revival ladder's own
+     *  preconditions, so the claim and the next SendMessage agree. Lets the parent decide
+     *  continue-vs-restart without trial-and-error. Background-agent lane only. */
     resumable?: boolean;
     /** P1-3(黑板 [1920]/[1921]/[1924]/[1925], cli/server 商定项) — a cross-channel correlation key for
      *  ONE completion event. The same task's completion fans out across several independent read faces

package/dist/core/task-registry-agent.d.ts

@@ -311,7 +311,7 @@ export declare function reviveBackgroundAgentLane(core: DurableAgentCore, id: st
     cycle: number;
 } | {
     ok: false;
-    reason: "not_found" | "still_running";
+    reason: "not_found" | "still_running" | "recycling";
 }>;
 /** S2b RB-27② — settle a REVIVED cycle (cycle-stamped: a stale cycle's late settle is a no-op so
  *  it can never flip a newer revived cycle back to terminal / clear its channel). */

package/dist/core/task-registry-agent.js

@@ -216,6 +216,7 @@ export async function reapDurableAgentsLane(core, scope, deps, policy) {
                 continue;
             }
             rowsReaped++;
+            core.reapedHandles.add(r.handle);
             if (deps.mailbox !== undefined) {
                 try {
                     await deps.mailbox.drop(scope, r.handle);
@@ -235,6 +236,7 @@ export async function reapDurableAgentsLane(core, scope, deps, policy) {
         }
         finally {
             core.reapingHandles.delete(r.handle);
+            core.reapedHandles.delete(r.handle);
         }
     }
     return { rowsReaped, sessionsReleased, skippedNoSessions };
@@ -919,11 +921,13 @@ async function rollbackRevivalClaim(store, claim) {
     }
 }
 export async function reviveBackgroundAgentLane(core, id, access, abort) {
-    if (core.reapingHandles.has(id) || core.claimingHandles.has(id))
-        return { ok: false, reason: "not_found" };
     const handle = core.handles.get(id);
     if (!handle || handle.type !== "background_agent" || !canAccess(handle, access))
         return { ok: false, reason: "not_found" };
+    if (core.reapedHandles.has(id))
+        return { ok: false, reason: "not_found" };
+    if (core.reapingHandles.has(id) || core.claimingHandles.has(id))
+        return { ok: false, reason: "recycling" };
     if (handle.status === "running" || handle.status === "pending")
         return { ok: false, reason: "still_running" };
     if (handle.status === "parked")

package/dist/core/task-registry-shared.d.ts

@@ -773,8 +773,9 @@ export declare function closestName(query: string, candidates: Iterable<string>)
  *  missing axis here is a broken invariant, answered with denial, never a pass. */
 export declare function canAccess(handle: SemaTaskHandle, access: TaskAccess): boolean;
 /** design/157 B13 二期(B13 档预调研 §4.2/§4.3 定稿)— the durable-agent lane's widened core seam.
- *  Extends {@link RegistryCore} with EXACTLY the 5 extra members the AGENT lane's `this.*` census
- *  reached (73 处/9 成员,扣车道内互调后落在这 5 个上,见 B13 档「二期细察补充」)。
+ *  Extends {@link RegistryCore} with the extra members the AGENT lane's `this.*` census reached
+ *  (73 处/9 成员,扣车道内互调后落在 5 个上,见 B13 档「二期细察补充」;`reapedHandles` 是后加的
+ *  第 6 个——reap 窗口的后半段,见其自身注释)。
  *  `durableAgentWrite`/`ensureDurableHeartbeat`/`settleBackgroundAgent` are NOT here — they are lane
  *  members themselves (车道内直接函数调用;类上只留转发或不留)。The class satisfies this via the
  *  same cached-view field, upgraded with lazy getter/setter proxies (an IIFE capturing `this`) so
@@ -783,6 +784,12 @@ export declare function canAccess(handle: SemaTaskHandle, access: TaskAccess): b
 export interface DurableAgentCore extends RegistryCore {
     readonly writerId: string;
     readonly reapingHandles: Set<string>;
+    /** The SECOND half of the reap window: ids whose durable row the sweep has already DELETED under its
+     *  rev guard, still inside the lifecycle fence while the sweep drops the mailbox and releases the
+     *  session. The fence must hold across that cleanup, but the row is gone from the moment the delete
+     *  wins, and the two halves owe a caller opposite answers — "this clears on its own, send again"
+     *  versus "it is gone, relaunch". A subset of `reapingHandles`, cleared with it. */
+    readonly reapedHandles: Set<string>;
     readonly claimingHandles: Set<string>;
     /** get/set proxy — `ensureDurableHeartbeatLane` both reads AND writes the timer slot. */
     durableHeartbeatTimer: ReturnType<typeof setInterval> | undefined;

package/dist/core/task-registry.d.ts

@@ -273,7 +273,7 @@ export declare class TaskRegistry {
         cycle: number;
     } | {
         ok: false;
-        reason: "not_found" | "still_running";
+        reason: "not_found" | "still_running" | "recycling";
     }>;
     settleRevivedAgent(id: string, cycle: number, outcome: {
         status: "completed" | "failed" | "killed";
@@ -324,15 +324,21 @@ export declare class TaskRegistry {
      *  the session is released under an ADMITTED resume, and the revive's queued write poisons on
      *  "gone"). Membership is synchronous on both sides, with three readers (the `claimingHandles` twin
      *  below carries the same fence set): reap marks BEFORE its terminal check, a revival lane refuses
-     *  while marked (the row is being recycled — not_found is the honest answer), and the terminal-handle
+     *  while marked (the row is being recycled), and the terminal-handle
      *  GC skips a marked id instead of evicting it. */
     private reapingHandles;
+    /** The post-delete half of the window above (see {@link DurableAgentCore.reapedHandles}): the sweep's
+     *  guarded delete has WON, and the fence is still held while the mailbox is dropped and the session
+     *  released. The fence's readers are unchanged — this only splits what a refused revival is TOLD,
+     *  since a caller advised to retry a row that no longer exists would retry forever. */
+    private reapedHandles;
     /** design/151 §7.3 (F-8) — handles a revival lane is CURRENTLY claiming (between the claim-CAS
      *  decision and the revive registration/rollback). BOTH lanes are writers: the tier-3 SendMessage
      *  claim, and (since the retained revive started claiming its own row) the in-process retained-revive
      *  path, which holds the mark across its store round trip. Synchronous membership on both sides, the
      *  `reapingHandles` twin, with three readers: the reap sweep skips a mid-claim row (its rev is about
-     *  to move), the sibling revival lane refuses one (`reviveBackgroundAgent` not_found), and the
+     *  to move), the sibling revival lane refuses one (`reviveBackgroundAgent` recycling — a transient
+     *  hold, told apart from a row that is actually gone), and the
      *  terminal-handle GC skips it — so the revival lanes, the reaper and the GC can never adjudicate the
      *  same handle concurrently in-process. */
     private claimingHandles;

package/dist/core/task-registry.js

@@ -116,6 +116,7 @@ export class TaskRegistry {
             pokeBgQuiescence: (owner) => self.pokeBgQuiescence(owner),
             get writerId() { return self.writerId; },
             get reapingHandles() { return self.reapingHandles; },
+            get reapedHandles() { return self.reapedHandles; },
             get claimingHandles() { return self.claimingHandles; },
             get durableHeartbeatTimer() { return self.durableHeartbeatTimer; },
             set durableHeartbeatTimer(v) { self.durableHeartbeatTimer = v; },
@@ -233,6 +234,7 @@ export class TaskRegistry {
     }
     writerId = randomBytes(8).toString("hex");
     reapingHandles = new Set();
+    reapedHandles = new Set();
     claimingHandles = new Set();
     durableHeartbeatTimer;
     mintTaskId(type) {

package/dist/core/tool-policy.d.ts

@@ -44,6 +44,12 @@ export interface ToolCallRequest {
      * when a policy is invoked directly (outside a Runner). A NORMAL-ask escalation policy reads it; a SAFETY
      * ask (egress / irreversible) ignores it and ALWAYS asks (invariant #2 stays structural — core mints
      * `irreversible_ask` for safety tools regardless of any budget).
+     *
+     * ⚖️ SCOPE (A-005.13, ruled 2026-08-09): this snapshot is PER-RUN — it is the ledger of the run whose
+     * gate is asking, NEVER the ledger of the run that authored the policy. A policy inherited down the
+     * delegation chain (`InheritedGate.parentConstraints`) therefore self-limits against each CHILD's own
+     * fresh ledger; the ancestor's counts do not travel (declared design — see the chain field's A-005.13
+     * note for the reasoning and the closure-state alternative).
      */
     budget?: {
         /**
@@ -60,8 +66,11 @@ export interface ToolCallRequest {
         suspendCount: number;
     };
 }
-/** Where a decision came from, for audit (design/37). */
-export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier" | "persisted_rule";
+/** Where a decision came from, for audit (design/37). `"sandbox"` (F-012 L2) marks an allow the
+ *  sandbox-admission leg resolved: the deployment declared an isolated execution env, every surviving
+ *  ask on the call was engine-classified sandbox-local, and the call crosses no declared boundary —
+ *  disclosed durably as `permission.sandbox_admitted`. */
+export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier" | "persisted_rule" | "sandbox";
 /**
  * WHO (or what) ENDED an approval — the machine-readable twin of a settlement's human-readable text,
  * so a consumer tells "a person decided this" from "nobody answered" without prose-matching a sentence.
@@ -164,7 +173,116 @@ export declare function decisionText(d: PermissionResult): string | undefined;
  */
 export interface ToolPolicy {
     check(req: ToolCallRequest, signal?: AbortSignal): PermissionResult | Promise<PermissionResult>;
+    /**
+     * The policy's CONSTRAINT PROJECTION — its deterministic DENY-verdict half expressed as pure data
+     * (F-012 L1), so a delegation chain / durable checkpoint can freeze what this policy refuses without
+     * carrying the live closure. Optional: a policy without one is OPAQUE to the projection plane (its
+     * live closure keeps the resume re-supply contract it has today). Built-in factories in this module
+     * attach one where the deny half IS data (name allow/deny lists, shell command-name lists);
+     * a custom closure policy simply opts out.
+     *
+     * The projection is a SUBSET contract, never a replacement: executing it yields every deny the
+     * data half implies, and says nothing about the policy's live remainder (asks, approvals,
+     * rewrites). `requiresLiveRemainder` states explicitly whether such a remainder exists — "has a
+     * projection" ≠ "fully projectable", and consumers deciding whether a frozen projection COMPLETELY
+     * describes the policy must read that bit, not the field's presence.
+     */
+    readonly projection?: ToolPolicyProjection;
 }
+/**
+ * One deterministic DENY component of a {@link ToolPolicyProjection} (F-012 L1). All fields are plain
+ * serializable data — a component round-trips JSON/`structuredClone` unchanged, which is what lets a
+ * chain of them persist on a checkpoint and be re-executed verbatim on resume.
+ *
+ *  - `tool_deny`: deny any call whose toolName is in `names`.
+ *  - `tool_allowlist`: deny any call whose toolName is NOT in `names`.
+ *  - `shell_command`: for calls to the named shell `tools`, parse the leading command name and deny
+ *    per `deny`/`allow` lists; `unmatchedAction`/`unparseableAction` say whether the projection may
+ *    speak for those arms (`"deny"`) or must stay silent (`"none"` — the live policy's ask arm owns
+ *    them). Non-shell tools are out of scope (no opinion).
+ */
+export type ToolPolicyProjectionComponent = {
+    kind: "tool_deny";
+    names: readonly string[];
+} | {
+    kind: "tool_allowlist";
+    names: readonly string[];
+} | {
+    kind: "shell_command";
+    tools: readonly string[];
+    deny: readonly string[];
+    allow?: readonly string[];
+    /** Verdict for a parsed command name outside `allow` (only meaningful when `allow` is present). */
+    unmatchedAction: "deny" | "none";
+    /** Verdict for a command string this projection cannot parse (compound/missing command). */
+    unparseableAction: "deny" | "none";
+};
+/**
+ * The deterministic data half of a {@link ToolPolicy} (F-012 L1): ordered deny components plus the
+ * explicit live-remainder bit. See {@link ToolPolicy.projection} for the contract.
+ */
+export interface ToolPolicyProjection {
+    readonly components: readonly ToolPolicyProjectionComponent[];
+    /**
+     * `true` when the policy has behavior BEYOND these components (an ask arm, an approval callback,
+     * a rewrite) — the projection then freezes only the deny half and the live policy must still ride
+     * the resume re-supply channel for the rest. `false` = the components plus "allow otherwise" ARE
+     * the whole policy (fully projectable — e.g. a plain name allow/deny policy).
+     */
+    readonly requiresLiveRemainder: boolean;
+}
+/**
+ * Execute a persisted {@link ToolPolicyProjection} against a call (F-012 L1): returns the first
+ * component's deny, or `undefined` when the projection has no opinion (it is deny-only by
+ * construction — never an allow, never an ask). This is what a durable RESUME runs instead of
+ * trusting a re-supplied policy's execution half for the frozen deny data: the projection persisted
+ * at suspend is the authority for what the chain refused, whatever a re-supplied closure claims.
+ */
+export declare function checkToolPolicyProjection(projection: Pick<ToolPolicyProjection, "components">, req: {
+    toolName: string;
+    args: unknown;
+}): Extract<PermissionResult, {
+    action: "deny";
+}> | undefined;
+/**
+ * One entry of the persisted constraint-chain topology (F-012 L1): either a layer's projection
+ * content, or an explicit OPAQUE placeholder for a layer that exports none. The placeholder is
+ * load-bearing — the chain digest binds the ORDERED topology (layer boundaries included), so an
+ * opaque layer's position is part of what a resume re-supply must reproduce.
+ *
+ * F-012 (codex round 12): each entry ALSO carries the serializable DECISION-CHAIN METADATA posture —
+ * whether the layer was classifier-armed (`autoModeArmed`) and its durable-mandate / content-mandate
+ * flags. The digest binds these, so a cross-process resume re-supplying a same-shape chain whose
+ * projections match but whose classifier was DROPPED (or whose mandate posture changed) — a
+ * version-skew / reconfiguration widening — is rejected pre-CAS. The metadata is NOT read by
+ * {@link checkToolPolicyProjection} (execution reads only `components`); it exists purely to be
+ * digested. The frozen closures themselves (approver, decider) are non-serializable and stay outside
+ * the digest — the re-supply trust contract governs their identity — but their PRESENCE/posture is
+ * bound so a re-supply cannot silently shed a decision-chain layer.
+ */
+export type ConstraintChainEntryMeta = {
+    /** True iff the layer carried a frozen auto-mode classifier (`autoMode`). */
+    autoModeArmed?: true;
+    durableMandate?: true;
+    contentMandate?: true;
+};
+export type ConstraintChainEntry = ConstraintChainEntryMeta & ({
+    opaque: true;
+} | {
+    components: readonly ToolPolicyProjectionComponent[];
+    requiresLiveRemainder: boolean;
+});
+/** Project one policy into its chain entry (opaque placeholder when it exports no projection),
+ *  carrying the layer's decision-chain metadata posture for the digest (round 12). */
+export declare function constraintChainEntryOf(policy: ToolPolicy, meta?: ConstraintChainEntryMeta): ConstraintChainEntry;
+/**
+ * Content digest over an ordered constraint chain (F-012 L1) — the durable half's anti-tamper anchor.
+ * Binds the chain TOPOLOGY (order, layer boundaries, opaque placeholders) and each projection's full
+ * content; version-prefixed (`cpv1:`) so a digest computed under different projection semantics can
+ * never false-match. Replaces the count-only re-supply contract: two chains of equal length with
+ * different frozen deny data now digest differently.
+ */
+export declare function constraintChainDigest(chain: readonly ConstraintChainEntry[]): string;
 /**
  * Refuse a decision that speaks the retired `reason` dialect (RB-479-B①, tripwire ruled 2026-08-03).
  *