@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/side-query.js

@@ -1,6 +1,10 @@
 import { ensureToolTurnInvariants } from "../internal/llm.js";
 import { resolveTaskModel } from "./roles.js";
+import { runRenderer } from "../prompt-assembly/renderers.js";
+import { roleBaseOf } from "../prompt-assembly/role-base.js";
+import { effectiveTraitsOf, readModelPromptTraits, selectorsOf } from "../prompt-assembly/select.js";
 import { readDegradation } from "../brain/degrading.js";
+import { extractErrorCode } from "../brain/errors.js";
 import { cacheFamilyOf, uncachedInputTokensOf } from "./runner/usage-accounting.js";
 import { providerReportedModel } from "./message-utils.js";
 import { providerToolCallId } from "../brain/tool-call-id.js";
@@ -8,6 +12,11 @@ function normalizeSideQueryUsage(model, u) {
     const input = uncachedInputTokensOf(cacheFamilyOf(model), u);
     return input === u.input ? u : { ...u, input };
 }
+const NO_RUN_FACTS = Object.freeze({ policyEnabled: false, hooksEnabled: false, isolationEnabled: false, withinTaskCompactionEnabled: false, supervisorEnabled: false, orchestrationEnabled: false, awarenessEnabled: false, goalEnabled: false, worktreeIsolated: false, teammateEnabled: false });
+function sideQueryRoleBase(role, model, tools) {
+    const selectors = selectorsOf(NO_RUN_FACTS, { role }, undefined, effectiveTraitsOf(readModelPromptTraits(model), undefined));
+    return runRenderer("role-base", { facts: NO_RUN_FACTS, toolNames: (tools ?? []).map((t) => t.name) }, selectors)?.text;
+}
 export async function runSideQuery(spec, deps) {
     if (!Array.isArray(spec.messages) || spec.messages.length === 0) {
         throw new Error("sideQuery requires a non-empty messages array");
@@ -39,7 +48,8 @@ export async function runSideQuery(spec, deps) {
         }
         return { role: "user", content: m.content, timestamp };
     };
-    const effectiveSystemPrompt = spec.systemPrompt ?? resolved.systemPrompt;
+    const decided = roleBaseOf([spec.systemPrompt !== undefined ? { systemPrompt: spec.systemPrompt } : undefined, resolved]);
+    const effectiveSystemPrompt = decided?.systemPrompt ?? (decided?.promptRole !== undefined ? sideQueryRoleBase(decided.promptRole, resolved.model, spec.tools) : undefined);
     const context = {
         ...(effectiveSystemPrompt !== undefined ? { systemPrompt: effectiveSystemPrompt } : {}),
         messages: ensureToolTurnInvariants(spec.messages.map(normalize)).messages,
@@ -71,6 +81,7 @@ export async function runSideQuery(spec, deps) {
     const degraded = readDegradation(msg);
     const servedModel = typeof msg.model === "string" && msg.model.length > 0 ? msg.model : resolved.model.id;
     const reportedModel = providerReportedModel(msg);
+    const errorCode = extractErrorCode(msg.errorMessage);
     return {
         text,
         toolCalls,
@@ -82,5 +93,8 @@ export async function runSideQuery(spec, deps) {
         ...(msg.usageMissing === true ? { usageMissing: true } : {}),
         stopReason: msg.stopReason,
         ...(msg.errorMessage !== undefined ? { errorMessage: msg.errorMessage } : {}),
+        ...(msg.stopReason === "error" && errorCode !== undefined ? { errorCode } : {}),
+        ...(msg.errorKind !== undefined ? { errorKind: msg.errorKind } : {}),
+        ...(msg.inputTooLongRuledOut === true ? { inputTooLongRuledOut: true } : {}),
     };
 }

package/dist/core/skill-grant.d.ts

@@ -199,6 +199,10 @@ export declare class SkillGrantTable {
     private readonly rowKeys;
     private mounted;
     private activations;
+    private scopes;
+    /** State the leg's skill scopes (the mods bus's record): every activation this table writes opens its skill's scope there. A
+     *  table never told opens nothing (the resume's pre-claim probe). */
+    bindScopes(scopes: Pick<import("./mods/spec-seats.js").SkillScopes, "open">): void;
     /** State where the run's mounted names are read (prepare, once the roster is assembled): a skill's entries are read against
      *  them when seeded and whenever the skill is activated. A table never told reads the grammar alone. */
     bindMountedNames(mounted: MountedToolNames): void;
@@ -211,8 +215,9 @@ export declare class SkillGrantTable {
      *  capture re-supplied beside the frozen rows that already carry it. Keyed on the ROW, not the skill: a definition that
      *  changed across a park writes its new rows when it is activated again. */
     private hold;
-    /** Write a skill's rows (rows already held are not held twice) — or none, refused with {@link SKILL_DENY_UNREADABLE_CODE},
-     *  when its `disallowed-tools` holds an entry that reads as nothing. Returns the allow entries that read as nothing. */
+    /** Write a skill's rows (rows already held are not held twice) and open its scope — or neither, refused with
+     *  {@link SKILL_DENY_UNREADABLE_CODE}, when its `disallowed-tools` holds an entry that reads as nothing. Returns the allow
+     *  entries that read as nothing. */
     activate(skill: SkillGrantSource, origin: SkillGrantOrigin): readonly SkillInertEntry[];
     /** Seed portable records (a delegated child's capture, a resumed leg's frozen rows): a record the model wrote keeps that
      *  word, every other record seeds under `origin` — `user` is written only from this leg's own spec, never seeded. Each

package/dist/core/skill-grant.js

@@ -180,6 +180,10 @@ export class SkillGrantTable {
     rowKeys = new Set();
     mounted;
     activations;
+    scopes;
+    bindScopes(scopes) {
+        this.scopes = scopes;
+    }
     bindMountedNames(mounted) {
         this.mounted = mounted;
     }
@@ -203,6 +207,7 @@ export class SkillGrantTable {
             throw skillDenyUnreadable(skill.name, unreadDeny, "activation");
         for (const row of rows)
             this.hold(row);
+        this.scopes?.open(skill.name);
         return inert;
     }
     seed(records, origin) {

package/dist/core/skills-directory.js

@@ -23,13 +23,15 @@ const SEQUENCE_NOT_AN_ENTRY = "its `- name` entries are not indented alike";
 const SEQUENCE_NOT_A_NAME = "an entry is not a plain or quoted name (nested, mapping, anchor, tag, flow and block-scalar entries, and number, boolean and null entries, are not read)";
 const VALUE_IS_A_MAPPING = "its value is a mapping or holds one (`key: value` or `{…}`), not a list of names";
 const VALUE_NOT_A_STRING = "its value is a number or a boolean, not a list of names";
+const YAML_ALIAS = 'it holds a YAML alias (an unquoted `*<name>`), which the reader does not resolve — quote a value or entry that is meant as a tool-name pattern ("*Edit")';
+const YAML_ALIAS_START = /^\*[^\s,[\]{}]/;
 const QUOTE_NOT_CLOSED = "a quote in it does not close";
 const flowNotClosed = (opener) => `its \`${opener}\` does not close within its lines`;
 const strayLine = (line) => `a flush-left line that is no key follows it (line ${line})`;
 const NOT_A_KEY_LINE = "a flush-left frontmatter line is a key — letters, digits, `_` and `-`, or one quoted scalar — then `:` and a blank or nothing; a comment starts with `#`";
 const PARENS_NOT_ONE_ZONE = "an entry's parentheses are not one group that closes it (a `(` that does not close, a `)` with no `(`, or text after the closing `)` — `\\(` / `\\)` are a rule's own text)";
 const KEY_REPEATED = "the key is written more than once";
-const notARule = (position) => `entry ${position} is no rule spelling (a tool name of ASCII letters, digits and \`_ - . : *\`, starting with a letter, a digit or \`_\`, then at most one parenthesized rule)`;
+const notARule = (position) => `entry ${position} is no rule spelling (a tool name of ASCII letters, digits and \`_ - . : *\`, starting with a letter, a digit, \`_\` or \`*\`, then at most one parenthesized rule)`;
 const keyInsideValue = (inner) => `an indented line under its value is a mapping key, \`${inlineUntrusted(inner, 64)}\` — YAML reads no key there (under a value that is not a mapping, or indented less than the nested block it follows)`;
 const toolListOutOfPlace = (inner) => `it holds the tool-list key \`${inner}\` — a tool list is read only as a key of the frontmatter, written flush left; anywhere else its list would be lost`;
 const isBlank = (ch) => ch === " " || ch === "\t";
@@ -434,7 +436,9 @@ function scanValue(text, seat) {
         const written = trimBlanks(plain);
         plain = "";
         breaks = 0;
-        if (opened.length > 0 || seat === "item") {
+        if (YAML_ALIAS_START.test(written))
+            cut.fail(YAML_ALIAS);
+        else if (opened.length > 0 || seat === "item") {
             if (YAML_NULL.test(written) || YAML_BOOL_OR_NUMBER.test(written))
                 cut.fail(SEQUENCE_NOT_A_NAME);
         }

package/dist/core/store-contracts/checkpoint-store-contract.d.ts

@@ -39,7 +39,17 @@ export declare const POLICY_ALLOW: Extract<ResumeOutcome, {
  * The full cross-backend contract for {@link CheckpointStore} — the SAME assertions for every
  * backend. Entries are a 1:1 port of the vitest originals (assertion semantics unchanged).
  */
-export declare function checkpointStoreContract(make: () => CheckpointStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function checkpointStoreContract(make: () => CheckpointStore, runAssertion?: ContractAssertionRunner, 
+/** `sessionHeads` = the map the binding's stores read their session heads from (their `deleteSessionCheckpoints` guard): the kit writes
+ *  the heads its delete case needs into it. Required only to judge a store that offers `deleteSessionCheckpoints`.
+ *  `holders` = the set of current claim holders the binding's store judges by (its `holderIsCurrent`, or the claim table it
+ *  reads): the kit adds and removes holders in it. Required only to judge a store that declares `fence.holder`. */
+options?: {
+    readonly sessionHeads?: Map<string, {
+        readonly owner: string | null;
+    }>;
+    readonly holders?: Set<string>;
+}): Promise<void>;
 /** Seed the canonical listByScope fixture into `store` and return the sorted summaries. Compare the
  *  result against {@link EXPECTED_LISTBYSCOPE_SUMMARIES} (deep equality) to prove the backend's
  *  summary projection matches the reference — the caller owns the comparison (harness-specific). */

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -1,6 +1,6 @@
 import { strict as assert } from "node:assert";
 import { executionVerdict } from "../checkpoint-execution-record.js";
-import { MAX_PENDING_STEER_ENTRIES, mintCheckpointToken, readPendingSteerQueue, } from "../checkpoint-store.js";
+import { MAX_PENDING_STEER_ENTRIES, checkpointIndexFacts, mintCheckpointToken, readPendingSteerQueue, } from "../checkpoint-store.js";
 import { checkpointFrom } from "../pause-registry.js";
 import { beginContract } from "./contract-harness.js";
 export function createCheckpointFixture(over = {}) {
@@ -48,7 +48,7 @@ export const POLICY_ALLOWED = Object.freeze({
     origin: "policy",
 });
 export const POLICY_ALLOW = { ...ALLOW, hostDecision: { decidedBy: "policy", approver: "unattended_class_answer" }, gateOutcome: POLICY_ALLOWED };
-export async function checkpointStoreContract(make, runAssertion) {
+export async function checkpointStoreContract(make, runAssertion, options = {}) {
     const { run, settle } = beginContract(runAssertion);
     run("kit prerequisites: reopen/setPendingSteer/listByScope are implemented (REQUIRED by this kit)", async () => {
         const probe = make();
@@ -308,7 +308,7 @@ export async function checkpointStoreContract(make, runAssertion) {
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
-    run("the approval object's members: a row's identity + face group and its targets (capabilityId/contractId/shapeDigest/implementationRevision + family/pathTarget/names + targets) survive the round-trip verbatim; an absent group stays absent", async () => {
+    run("the approval object's members: a row's identity + face group and its targets (capabilityId/contractId/shapeDigest/implementationRevision + family/pathTarget/hostTarget/names + targets + engineMounted) survive the round-trip verbatim; an absent group stays absent", async () => {
         const store = make();
         const carried = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-carried" });
         const group = {
@@ -320,6 +320,7 @@ export async function checkpointStoreContract(make, runAssertion) {
             pathTarget: { param: "destination", aliases: ["path"], access: "create", skillScopeEligible: true },
             names: ["AcmeWrite", "acme_write"],
             targets: { protective: "/srv/work/out.txt", declared: "/srv/work/out.txt" },
+            engineMounted: true,
         };
         Object.assign(carried.pendingAction, group);
         const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-bare" });
@@ -331,6 +332,14 @@ export async function checkpointStoreContract(make, runAssertion) {
         const bareBack = (await store.get(bare.token)).pendingAction;
         for (const k of Object.keys(group))
             assert.equal(k in bareBack, false, `an absent ${k} must stay OMITTED (a pre-388 row reads name-only, never a partial face)`);
+        const fetchRow = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-host" });
+        Object.assign(fetchRow.pendingAction, { ...group, family: "web", pathTarget: undefined, targets: undefined, hostTarget: { param: "url" } });
+        delete fetchRow.pendingAction.pathTarget;
+        delete fetchRow.pendingAction.targets;
+        await store.put(fetchRow.token, fetchRow);
+        const fetchBack = (await store.get(fetchRow.token)).pendingAction;
+        assert.deepEqual(fetchBack.hostTarget, { param: "url" }, "the row's hostTarget must survive the round-trip verbatim (dropped, a resume of the parked fetch reads a face that moved and is vetoed, and its pre-claim recheck judges the catalog's slot for the NAME)");
+        assert.equal("hostTarget" in bareBack, false, "an absent hostTarget must stay OMITTED");
     });
     run("#457 previewWithheld three-form matrix: a row's spelling survives + projects; absent stays absent; an out-of-contract spelling reads as absent", async () => {
         const store = make();
@@ -436,6 +445,162 @@ export async function checkpointStoreContract(make, runAssertion) {
         await assert.rejects(store.recordExecutionOutcome(cp.token, cp.scope, EXECUTED_ALLOW), (e) => e.code === "checkpoint.execution_outcome_conflict", "a person's record for a row the policy decided is a different record");
         assert.deepEqual((await store.get(cp.token)).executionOutcome, POLICY_ALLOWED);
     });
+    run("index facts: every row's checkpointIndexFacts survive the round trip — an approval gate with a card, a word outside the card set, no card, a descriptor, a deadline, the directional-control bit; a tool-less park", async () => {
+        const store = make();
+        const descriptor = { severity: 4, axes: { egress: true }, toolName: "Write" };
+        const laterWord = createCheckpointFixture({ gate: { kind: "human", reason: "approve", toolName: "Write" } });
+        Object.assign(laterWord.gate, { approvalCard: "card-of-a-later-engine" });
+        const rows = [
+            createCheckpointFixture({ gate: { kind: "human", reason: "approve", toolName: "Write", approvalCard: "file-write", riskDescriptor: descriptor }, deadline: 1_900_000_000_000 }),
+            createCheckpointFixture({ gate: { kind: "irreversible_ask", reason: "send", toolName: "Write", approvalCard: "question" } }),
+            laterWord,
+            createCheckpointFixture({ pendingAction: { kind: "tool_approval", origin: "policy", toolCallId: "call-b", toolName: "Write", args: {}, boundInputHash: "hb", hasBidiControls: true, batchToolCallIds: ["call-b"], completedCallIds: [] } }),
+            createCheckpointFixture({ gate: { kind: "resource_limit", reason: "turns" }, pendingAction: { kind: "resource_limit", reason: "turns" }, deadline: 1_900_000_000_001 }),
+        ];
+        for (const cp of rows) {
+            await store.put(cp.token, cp);
+            const back = await store.get(cp.token);
+            assert.ok(back !== null, "a row put is a row read");
+            assert.deepEqual(checkpointIndexFacts(back), checkpointIndexFacts(cp), `the index facts of the row ${cp.gate.kind} came back different`);
+        }
+    });
+    run("listOverdue (when offered): pending rows of every scope past the cutoff, one facet per call (facetOf, the question card included), deadline-then-token order, the bound cut with a cursor that resumes without a gap or a repeat, a bad query refused", async () => {
+        const store = make();
+        if (store.listOverdue === undefined)
+            return;
+        const human = (over) => createCheckpointFixture(over);
+        const question = createCheckpointFixture({ token: "ov-q", deadline: 1_000, gate: { kind: "human", reason: "ask", toolName: "Write", approvalCard: "question" } });
+        const rows = [
+            human({ token: "ov-a2", deadline: 1_500 }),
+            human({ token: "ov-a1", deadline: 1_000, scope: "tenant-b" }),
+            human({ token: "ov-a0", deadline: 1_000 }),
+            question,
+            createCheckpointFixture({ token: "ov-r", deadline: 900, gate: { kind: "resource_limit", reason: "turns" }, pendingAction: { kind: "resource_limit", reason: "turns" } }),
+            createCheckpointFixture({ token: "ov-t", deadline: 900, gate: { kind: "task_done" }, pendingAction: { kind: "task_done" } }),
+            human({ token: "ov-late", deadline: 5_000 }),
+            human({ token: "ov-none" }),
+            human({ token: "ov-done", deadline: 1_000 }),
+        ];
+        for (const cp of rows)
+            await store.put(cp.token, cp);
+        await store.resolve("ov-done", "tenant-a", ALLOW);
+        const tokensOf = (page) => page.rows.map((r) => r.token);
+        assert.deepEqual(tokensOf(await store.listOverdue({ cutoff: 2_000, facet: "A" })), ["ov-a0", "ov-a1", "ov-a2"], "facet A = the approval rows past the cutoff, every scope, (deadline, token) ascending");
+        assert.deepEqual(tokensOf(await store.listOverdue({ cutoff: 2_000, facet: "B" })), ["ov-r", "ov-q"], "facet B = the abandonment rows, the question parked under an approval gate kind among them");
+        assert.deepEqual(tokensOf(await store.listOverdue({ cutoff: 2_000, facet: "-" })), ["ov-t"], "facet - = the non-gate park");
+        const first = await store.listOverdue({ cutoff: 2_000, facet: "A", limit: 2 });
+        assert.deepEqual(tokensOf(first), ["ov-a0", "ov-a1"], "the bound cuts the page");
+        assert.ok(first.next !== undefined, "a cut page carries the next cursor");
+        const second = await store.listOverdue({ cutoff: 2_000, facet: "A", limit: 2, after: first.next });
+        assert.deepEqual(tokensOf(second), ["ov-a2"], "the cursor resumes after the last row of the page before");
+        assert.equal(second.next, undefined, "the last page carries no cursor");
+        assert.equal((await store.get(question.token)).status, "pending", "read-only: the listing mutates nothing");
+        for (const bad of [{ cutoff: 2_000, facet: "A", limit: 0 }, { cutoff: 2_000, facet: "A", limit: 501 }, { cutoff: 2_000, facet: "A", limit: 1.5 }, { cutoff: Number.NaN, facet: "A" }, { cutoff: 2_000, facet: "C" }, { cutoff: 2_000, facet: "A", scope: "tenant-a" }]) {
+            await assert.rejects(store.listOverdue(bad), (e) => e.code === "config.invalid_argument", `refused loudly: ${JSON.stringify(bad)}`);
+        }
+    });
+    run("listBySession (when offered): one session's rows in any status narrowed by status / gate kinds / tool call / scope / createdSince, oldest or newest first, the bound cut with a resuming cursor, an empty gate-kind list matching nothing, a bad query refused", async () => {
+        const store = make();
+        if (store.listBySession === undefined)
+            return;
+        const s = "sess-list";
+        const rows = [
+            createCheckpointFixture({ token: "ls-1", sessionId: s, createdAt: 1 }),
+            createCheckpointFixture({ token: "ls-2", sessionId: s, createdAt: 2, pendingAction: { kind: "tool_approval", origin: "policy", toolCallId: "call-9", toolName: "Write", args: {}, boundInputHash: "h9", boundGrantAbsence: "not_bindable", batchToolCallIds: ["call-9"], completedCallIds: [] } }),
+            createCheckpointFixture({ token: "ls-3", sessionId: s, createdAt: 3, gate: { kind: "resource_limit", reason: "turns" }, pendingAction: { kind: "resource_limit", reason: "turns" } }),
+            createCheckpointFixture({ token: "ls-4", sessionId: s, createdAt: 4, scope: "tenant-b" }),
+            createCheckpointFixture({ token: "ls-x", sessionId: "another-session", createdAt: 1 }),
+        ];
+        for (const cp of rows)
+            await store.put(cp.token, cp);
+        await store.resolve("ls-1", "tenant-a", ALLOW);
+        await store.expire("ls-3", "tenant-a");
+        const tokensOf = (page) => page.rows.map((r) => {
+            const read = r;
+            assert.equal(read.kind, "row", "a readable row is answered as a row");
+            return read.checkpoint.token;
+        });
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s })), ["ls-1", "ls-2", "ls-3", "ls-4"], "every status, every scope, oldest first; another session's row never");
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s, order: "newest" })), ["ls-4", "ls-3", "ls-2", "ls-1"]);
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s, status: "pending", gateKinds: ["human"], order: "newest", limit: 1 })), ["ls-4"], "the session's newest pending row of a gate kind");
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s, status: "pending", gateKinds: ["human"], scope: "tenant-a" })), ["ls-2"]);
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s, gateKinds: [] })), [], "an empty gate-kind list matches no row");
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s, status: "expired", limit: 1 })), ["ls-3"]);
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s, toolCallId: "call-3" })), ["ls-1", "ls-4"], "the rows that parked this tool call (a park with no tool call never matches)");
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s, toolCallId: "call-9", status: "pending" })), ["ls-2"]);
+        assert.deepEqual(tokensOf(await store.listBySession({ sessionId: s, createdSince: 3 })), ["ls-3", "ls-4"]);
+        const first = await store.listBySession({ sessionId: s, limit: 3, order: "newest" });
+        assert.deepEqual(tokensOf(first), ["ls-4", "ls-3", "ls-2"]);
+        assert.ok(first.next !== undefined, "a cut page carries the next cursor");
+        const second = await store.listBySession({ sessionId: s, limit: 3, order: "newest", after: first.next });
+        assert.deepEqual(tokensOf(second), ["ls-1"]);
+        assert.equal(second.next, undefined);
+        const read = (await store.listBySession({ sessionId: s, toolCallId: "call-9" })).rows[0];
+        read.checkpoint.status = "expired";
+        assert.equal((await store.get("ls-2")).status, "pending", "a listed row is a copy: mutating it changes nothing stored");
+        for (const bad of [{ sessionId: "" }, { sessionId: s, limit: 101 }, { sessionId: s, limit: 0 }, { sessionId: s, status: "done" }, { sessionId: s, gateKinds: ["nope"] }, { sessionId: s, order: "latest" }, { sessionId: s, createdSince: Number.POSITIVE_INFINITY }, { sessionId: s, owner: "x" }]) {
+            await assert.rejects(store.listBySession(bad), (e) => e.code === "config.invalid_argument", `refused loudly: ${JSON.stringify(bad)}`);
+        }
+    });
+    run("deleteSessionCheckpoints (when offered): every row of the session, in any status, only when the session row exists and its owner equals the guard's (null-safe); otherwise nothing is deleted and the answer is 0", async () => {
+        const store = make();
+        if (store.deleteSessionCheckpoints === undefined)
+            return;
+        const heads = options.sessionHeads;
+        assert.ok(heads !== undefined, "a store offering deleteSessionCheckpoints is judged with the binding's `sessionHeads` (the map its session head read reads)");
+        heads.set("del-owned", { owner: "alice" });
+        heads.set("del-anon", { owner: null });
+        const owned = [
+            createCheckpointFixture({ sessionId: "del-owned" }),
+            createCheckpointFixture({ sessionId: "del-owned" }),
+            createCheckpointFixture({ sessionId: "del-owned" }),
+            createCheckpointFixture({ sessionId: "del-owned", scope: "tenant-b" }),
+        ];
+        const anon = createCheckpointFixture({ sessionId: "del-anon" });
+        const orphan = createCheckpointFixture({ sessionId: "del-no-row" });
+        const bystander = createCheckpointFixture({ sessionId: "del-other" });
+        for (const cp of [...owned, anon, orphan, bystander])
+            await store.put(cp.token, cp);
+        await store.resolve(owned[1].token, owned[1].scope, ALLOW);
+        await store.expire(owned[2].token, owned[2].scope);
+        assert.equal(await store.deleteSessionCheckpoints("del-owned", { owner: "bob" }), 0, "another owner deletes nothing");
+        assert.equal(await store.deleteSessionCheckpoints("del-owned", { owner: null }), 0, "the anonymous guard does not match an owned session");
+        assert.equal(await store.deleteSessionCheckpoints("del-no-row", { owner: null }), 0, "no session row deletes nothing");
+        assert.ok((await store.get(orphan.token)) !== null && (await store.get(owned[0].token)) !== null, "a refused guard leaves every row");
+        assert.equal(await store.deleteSessionCheckpoints("del-owned", { owner: "alice" }), 4, "the owner's guard deletes the session's rows — pending, resolved, expired, in every scope");
+        for (const cp of owned)
+            assert.equal(await store.get(cp.token), null);
+        assert.equal(await store.deleteSessionCheckpoints("del-anon", { owner: null }), 1, "the anonymous guard deletes an anonymous session's rows");
+        assert.ok((await store.get(bystander.token)) !== null, "another session's row stays");
+        assert.equal(await store.deleteSessionCheckpoints("del-owned", { owner: "alice" }), 0, "a second delete finds nothing");
+        const deleteWith = store.deleteSessionCheckpoints;
+        for (const guard of [{}, { owner: undefined }, { owner: 7 }]) {
+            const call = () => Reflect.apply(deleteWith, store, ["del-other", guard]);
+            await assert.rejects(call, (e) => e.code === "config.invalid_argument", `refused loudly: ${JSON.stringify(guard)}`);
+        }
+        assert.ok((await store.get(bystander.token)) !== null, "a refused guard deletes nothing");
+    });
+    run("claim holder (when declared `fence.holder`): a resolve carrying `expect.holder` wins only while the holder is current; a superseded holder loses with the row pending at the same rev (claimTerminal, when offered, answers that reading); no holder is unchanged", async () => {
+        const store = make();
+        if (store.fence?.holder !== true)
+            return;
+        const holders = options.holders;
+        assert.ok(holders !== undefined, "a store declaring `fence.holder` is judged with the binding's `holders` (the set its holder judge reads)");
+        holders.add("kit-holder-current");
+        const [a, b, c] = [createCheckpointFixture(), createCheckpointFixture(), createCheckpointFixture()];
+        for (const cp of [a, b, c])
+            await store.put(cp.token, cp);
+        assert.equal(await store.resolve(a.token, a.scope, ALLOW, { rev: 0, holder: "kit-holder-gone" }), false, "a holder that is not current loses");
+        const after = (await store.get(a.token));
+        assert.deepEqual([after.status, after.rev ?? 0], ["pending", 0], "the row is untouched by the lost CAS");
+        if (store.claimTerminal !== undefined) {
+            assert.deepEqual(await store.claimTerminal(a.token, a.scope, { kind: "resolve", outcome: ALLOW, expect: { rev: 0, holder: "kit-holder-gone" } }), { claimed: false, current: { status: "pending", rev: 0 } });
+        }
+        assert.equal(await store.resolve(a.token, a.scope, ALLOW, { rev: 0, holder: "kit-holder-current" }), true, "the current holder wins");
+        holders.delete("kit-holder-current");
+        assert.equal(await store.resolve(b.token, b.scope, ALLOW, { rev: 0, holder: "kit-holder-current" }), false, "a holder released after an earlier win is judged afresh");
+        assert.equal(await store.resolve(c.token, c.scope, ALLOW, { rev: 0 }), true, "no holder: the CAS is as before");
+    });
     await settle();
 }
 const sortByToken = (a, b) => a.token.localeCompare(b.token);

