@sema-agent/core 7.55.0 → 7.56.0

package/dist/core/ask-unresolvable-notice.js

@@ -1,3 +1,4 @@
+import { APPROVAL_REMEDY_KINDS, readApprovalRemedy } from "./ask-origin.js";
 export const ASK_UNRESOLVABLE_CAUSES = Object.freeze(["approver_unavailable", "no_approver_wired", "mandate_unreconstructible"]);
 Object.freeze(ASK_UNRESOLVABLE_CAUSES);
 const ASK_UNRESOLVABLE_CAUSE_SET = new Set(ASK_UNRESOLVABLE_CAUSES);
@@ -18,7 +19,7 @@ export function askUnresolvableRemedySeat(cause) {
     return CAUSE_REMEDY_SEAT[cause];
 }
 export function askUnresolvableNotice(facts) {
-    const { sessionId, toolName, toolCallId, cause, parkLaneExisted, remedy } = facts;
+    const { sessionId, toolName, toolCallId, cause, parkLaneExisted, remedy, remedies } = facts;
     if (typeof sessionId !== "string" || sessionId.length === 0) {
         throw new TypeError("delegation.ask_unresolvable: sessionId is required — a user-audience notice with no session routes nowhere");
     }
@@ -31,12 +32,25 @@ export function askUnresolvableNotice(facts) {
     if (!isAskUnresolvableCause(cause)) {
         throw new TypeError(`delegation.ask_unresolvable: cause ${JSON.stringify(cause)} is not one of ${ASK_UNRESOLVABLE_CAUSES.join("/")}`);
     }
+    let remedyList;
+    if (remedies !== undefined) {
+        if (typeof remedy !== "string" || remedy.length === 0 || !Array.isArray(remedies) || remedies.length === 0) {
+            throw new TypeError("delegation.ask_unresolvable: remedies are a non-empty list of ways out riding beside the remedy sentence they restate");
+        }
+        remedyList = [];
+        for (let i = 0; i < remedies.length; i++) {
+            const read = Object.hasOwn(remedies, i) ? readApprovalRemedy(remedies[i]) : undefined;
+            if (read === undefined)
+                throw new TypeError(`delegation.ask_unresolvable: remedies[${i}] is not one way out of the closed set (${APPROVAL_REMEDY_KINDS.join("/")}) with exactly its own fields`);
+            remedyList.push(read);
+        }
+    }
     const park = parkLaneExisted ? "the durable approval park did not take it" : "no durable approval park is armed for this run";
     return {
         code: "delegation.ask_unresolvable",
         message: `approval for "${toolName}" could not be resolved: ${CAUSE_CLAUSE[cause]} and ${park} — ` +
             `the call was denied fail-closed and did not run. ${typeof remedy === "string" && remedy.length > 0 ? `To let it run: ${remedy}. ` : ""}To let such approvals wait for a person, run with a checkpoint store and a ` +
             `durable approval opt-in (or a live approver reachable for delegated children).`,
-        detail: { sessionId, toolName, toolCallId, cause, parkLaneExisted: parkLaneExisted === true, ...(typeof remedy === "string" && remedy.length > 0 ? { remedy } : {}) },
+        detail: { sessionId, toolName, toolCallId, cause, parkLaneExisted: parkLaneExisted === true, ...(typeof remedy === "string" && remedy.length > 0 ? { remedy } : {}), ...(remedyList !== undefined ? { remedies: remedyList } : {}) },
     };
 }

package/dist/core/checkpoint-generation.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A checkpoint row's generation and the judges of a resolve's expectation over it (the generation, the claim holder). Every
+ * backend, the resume's claim and a host that compares two reads of one row read the generation here, so "an absent `rev`
+ * reads as 0" is written once.
+ * A leaf: it types against `checkpoint-store.ts` (type only), so the store module can call it without a load-order cycle.
+ */
+import type { Checkpoint, CheckpointStore, ResolveExpectation } from "./checkpoint-store.js";
+/**
+ * THE generation of a checkpoint row: its monotonic {@link Checkpoint.rev}, where an absent `rev` (a row
+ * minted before the field existed, never mutated) reads as `0`. This is the one place that rule is
+ * written — the CAS predicate under it, the loss answer, both backends' resolve / reopen bump, and the
+ * resume's expectation all read the generation through it, and so should a backend or a host that
+ * compares two reads of one row (`checkpointRevOf(again) === checkpointRevOf(row)` ⇒ no resolve / reopen
+ * landed between them).
+ */
+export declare function checkpointRevOf(cp: Pick<Checkpoint, "rev">): number;
+/**
+ * REF-A4 — THE optimistic-concurrency half of `resolve`'s CAS predicate (design/80 D-1), shared by every
+ * backend. The caller validated its reopen-by-reason guard against a `get()` snapshot; if a concurrent
+ * resolve/reopen cycle moved the monotonic `rev` in the get→resolve window, that validation is stale ⇒
+ * lose the CAS (fail-closed), forcing a re-get + re-validate. Keyed on `rev`, NOT on `reopenReason` — a
+ * 2-valued enum can ABA back to a prior value while the winner changed (round-2 BLOCKER fix). An absent
+ * expectation opts out of the guard entirely.
+ */
+export declare function checkpointOccMatches(cp: Checkpoint, expect?: ResolveExpectation): boolean;
+/**
+ * The deployment's judge of a claim holder, handed to an in-tree store (`holderIsCurrent`): `true` while the grant `holder` names is
+ * the current one, `false` once it is not. Exactly `true` is current; any answer that is not a boolean — a promise from an async judge
+ * included — is refused loudly ({@link checkpointHolderMatches}), never read by its truthiness and never as a lost grant.
+ * SYNCHRONOUS — the store calls it inside its atomic step, right before the commit, so the judgement and the flip
+ * are one step with respect to code in THIS process. That closes the race only when the deployment's claim transfers happen in this
+ * process and synchronously (an in-process claim table); a claim another process can transfer needs a store whose CAS and the claim
+ * table share one transaction (a SQL backend's WHERE).
+ */
+export type HolderJudge = (holder: string) => boolean;
+/**
+ * THE holder half of the same predicate ({@link ResolveExpectation.holder}), shared by every backend that judges holders through a
+ * function: no holder ⇒ nothing to judge; a holder ⇒ the store's judge answers whether that grant is still the current one. A store
+ * with no judge loses a holder-bearing CAS — it never ignores a precondition it was handed. Called inside the store's atomic step,
+ * right before the commit; a judge that throws makes the CAS throw with the row untouched. The judge's answer is current only when it
+ * is exactly `true`; an answer that is not a boolean throws `config.invalid_checkpoint_store` (the row untouched): a wiring error is
+ * named as one, not passed as a grant (by truthiness) nor reported as a superseded holder (by refusal).
+ */
+export declare function checkpointHolderMatches(expect: ResolveExpectation | undefined, holderIsCurrent: HolderJudge | undefined): boolean;
+/** `RunInternals.holder` when present: a non-empty string (the deployment's credential for one claim grant). A provided value that
+ *  is empty or not a string names no grant and is refused at the door (`config.invalid_argument`), never carried into a CAS where a
+ *  judge would read it as a grant that lost. The value itself is never printed — only its kind. */
+export declare function assertHolderValue(holder: unknown): void;
+/** The store-seat refusal of a claim holder the seat's store cannot judge: a run handed {@link ResolveExpectation.holder} (through
+ *  `RunInternals.holder`) whose store does not declare `fence = { holder: true }`. The store seat's door and code
+ *  (`config.invalid_checkpoint_store`, as for a store without the execution declaration); no store (a disarmed run) has nothing to
+ *  judge. The holder's value is never named. */
+export declare function assertCheckpointStoreJudgesHolder(seat: "TaskSpec.checkpointStore" | "RunnerDeps.checkpointStore", store: CheckpointStore | undefined, holder: string | undefined): void;

package/dist/core/checkpoint-generation.js

@@ -0,0 +1,35 @@
+export function checkpointRevOf(cp) {
+    return cp.rev ?? 0;
+}
+export function checkpointOccMatches(cp, expect) {
+    return expect === undefined || checkpointRevOf(cp) === expect.rev;
+}
+export function checkpointHolderMatches(expect, holderIsCurrent) {
+    if (expect?.holder === undefined)
+        return true;
+    if (holderIsCurrent === undefined)
+        return false;
+    const answer = holderIsCurrent(expect.holder);
+    if (typeof answer !== "boolean") {
+        const kind = answer === null ? "null" : typeof answer === "object" ? "an object (an async judge answers a promise)" : `a ${typeof answer}`;
+        const e = new Error(`the checkpoint store's \`holderIsCurrent\` judge must answer \`true\` or \`false\` synchronously (it answered ${kind}) — any other answer is a wiring error, not a judgement; the resolve did not run and the row is untouched. Make the judge a synchronous read of the claim table.`);
+        e.code = "config.invalid_checkpoint_store";
+        throw e;
+    }
+    return answer === true;
+}
+export function assertHolderValue(holder) {
+    if (holder === undefined || (typeof holder === "string" && holder !== ""))
+        return;
+    const kind = holder === "" ? "an empty string" : holder === null ? "null" : `a ${typeof holder}`;
+    const e = new Error(`RunInternals.holder must be a non-empty string when present (got ${kind}) — it is the deployment's credential for the claim grant the run acts under; omit it for a run that acts under none.`);
+    e.code = "config.invalid_argument";
+    throw e;
+}
+export function assertCheckpointStoreJudgesHolder(seat, store, holder) {
+    if (holder === undefined || store === undefined || store.fence?.holder === true)
+        return;
+    const e = new Error(`${seat}: the run carries a claim holder, but the wired CheckpointStore does not declare \`fence = { holder: true }\` — a store that does not judge the holder in its resolve would ignore it, and the fence would hold nothing. Wire a store that judges holders (the in-tree stores take \`holderIsCurrent\`) or stop passing one.`);
+    e.code = "config.invalid_checkpoint_store";
+    throw e;
+}

package/dist/core/checkpoint-queries.d.ts

@@ -0,0 +1,180 @@
+import type { Checkpoint, CheckpointSummary, CheckpointToken } from "./checkpoint-store.js";
+import { facetOf, type GateKind } from "./pause-registry.js";
+/**
+ * The page bounds of the two listing faces: a query without `limit` reads `default` rows, an explicit `limit` is an integer in
+ * 1..`max`. A session page holds whole rows (each carries its parked state), an overdue page holds summaries — hence the smaller
+ * session bound.
+ */
+export declare const CHECKPOINT_LIST_LIMITS: Readonly<{
+    overdue: Readonly<{
+        readonly default: 100;
+        readonly max: 500;
+    }>;
+    session: Readonly<{
+        readonly default: 100;
+        readonly max: 100;
+    }>;
+}>;
+/** A row's deadline semantic — {@link facetOf}'s answer for its gate (`A` approval SLA, `B` abandonment TTL, `-` the non-gate park). */
+export type CheckpointFacet = ReturnType<typeof facetOf>;
+type CheckpointRowStatus = Checkpoint["status"];
+/** One page of a listing face: the rows, and the cursor of the next page — present exactly when more rows match after these. */
+export interface CheckpointPage<R, C> {
+    readonly rows: readonly R[];
+    /** Pass it as the next query's `after`. The store mints it from its own order key; a caller never builds one. */
+    readonly next?: C;
+}
+/** The order key of an overdue page: the row's deadline (`-Infinity` for a deadline that is not a finite number), then its token. */
+export interface CheckpointOverdueCursor {
+    readonly deadline: number;
+    readonly token: CheckpointToken;
+}
+/**
+ * What {@link import("./checkpoint-store.js").CheckpointStore.listOverdue} is asked for: the PENDING rows of every scope whose
+ * deadline has passed `cutoff` ({@link checkpointDeadlinePassed}) and whose gate reads as `facet` ({@link facetOf}, the card
+ * overrides included — a question parked under an approval gate kind is `B`). Ordered by deadline, then token, ascending.
+ * A deployment's sweep reads one facet at a time and disposes each row through the row CAS verbs (`expire`, or a resume that
+ * denies): `A` rows are approvals whose deadline denies, `B` and `-` rows are abandoned at theirs.
+ */
+export interface CheckpointOverdueQuery {
+    /** Epoch ms, a finite number. */
+    cutoff: number;
+    facet: CheckpointFacet;
+    after?: CheckpointOverdueCursor;
+    /** At most this many rows, an integer in 1..{@link CHECKPOINT_LIST_LIMITS}`.overdue.max`; absent = the default. */
+    limit?: number;
+}
+/** The order key of a session page: the row's `createdAt` (`-Infinity` for one that is not a finite number), then its token. */
+export interface CheckpointSessionCursor {
+    readonly createdAt: number;
+    readonly token: CheckpointToken;
+}
+/**
+ * What {@link import("./checkpoint-store.js").CheckpointStore.listBySession} is asked for: the rows of ONE session, of every
+ * status unless `status` says one, narrowed by the members present. Ordered by `createdAt`, then token — oldest first unless
+ * `order` says `newest`. "The session's pending row of these gate kinds, newest first" is `{ status: "pending", gateKinds,
+ * order: "newest", limit: 1 }`; "the rows that parked this tool call" is `{ toolCallId }`; "does the session hold an expired
+ * row" is `{ status: "expired", limit: 1 }`.
+ */
+export interface CheckpointSessionQuery {
+    /** The session id (non-empty). */
+    sessionId: string;
+    /** Only the rows filed in this scope. */
+    scope?: string;
+    /** Only the rows in this status. Absent = every status. */
+    status?: CheckpointRowStatus;
+    /** Only the rows parked on one of these gate kinds; an empty list matches no row. Absent = every kind. */
+    gateKinds?: readonly GateKind[];
+    /** Only the rows whose pending action is a `tool_approval` of this tool call (a park with no tool call never matches). */
+    toolCallId?: string;
+    /** Only the rows created at or after this epoch ms (a finite number). */
+    createdSince?: number;
+    order?: "oldest" | "newest";
+    after?: CheckpointSessionCursor;
+    /** At most this many rows, an integer in 1..{@link CHECKPOINT_LIST_LIMITS}`.session.max`; absent = the default. */
+    limit?: number;
+}
+/**
+ * One row of a session page. `row` is a readable row (its members match the query and every member the face judged is well
+ * formed). `unreadable` is a row of THIS session that matches every filter the store could judge but whose stored shape the face
+ * cannot read — a token member other than the key it is filed under, a scope that is not a string, a status outside the three
+ * words, a gate with no registered kind, a pending action with no kind, a tool approval with no tool call id, a `createdAt` that
+ * is not a finite number, a state that is not an object: it is answered rather than skipped (an unreadable row is not an absent
+ * one, and a consumer that takes its token to `get` meets the damage loudly) and rather than failing the page (one damaged row
+ * does not hide the readable rows beside it). The store discloses it through its own seat. Its `token` is the key the store
+ * files it under.
+ */
+export type CheckpointRowRead = {
+    readonly kind: "row";
+    readonly checkpoint: Checkpoint;
+} | {
+    readonly kind: "unreadable";
+    readonly token: CheckpointToken;
+    /** The stored scope, or `null` when it is not a string. */
+    readonly scope: string | null;
+    readonly sessionId: string;
+    /** The status as stored (a word outside the three is part of the damage). */
+    readonly status: string;
+    /** The stored `createdAt`, or `null` when it is not a finite number. */
+    readonly createdAt: number | null;
+    /** What could not be read, naming the member by its shape (never its value). */
+    readonly problem: string;
+};
+/**
+ * The guard of {@link import("./checkpoint-store.js").CheckpointStore.deleteSessionCheckpoints}: the rows are deleted only when the
+ * session's own row exists and is owned by `owner` — compared null-safe (`null` = the anonymous session, and it matches only an
+ * anonymous one). No session row, or another owner, deletes nothing and answers `0`. `owner` is a principal name or `null`: a
+ * blank string names nobody and is refused.
+ */
+export interface CheckpointDeleteGuard {
+    readonly owner: string | null;
+}
+/** {@link readCheckpointOverdueQuery}'s answer: the members as read, the default limit filled in. */
+export interface CheckpointOverdueQueryReading {
+    readonly cutoff: number;
+    readonly facet: CheckpointFacet;
+    readonly after?: CheckpointOverdueCursor;
+    readonly limit: number;
+}
+/** {@link readCheckpointSessionQuery}'s answer: the members as read, the default order and limit filled in. */
+export interface CheckpointSessionQueryReading {
+    readonly sessionId: string;
+    readonly scope?: string;
+    readonly status?: CheckpointRowStatus;
+    readonly gateKinds?: readonly GateKind[];
+    readonly toolCallId?: string;
+    readonly createdSince?: number;
+    readonly order: "oldest" | "newest";
+    readonly after?: CheckpointSessionCursor;
+    readonly limit: number;
+}
+/** The one reading of a {@link CheckpointOverdueQuery} for every store that implements `listOverdue`. A bad value is refused,
+ *  never mapped to a default: `config.invalid_argument`. */
+export declare function readCheckpointOverdueQuery(raw: unknown): CheckpointOverdueQueryReading;
+/** The one reading of a {@link CheckpointSessionQuery} for every store that implements `listBySession`. A bad value is refused,
+ *  never mapped to a default: `config.invalid_argument`. */
+export declare function readCheckpointSessionQuery(raw: unknown): CheckpointSessionQueryReading;
+/** The guard's one reading (the delete is irreversible, so a guard that is not exactly `{ owner: <a principal name> | null }` is refused). */
+export declare function readCheckpointDeleteGuard(sessionId: unknown, raw: unknown): {
+    readonly sessionId: string;
+    readonly owner: string | null;
+};
+/** Does the session's head admit the delete: a row exists and its owner equals the guard's, null-safe. */
+export declare function deleteGuardAdmits(head: {
+    readonly owner: string | null;
+} | undefined, owner: string | null): boolean;
+/**
+ * `deleteSessionCheckpoints` over a store's rows, for both first-party stores: the guard read, the session's rows taken as they stand when
+ * the call starts — BEFORE the head read, so a row put while it is awaited (another generation of the id, under another owner) is
+ * never one of them — the guard judged on the head, then each taken row handed to `remove`, which deletes it only while it is still
+ * that row and answers whether it did. Answers the count.
+ */
+export declare function deleteSessionRowsAtStart(rows: Iterable<readonly [string, Checkpoint]>, sessionId: unknown, guard: unknown, headOf: (sessionId: string) => Promise<{
+    readonly owner: string | null;
+} | undefined>, remove: (token: string, row: Checkpoint) => boolean | Promise<boolean>): Promise<number>;
+/**
+ * Has a row's deadline passed `cutoff`? A row with no deadline never has; a deadline that is not a finite number always has —
+ * a bound nobody can evaluate is not a bound, and leaving it would keep the row pending forever (core sanitizes its own mints,
+ * but rows also come from other backends and older engines, and a JSON-held `NaN` reads back as `null`). The two `reap` verbs and
+ * {@link selectOverduePage} read this one rule.
+ */
+export declare function checkpointDeadlinePassed(deadline: number | null | undefined, cutoff: number): boolean;
+/**
+ * The overdue page over a store's rows (`[key, row]` pairs — the key is the authoritative token): pending ∧
+ * {@link checkpointDeadlinePassed} ∧ `facetOf(gate) === facet`, after the cursor, ordered (deadline key, token) ascending, filled up
+ * to `limit` with the rows whose summary `project` mints. A candidate whose shape the face cannot read, or whose summary cannot be
+ * projected, is left out and disclosed (`disclose` gets one sentence per such row, on every call) and the page fills on from the
+ * next candidate; only the rows of the page are projected. `next` is present when a candidate remains after the page's last row
+ * (a page after it can come back shorter, even empty, when every remaining candidate is damaged).
+ */
+export declare function selectOverduePage(rows: Iterable<readonly [string, Checkpoint]>, query: CheckpointOverdueQueryReading, project: (cp: Checkpoint) => CheckpointSummary, disclose?: (sentence: string) => void): CheckpointPage<CheckpointSummary, CheckpointOverdueCursor>;
+/**
+ * The session page over a store's rows (`[key, row]` pairs — the key is the authoritative token): the session's rows narrowed by
+ * the query's members, after the cursor, ordered (createdAt key, token) in the query's order, cut at `limit` before anything is
+ * copied (`clone` runs for the page's readable rows only). A filter that reads a damaged member cannot exclude the row, so a row of
+ * this session that no readable filter excludes and that carries damage is answered `unreadable` (and disclosed); a row whose
+ * session id is not a string is attributable to no session — left out and disclosed. `next` is present exactly when more rows
+ * match after the page.
+ */
+export declare function selectSessionPage(rows: Iterable<readonly [string, Checkpoint]>, query: CheckpointSessionQueryReading, clone: (cp: Checkpoint) => Checkpoint, disclose?: (sentence: string) => void): CheckpointPage<CheckpointRowRead, CheckpointSessionCursor>;
+export {};

package/dist/core/checkpoint-queries.js

@@ -0,0 +1,272 @@
+import { types } from "node:util";
+import { facetOf, isGateKind } from "./pause-registry.js";
+import { receiptRefusal, receiveOwnProperties } from "./own-property-receipt.js";
+import { principalNameOf } from "./principal-name.js";
+export const CHECKPOINT_LIST_LIMITS = Object.freeze({
+    overdue: Object.freeze({ default: 100, max: 500 }),
+    session: Object.freeze({ default: 100, max: 100 }),
+});
+const FACETS = ["A", "B", "-"];
+const STATUSES = ["pending", "resolved", "expired"];
+const OVERDUE_MEMBERS = ["cutoff", "facet", "after", "limit"];
+const SESSION_MEMBERS = ["sessionId", "scope", "status", "gateKinds", "toolCallId", "createdSince", "order", "after", "limit"];
+function receiveQuery(raw, subject, face, members) {
+    if (typeof raw !== "object" || raw === null)
+        throw receiptRefusal(`${face}: the query must be an object, got ${raw === null ? "null" : typeof raw}`);
+    const got = receiveOwnProperties(raw, { subject, unit: "member", moment: `at ${face}` });
+    const own = Object.create(null);
+    for (const name of Object.keys(got)) {
+        if (!members.includes(name))
+            throw receiptRefusal(`${face}: the query carries "${name}", which is not a member of ${subject} — refused rather than answered without the filter it names`);
+        own[name] = got[name];
+    }
+    return own;
+}
+function readGateKinds(raw) {
+    const refuse = () => receiptRefusal("CheckpointSessionQuery.gateKinds must be a dense array of registered gate kinds (no hole, no accessor, not a Proxy) when present");
+    if (typeof raw !== "object" || raw === null || types.isProxy(raw) || !Array.isArray(raw))
+        throw refuse();
+    const length = Object.getOwnPropertyDescriptor(raw, "length")?.value;
+    if (typeof length !== "number")
+        throw refuse();
+    const kinds = [];
+    for (let i = 0; i < length; i++) {
+        const d = Object.getOwnPropertyDescriptor(raw, i);
+        if (d === undefined || !("value" in d) || !isGateKind(d.value))
+            throw refuse();
+        kinds.push(d.value);
+    }
+    return Object.freeze(kinds);
+}
+function readLimit(raw, subject, bound) {
+    if (raw === undefined)
+        return bound.default;
+    if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1 && raw <= bound.max)
+        return raw;
+    throw receiptRefusal(`${subject}.limit must be an integer in 1..${bound.max} when present`);
+}
+function readCursor(raw, subject, key, face) {
+    const got = receiveQuery(raw, `${subject}.after`, face, [key, "token"]);
+    const value = got[key];
+    if (typeof value !== "number" || Number.isNaN(value) || value === Infinity)
+        throw receiptRefusal(`${subject}.after.${key} must be a finite number or -Infinity (a cursor is the order key of the page before)`);
+    if (typeof got.token !== "string")
+        throw receiptRefusal(`${subject}.after.token must be a string`);
+    return { [key]: value, token: got.token };
+}
+export function readCheckpointOverdueQuery(raw) {
+    const face = "CheckpointStore.listOverdue";
+    const got = receiveQuery(raw, "CheckpointOverdueQuery", face, OVERDUE_MEMBERS);
+    const { cutoff, facet, after } = got;
+    if (typeof cutoff !== "number" || !Number.isFinite(cutoff))
+        throw receiptRefusal("CheckpointOverdueQuery.cutoff must be a finite number (epoch ms)");
+    if (!FACETS.includes(facet))
+        throw receiptRefusal(`CheckpointOverdueQuery.facet must be one of ${FACETS.map((f) => JSON.stringify(f)).join(" / ")}`);
+    return {
+        cutoff,
+        facet: facet,
+        ...(after !== undefined ? { after: readCursor(after, "CheckpointOverdueQuery", "deadline", face) } : {}),
+        limit: readLimit(got.limit, "CheckpointOverdueQuery", CHECKPOINT_LIST_LIMITS.overdue),
+    };
+}
+export function readCheckpointSessionQuery(raw) {
+    const face = "CheckpointStore.listBySession";
+    const got = receiveQuery(raw, "CheckpointSessionQuery", face, SESSION_MEMBERS);
+    const { sessionId, scope, status, gateKinds, toolCallId, createdSince, order, after } = got;
+    if (typeof sessionId !== "string" || sessionId === "")
+        throw receiptRefusal("CheckpointSessionQuery.sessionId must be a non-empty string");
+    if (scope !== undefined && typeof scope !== "string")
+        throw receiptRefusal(`CheckpointSessionQuery.scope must be a string when present, got ${typeof scope}`);
+    if (status !== undefined && !STATUSES.includes(status))
+        throw receiptRefusal(`CheckpointSessionQuery.status must be one of ${STATUSES.join(" / ")} when present`);
+    if (toolCallId !== undefined && typeof toolCallId !== "string")
+        throw receiptRefusal(`CheckpointSessionQuery.toolCallId must be a string when present, got ${typeof toolCallId}`);
+    if (createdSince !== undefined && (typeof createdSince !== "number" || !Number.isFinite(createdSince)))
+        throw receiptRefusal("CheckpointSessionQuery.createdSince must be a finite number when present");
+    if (order !== undefined && order !== "oldest" && order !== "newest")
+        throw receiptRefusal('CheckpointSessionQuery.order must be "oldest" or "newest" when present');
+    const kinds = gateKinds === undefined ? undefined : readGateKinds(gateKinds);
+    return {
+        sessionId,
+        ...(scope !== undefined ? { scope } : {}),
+        ...(status !== undefined ? { status: status } : {}),
+        ...(kinds !== undefined ? { gateKinds: kinds } : {}),
+        ...(toolCallId !== undefined ? { toolCallId } : {}),
+        ...(createdSince !== undefined ? { createdSince } : {}),
+        order: order === "newest" ? "newest" : "oldest",
+        ...(after !== undefined ? { after: readCursor(after, "CheckpointSessionQuery", "createdAt", face) } : {}),
+        limit: readLimit(got.limit, "CheckpointSessionQuery", CHECKPOINT_LIST_LIMITS.session),
+    };
+}
+export function readCheckpointDeleteGuard(sessionId, raw) {
+    const face = "CheckpointStore.deleteSessionCheckpoints";
+    if (typeof sessionId !== "string" || sessionId === "")
+        throw receiptRefusal(`${face}: the session id must be a non-empty string`);
+    const got = receiveQuery(raw, "CheckpointDeleteGuard", face, ["owner"]);
+    const owner = got.owner === null ? null : principalNameOf(got.owner);
+    if (owner === undefined)
+        throw receiptRefusal("CheckpointDeleteGuard.owner must be a principal name (a string with a visible character, no control or separator character, and no format character but a joiner) or null");
+    return { sessionId, owner };
+}
+export function deleteGuardAdmits(head, owner) {
+    return head !== undefined && head.owner === owner;
+}
+export async function deleteSessionRowsAtStart(rows, sessionId, guard, headOf, remove) {
+    const read = readCheckpointDeleteGuard(sessionId, guard);
+    const taken = [];
+    for (const [token, cp] of rows)
+        if (cp.sessionId === read.sessionId)
+            taken.push([token, cp]);
+    if (!deleteGuardAdmits(await headOf(read.sessionId), read.owner))
+        return 0;
+    let n = 0;
+    for (const [token, cp] of taken)
+        if (await remove(token, cp))
+            n++;
+    return n;
+}
+export function checkpointDeadlinePassed(deadline, cutoff) {
+    return deadline !== undefined && (typeof deadline === "number" && Number.isFinite(deadline) ? deadline <= cutoff : true);
+}
+function orderKey(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : -Infinity;
+}
+function membersOf(key, cp) {
+    return { key, token: cp.token, sessionId: cp.sessionId, scope: cp.scope, status: cp.status, gate: cp.gate, pendingAction: cp.pendingAction, createdAt: cp.createdAt, deadline: cp.deadline, state: cp.state, checkpointId: cp.checkpointId };
+}
+function memberOf(value, key) {
+    return typeof value === "object" && value !== null && key in value ? value[key] : undefined;
+}
+const isStatusWord = (v) => STATUSES.some((s) => s === v);
+const isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
+function listingDamage(m) {
+    if (m.token !== m.key)
+        return "its token member is not the key the store files it under";
+    if (typeof m.scope !== "string")
+        return "its scope is not a string";
+    if (!isStatusWord(m.status))
+        return "its status is not one of pending / resolved / expired";
+    if (!isGateKind(memberOf(m.gate, "kind")))
+        return "its gate is not an object of a registered gate kind";
+    const actionKind = memberOf(m.pendingAction, "kind");
+    if (typeof actionKind !== "string")
+        return "its pending action is not an object with a kind";
+    if (actionKind === "tool_approval" && typeof memberOf(m.pendingAction, "toolCallId") !== "string")
+        return "its tool approval carries no tool call id";
+    if (!isFiniteNumber(m.createdAt))
+        return "its createdAt is not a finite number";
+    if (typeof m.state !== "object" || m.state === null)
+        return "its state is not an object";
+    return undefined;
+}
+function thrownName(e) {
+    return e instanceof Error ? e.constructor.name : typeof e;
+}
+function rowName(m) {
+    return `checkpoint ${typeof m.checkpointId === "string" ? JSON.stringify(m.checkpointId) : "null"} of session ${typeof m.sessionId === "string" ? JSON.stringify(m.sessionId) : "(unreadable)"}`;
+}
+function afterCursor(key, token, cursor, ascending) {
+    if (key !== cursor.key)
+        return ascending ? key > cursor.key : key < cursor.key;
+    return ascending ? token > cursor.token : token < cursor.token;
+}
+function compareKeys(a, b) {
+    if (a.key !== b.key)
+        return a.key < b.key ? -1 : 1;
+    return a.token < b.token ? -1 : a.token > b.token ? 1 : 0;
+}
+export function selectOverduePage(rows, query, project, disclose) {
+    const hits = [];
+    for (const [token, cp] of rows) {
+        const m = membersOf(token, cp);
+        if (m.status !== "pending" || !checkpointDeadlinePassed(m.deadline, query.cutoff))
+            continue;
+        const damage = typeof m.sessionId !== "string" ? "its sessionId is not a string" : listingDamage(m);
+        if (damage !== undefined) {
+            disclose?.(`${rowName(m)}: ${damage} — the overdue listing cannot read it, so it leaves it out`);
+            continue;
+        }
+        if (facetOf(m.gate) !== query.facet)
+            continue;
+        const key = orderKey(m.deadline);
+        if (query.after !== undefined && !afterCursor(key, token, { key: query.after.deadline, token: query.after.token }, true))
+            continue;
+        hits.push({ key, token, cp, m });
+    }
+    hits.sort(compareKeys);
+    const out = [];
+    let last;
+    let i = 0;
+    for (; i < hits.length && out.length < query.limit; i++) {
+        const hit = hits[i];
+        let summary;
+        try {
+            summary = project(hit.cp);
+        }
+        catch (e) {
+            disclose?.(`${rowName(hit.m)}: its summary could not be projected (${thrownName(e)}) — the overdue listing leaves it out`);
+            continue;
+        }
+        out.push(summary);
+        last = hit;
+    }
+    return { rows: out, ...(i < hits.length && last !== undefined ? { next: { deadline: last.key, token: last.token } } : {}) };
+}
+export function selectSessionPage(rows, query, clone, disclose) {
+    const ascending = query.order === "oldest";
+    const hits = [];
+    if (query.gateKinds !== undefined && query.gateKinds.length === 0)
+        return { rows: [] };
+    for (const [token, cp] of rows) {
+        const m = membersOf(token, cp);
+        if (typeof m.sessionId !== "string") {
+            disclose?.(`${rowName(m)}: its sessionId is not a string — no session listing can attribute it, so it is left out`);
+            continue;
+        }
+        if (m.sessionId !== query.sessionId)
+            continue;
+        if (query.scope !== undefined && typeof m.scope === "string" && m.scope !== query.scope)
+            continue;
+        if (query.status !== undefined && isStatusWord(m.status) && m.status !== query.status)
+            continue;
+        const gateKind = memberOf(m.gate, "kind");
+        if (query.gateKinds !== undefined && isGateKind(gateKind) && !query.gateKinds.includes(gateKind))
+            continue;
+        if (query.toolCallId !== undefined) {
+            const actionKind = memberOf(m.pendingAction, "kind");
+            const callId = memberOf(m.pendingAction, "toolCallId");
+            if (typeof actionKind === "string" && actionKind !== "tool_approval")
+                continue;
+            if (actionKind === "tool_approval" && typeof callId === "string" && callId !== query.toolCallId)
+                continue;
+        }
+        if (query.createdSince !== undefined && isFiniteNumber(m.createdAt) && m.createdAt < query.createdSince)
+            continue;
+        const key = orderKey(m.createdAt);
+        if (query.after !== undefined && !afterCursor(key, token, { key: query.after.createdAt, token: query.after.token }, ascending))
+            continue;
+        hits.push({ key, token, cp, m, damage: listingDamage(m) });
+    }
+    hits.sort((a, b) => (ascending ? 1 : -1) * compareKeys(a, b));
+    const page = hits.slice(0, query.limit);
+    const last = page[page.length - 1];
+    return {
+        rows: page.map((h) => readOut(h, clone, disclose)),
+        ...(hits.length > query.limit && last !== undefined ? { next: { createdAt: last.key, token: last.token } } : {}),
+    };
+}
+function readOut(hit, clone, disclose) {
+    const { token, cp, m, damage } = hit;
+    if (damage === undefined)
+        return { kind: "row", checkpoint: clone(cp) };
+    disclose?.(`${rowName(m)}: ${damage} — listed as unreadable`);
+    return {
+        kind: "unreadable",
+        token: token,
+        scope: typeof m.scope === "string" ? m.scope : null,
+        sessionId: String(m.sessionId),
+        status: typeof m.status === "string" ? m.status : `(${typeof m.status})`,
+        createdAt: isFiniteNumber(m.createdAt) ? m.createdAt : null,
+        problem: damage,
+    };
+}

package/dist/core/checkpoint-requirements.d.ts

@@ -6,7 +6,7 @@ import { type StoreFidelity, type Checkpoint, type CheckpointFeature, type Check
  * had carried beside the one its word now names, and the members added after the table, each a capability a reader
  * must have. Downstream reads them for display only (`CheckpointError.detail.requires`).
  */
-export declare const REQUIREMENT_WORDS: readonly ["resource", "binding", "token", "orgAdmission", "f012", "realApproval", "face", "requirements_digest", "org_admission_inherited", "org_write_grant", "org_governed", "delegation_provenance", "skill_grants", "skill_card_binding", "hands_coordinates", "hands_home", "path_rule_anchors", "path_rule_installations", "permission_mode", "plan_mode_restore", "persisted_rule_mandate", "deployment_authored", "call_names", "write_face", "denial_limit_fallback", "leg_scope", "tool_ceiling", "tool_lists_judged", "own_tool_lists", "approval_targets", "cross_boundary"];
+export declare const REQUIREMENT_WORDS: readonly ["resource", "binding", "token", "orgAdmission", "f012", "realApproval", "face", "requirements_digest", "org_admission_inherited", "org_write_grant", "org_governed", "delegation_provenance", "skill_grants", "skill_card_binding", "hands_coordinates", "hands_home", "path_rule_anchors", "path_rule_installations", "permission_mode", "plan_mode_restore", "persisted_rule_mandate", "deployment_authored", "call_names", "write_face", "denial_limit_fallback", "leg_scope", "tool_ceiling", "tool_lists_judged", "own_tool_lists", "approval_targets", "cross_boundary", "mount_site", "skill_scopes"];
 export type RequirementWord = (typeof REQUIREMENT_WORDS)[number];
 /** Runtime twin of {@link RequirementWord}. */
 export declare function isRequirementWord(word: unknown): word is RequirementWord;
@@ -124,6 +124,9 @@ export declare const CHECKPOINT_STATE_REQUIREMENTS: {
     readonly skillGrants: {
         readonly word: "skill_grants";
     };
+    readonly skillScopes: {
+        readonly word: "skill_scopes";
+    };
     readonly reminderMark: {
         readonly digest: "decision-read";
     };
@@ -323,6 +326,9 @@ export declare const PENDING_ACTION_REQUIREMENTS: {
         readonly names: {
             readonly word: "call_names";
         };
+        readonly engineMounted: {
+            readonly word: "mount_site";
+        };
         readonly targets: {
             readonly word: "approval_targets";
         };
@@ -485,6 +491,9 @@ export declare const CHECKPOINT_REQUIREMENTS: {
             readonly skillGrants: {
                 readonly word: "skill_grants";
             };
+            readonly skillScopes: {
+                readonly word: "skill_scopes";
+            };
             readonly reminderMark: {
                 readonly digest: "decision-read";
             };
@@ -829,6 +838,9 @@ export declare const CHECKPOINT_REQUIREMENTS: {
                 readonly names: {
                     readonly word: "call_names";
                 };
+                readonly engineMounted: {
+                    readonly word: "mount_site";
+                };
                 readonly targets: {
                     readonly word: "approval_targets";
                 };