package/dist/core/store-contracts/file-history-store-contract.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { chmod, mkdtemp, mkdir, rm, stat, symlink, writeFile, readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { isGovernanceRetryClass } from "../governance-codes.js";
 import { NodeExecutionEnv } from "../../internal/harness.js";
 import { beginContract } from "./contract-harness.js";
 function probeOver(inner) {
@@ -34,6 +35,13 @@ function envWithFailingRead(inner, fail) {
         },
     });
 }
+const NAMES_A_FAULT = { track_failed: true, snapshot_failed: true, restore_failed: true, adopt_failed: true, unsupported_format: true, not_found: false, conflict: false, aborted: false };
+function assertPermanenceWord(error, what) {
+    const p = error?.permanence;
+    assert.ok(p === undefined || isGovernanceRetryClass(p), `${what}: permanence must be absent or a GovernanceRetryClass word, got ${typeof p === "string" ? `"${p}"` : typeof p}`);
+    if (p !== undefined)
+        assert.ok(error !== undefined && NAMES_A_FAULT[error.code] === true, `${what}: ${error?.code} is not a fault and carries no permanence`);
+}
 async function withTree(fn) {
     const dir = await mkdtemp(join(tmpdir(), "fh-kit-"));
     try {
@@ -52,9 +60,20 @@ export async function fileHistoryStoreContract(make, runAssertion) {
             const r = await store.restore("sc", "e1", env, dir);
             assert.equal(r.outcome, "failed");
             assert.equal(r.error?.code, "not_found");
+            assertPermanenceWord(r.error, "a boundary never made (not a fault)");
             assert.deepEqual(r.filesChanged, []);
             assert.deepEqual(r.refused, []);
             assert.equal(await store.reap("sc", []), 0);
+            if (store.exportHistory !== undefined)
+                assert.deepEqual(await store.exportHistory("sc"), { ok: true, history: null }, "nothing to export is `ok` with `history: null` — the one meaning of null");
+            await writeFile(join(dir, "f.txt"), "v1");
+            assert.deepEqual(await store.trackEdit("sc", join(dir, "f.txt"), env, dir), { ok: true, minted: true });
+            assert.deepEqual(await store.snapshot("sc", "b1", env, dir), { ok: true });
+            await writeFile(join(dir, "f.txt"), "v2-edited");
+            const never = await store.restore("sc", "never-made", env, dir);
+            assert.equal(never.error?.code, "not_found");
+            assert.deepEqual([never.filesChanged, never.identicalSkipped, never.refused, never.failed], [[], [], [], []], "a boundary never made has an empty ledger");
+            assert.equal(await readFile(join(dir, "f.txt"), "utf8"), "v2-edited", "a boundary never made touches nothing");
         });
     });
     run("first-touch idempotence: a second trackEdit for the same path is a cheap no-op (ZERO env reads)", async () => {
@@ -186,6 +205,8 @@ export async function fileHistoryStoreContract(make, runAssertion) {
             assert.equal(busy.ok, false);
             if (!busy.ok)
                 assert.equal(busy.error.code, "conflict");
+            if (!busy.ok)
+                assertPermanenceWord(busy.error, "the target law's conflict");
             assert.equal(await store.canRestore("fresh", "b"), true);
         });
     });
@@ -272,10 +293,39 @@ export async function fileHistoryStoreContract(make, runAssertion) {
                 assert.deepEqual(await store.annulTrack("sc", join(dir, "opaque2.txt"), dir), { ok: true });
             await writeFile(join(dir, "opaque.txt"), "agent-edited");
             const r = await store.restore("sc", "b0", env, dir);
-            assert.equal(r.refused.some((f) => f.reason.includes("base_unavailable")), true, `the kept marker must still refuse a below-base restore: ${JSON.stringify(r)}`);
+            assert.equal(r.refused.some((f) => f.reason.includes("base_unavailable") && f.class === "base_unavailable"), true, `the kept marker must still refuse a below-base restore, classed base_unavailable: ${JSON.stringify(r)}`);
             assert.equal(await readFile(join(dir, "opaque.txt"), "utf8"), "agent-edited", "never overwritten with a fake baseline");
         });
     });
+    run("annulTrack's proof read that cannot re-read the path judged nothing: track_failed (aborted when the signal fired), no permanence, the record kept — never the history law's conflict", async () => {
+        await withTree(async (dir, env) => {
+            const store = make();
+            await writeFile(join(dir, "f.txt"), "pristine");
+            await writeFile(join(dir, "g.txt"), "pristine");
+            assert.deepEqual(await store.trackEdit("sc", join(dir, "f.txt"), env, dir), { ok: true, minted: true });
+            assert.deepEqual(await store.trackEdit("sc", join(dir, "g.txt"), env, dir), { ok: true, minted: true });
+            const unreadable = envWithFailingRead(env, async () => ({ ok: false, error: { code: "unknown", message: "transport gone" } }));
+            const unjudged = await store.annulTrack("sc", join(dir, "f.txt"), dir, { env: unreadable });
+            assert.equal(unjudged.ok, false, "an unread proof never retracts");
+            if (!unjudged.ok) {
+                assert.equal(unjudged.error.code, "track_failed", `a proof that could not be read is the verb's failure, not the law: ${JSON.stringify(unjudged)}`);
+                assert.equal(unjudged.error.permanence, undefined, "an env read error is not the store's own storage fault — unjudged");
+            }
+            const aborted = new AbortController();
+            aborted.abort();
+            const cut = await store.annulTrack("sc", join(dir, "g.txt"), dir, { env, signal: aborted.signal });
+            assert.equal(cut.ok, false, "a proof read cut by the signal never retracts");
+            if (!cut.ok)
+                assert.equal(cut.error.code, "aborted", `the signal fired: ${JSON.stringify(cut)}`);
+            assert.deepEqual(await store.snapshot("sc", "b1", env, dir), { ok: true });
+            await writeFile(join(dir, "f.txt"), "diverged");
+            await writeFile(join(dir, "g.txt"), "diverged");
+            const r = await store.restore("sc", "b1", env, dir);
+            assert.equal(r.outcome, "complete");
+            assert.equal(await readFile(join(dir, "f.txt"), "utf8"), "pristine", "the unjudged retraction left the record intact");
+            assert.equal(await readFile(join(dir, "g.txt"), "utf8"), "pristine", "the aborted retraction left the record intact");
+        });
+    });
     run("annulTrack refuses what is no longer a mint: a boundary-referenced record is history (typed conflict, record intact)", async () => {
         await withTree(async (dir, env) => {
             const store = make();
@@ -301,10 +351,14 @@ export async function fileHistoryStoreContract(make, runAssertion) {
             });
             const t = await store.trackEdit("sc", join(dir, "f.txt"), hostile, dir);
             assert.equal(typeof t.ok, "boolean");
+            if (!t.ok)
+                assertPermanenceWord(t.error, "trackEdit over a hostile env");
             const sHealthy = await store.trackEdit("sc2", join(dir, "f.txt"), env, dir);
             assert.deepEqual(sHealthy, { ok: true, minted: true });
             const snap = await store.snapshot("sc2", "b", hostile, dir);
             assert.equal(snap.ok, false);
+            if (!snap.ok)
+                assertPermanenceWord(snap.error, "snapshot over a hostile env");
             const r = await store.restore("sc2", "nope", hostile, dir);
             assert.equal(r.outcome, "failed");
         });
@@ -364,7 +418,8 @@ export async function fileHistoryStoreContract(make, runAssertion) {
             await shed.write(join(dir, "keep.txt"), "turn-1");
             assert.deepEqual(await src.snapshot("sc", "b1", env, dir), { ok: true });
             assert.equal(await src.reap("sc", ["b0", "b1"]), 0);
-            const envelope = await src.exportHistory("sc");
+            const exported = await src.exportHistory("sc");
+            const envelope = exported.ok ? exported.history : null;
             assert.ok(envelope !== null, "a scope with history must export an envelope");
             assert.equal(envelope.formatVersion, "file-history/1");
             assert.ok(envelope.tracked.every((t) => (t.keyKind === "root-relative" || t.keyKind === "absolute") && (t.keyFamily === "posix" || t.keyFamily === "win")), "every tracked row must carry its key's self-description (kind + family) — a bare key cannot be judged after it crosses machines");
@@ -409,6 +464,17 @@ export async function fileHistoryStoreContract(make, runAssertion) {
             });
             const m = await store.importHistory("sc", missingBlob, async () => undefined);
             assert.equal(m.ok, false);
+            if (!m.ok)
+                assert.equal(m.error.code, "adopt_failed", "a source that cannot supply a referenced blob");
+            if (!m.ok)
+                assertPermanenceWord(m.error, "importHistory whose source has no such blob");
+            assert.equal(await store.canRestore("sc", "b2"), false);
+            const thrown = await store.importHistory("sc", missingBlob, async () => {
+                throw Object.assign(new Error("source blob unreadable"), { code: "EACCES" });
+            });
+            assert.equal(thrown.ok, false);
+            if (!thrown.ok)
+                assertPermanenceWord(thrown.error, "importHistory whose source fetch threw");
             assert.equal(await store.canRestore("sc", "b2"), false);
             const duplicated = wireEnvelope({
                 formatVersion: "file-history/1",
@@ -507,7 +573,9 @@ export async function fileHistoryStoreContract(make, runAssertion) {
             await shed.write(join(dir, "f.txt"), "source-pristine");
             assert.deepEqual(await src.trackEdit("sc", join(dir, "f.txt"), env, dir), { ok: true, minted: true });
             assert.deepEqual(await src.snapshot("sc", "b1", env, dir), { ok: true });
-            const envelope = (await src.exportHistory("sc"));
+            const exported = await src.exportHistory("sc");
+            assert.ok(exported.ok && exported.history !== null, "a scope with history must export an envelope");
+            const envelope = exported.history;
             const dst = make();
             assert.deepEqual(await dst.importHistory("target", envelope, shed.fetch), { ok: true });
             assert.deepEqual(await dst.importHistory("target", envelope, shed.fetch), { ok: true }, "the same envelope arriving twice is a re-publish, not a conflict");
@@ -515,7 +583,8 @@ export async function fileHistoryStoreContract(make, runAssertion) {
             assert.deepEqual(await dst.trackEdit("target", join(dir, "local.txt"), env, dir), { ok: true, minted: true });
             assert.deepEqual(await dst.snapshot("target", "b-local", env, dir), { ok: true });
             const other = await src.exportHistory("sc");
-            const conflict = await dst.importHistory("target", other, shed.fetch);
+            assert.ok(other.ok && other.history !== null);
+            const conflict = await dst.importHistory("target", other.history, shed.fetch);
             assert.equal(conflict.ok, false);
             if (!conflict.ok)
                 assert.equal(conflict.error.code, "conflict");
@@ -660,6 +729,7 @@ export async function fileHistoryStoreContract(make, runAssertion) {
                 const r = await store.restore("sc", "b1", env, dir);
                 assert.equal(r.outcome, "partial", JSON.stringify(r));
                 assert.equal(r.refused.length, 2, "both kind mismatches are refused, each by name");
+                assert.deepEqual(r.refused.map((f) => f.class), ["link_safety", "link_safety"], `a kind mismatch is a link-safety refusal: ${JSON.stringify(r.refused)}`);
                 assert.equal(await readFile(join(outside, "victim.txt"), "utf8"), "OUTSIDE-UNTOUCHED", "a leaf link is never written THROUGH");
                 assert.deepEqual(r.filesChanged, []);
             }

package/dist/core/store-contracts/peer-directory-contract.d.ts

@@ -9,7 +9,7 @@ export interface PeerDirectoryContractHooks {
     runAssertion?: ContractAssertionRunner;
 }
 /**
- * The directory contract. Four readings, each the reason the engine can do something:
+ * The directory contract. Five readings, each the reason the engine can do something:
  *  1. **scope wall** — a listing is the ACCESSOR's scope only; the cross-principal wall's mechanical
  *     seat is this filter, so a row leaking across scopes is a tenant leak, not a display bug;
  *  2. **the full set, copies** — live, dead AND deleted rows are all listed (a `name [ref]` is minted
@@ -18,6 +18,11 @@ export interface PeerDirectoryContractHooks {
  *  3. **resolution feeds on the listing** — the engine's own resolver, over the rows as listed, finds
  *     a live row by name, still finds a dead one, and answers `deleted` for a tombstone;
  *  4. **restore is CAS-on-absent** (only where the host implements it) — an absent row is restored and
- *     then listed; a present row is never overwritten (`false`, the existing row byte-unchanged).
+ *     then listed; a present row is never overwritten (`false`, the existing row byte-unchanged);
+ *  5. **every listed row is one the engine's reader accepts** — the engine reads a listing through
+ *     `readPeerSessionRecord` and one refused row faults the WHOLE listing (dropping it would resize refs and
+ *     change resolution over the full set), so a row that does not say `where`, or a non-local row carrying a
+ *     machine-bound member, takes the directory's peer lane down. (How a host decides `where` is its own;
+ *     the kit does not require the written value back.)
  */
 export declare function peerDirectoryContract(mk: () => PeerDirectory, hooks: PeerDirectoryContractHooks): Promise<void>;

package/dist/core/store-contracts/peer-directory-contract.js

@@ -1,9 +1,9 @@
 import { strict as assert } from "node:assert";
-import { resolvePeerSessions } from "../../agents/peer-directory.js";
+import { readPeerSessionRecord, resolvePeerSessions } from "../../agents/peer-directory.js";
 import { beginContract } from "./contract-harness.js";
 export const PEER_DIRECTORY_CONTRACT_SCOPE = "peer-kit-A";
 function row(name, sessionId, over = {}) {
-    return { schemaVersion: 1, sessionId, scope: PEER_DIRECTORY_CONTRACT_SCOPE, name, startedAt: 1_000, updatedAt: 2_000, liveness: "live", ...over };
+    return { schemaVersion: 1, sessionId, scope: PEER_DIRECTORY_CONTRACT_SCOPE, name, startedAt: 1_000, updatedAt: 2_000, liveness: "live", where: "hosted", ...over };
 }
 async function withDirs(mk, fn) {
     const live = [];
@@ -78,5 +78,17 @@ export async function peerDirectoryContract(mk, hooks) {
         assert.equal(current.liveness, "live");
         assert.equal(current.updatedAt, 9_000, "the existing row is byte-unchanged by a losing restore");
     });
+    run("every listed row is one the engine's row reader accepts (live, dead and deleted alike)", async (make) => {
+        const d = make();
+        await hooks.write(d, row("alpha", "sess-a"));
+        await hooks.write(d, row("beta", "sess-b", { liveness: "dead", diedAt: 3_000 }));
+        await hooks.write(d, row("gamma", "sess-c", { liveness: "deleted", diedAt: 3_000 }));
+        const listed = await d.listPeerSessions({ scope: S });
+        assert.equal(listed.length, 3);
+        for (const r of listed) {
+            const read = readPeerSessionRecord(r);
+            assert.ok(read.ok, `listed row ${r.sessionId} is refused by the engine's reader (${read.ok ? "" : `${read.reason}${read.field !== undefined ? `: ${read.field}` : ""}`})`);
+        }
+    });
     await settle();
 }

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

@@ -0,0 +1,7 @@
+import { type SessionPolicyStore } from "../session-policy-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+/**
+ * The full cross-backend contract for the operator part of a {@link SessionPolicyStore} row. Every case builds its store via
+ * `make()`; with no runner the cases run sequentially and the first failure throws.
+ */
+export declare function sessionPolicyStoreContract(make: () => SessionPolicyStore, runAssertion?: ContractAssertionRunner): Promise<void>;