@sema-agent/core 7.54.1 → 7.56.0

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";
     };
@@ -317,9 +320,15 @@ export declare const PENDING_ACTION_REQUIREMENTS: {
         readonly pathTarget: {
             readonly digest: "decision-read";
         };
+        readonly hostTarget: {
+            readonly digest: "decision-read";
+        };
         readonly names: {
             readonly word: "call_names";
         };
+        readonly engineMounted: {
+            readonly word: "mount_site";
+        };
         readonly targets: {
             readonly word: "approval_targets";
         };
@@ -482,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";
             };
@@ -820,9 +832,15 @@ export declare const CHECKPOINT_REQUIREMENTS: {
                 readonly pathTarget: {
                     readonly digest: "decision-read";
                 };
+                readonly hostTarget: {
+                    readonly digest: "decision-read";
+                };
                 readonly names: {
                     readonly word: "call_names";
                 };
+                readonly engineMounted: {
+                    readonly word: "mount_site";
+                };
                 readonly targets: {
                     readonly word: "approval_targets";
                 };
@@ -873,9 +891,6 @@ export interface UnencodableMember {
     readonly path: string;
     readonly kind: "cycle" | "depth" | "function" | "symbol" | "unreadable" | "codec";
 }
-/** Where a value holds something the row digest cannot encode, or `undefined` — the park mint asks this of the
- *  arguments before any side effect, so such a call is refused before anything is paused. */
-export declare function unencodableIn(value: unknown, path: string): UnencodableMember | undefined;
 /** The row digest: sha256 (hex) over the binding serializer's canonical form ({@link canonicalize}: type-tagged,
  *  sorted keys) of every member a decision reads but the digest itself, keyed by path, each read through
  *  {@link digestProjection}. Never a constant: a value it cannot encode throws {@link RowNotEncodable}. */

package/dist/core/checkpoint-requirements.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { canonicalize, UNCANONICALIZABLE } from "./canonical-json.js";
+import { canonicalize, MAX_DEPTH, UNCANONICALIZABLE } from "./canonical-json.js";
 import { CHECKPOINT_FEATURES, checkpointVersionOf, encodeAtFidelity } from "./checkpoint-store.js";
 export const REQUIREMENT_WORDS = Object.freeze([
     "resource",
@@ -33,6 +33,8 @@ export const REQUIREMENT_WORDS = Object.freeze([
     "own_tool_lists",
     "approval_targets",
     "cross_boundary",
+    "mount_site",
+    "skill_scopes",
 ]);
 export function isRequirementWord(word) {
     return typeof word === "string" && REQUIREMENT_WORDS.includes(word);
@@ -74,6 +76,7 @@ export const CHECKPOINT_STATE_REQUIREMENTS = {
     readFace: { word: "face" },
     writeFace: { word: "write_face" },
     skillGrants: { word: "skill_grants" },
+    skillScopes: { word: "skill_scopes" },
     reminderMark: DECISION_READ,
     repairBundle: DECISION_READ,
     workspaceHandle: DECISION_READ,
@@ -126,7 +129,9 @@ export const PENDING_ACTION_REQUIREMENTS = {
         implementationRevision: DECISION_READ,
         family: DECISION_READ,
         pathTarget: DECISION_READ,
+        hostTarget: DECISION_READ,
         names: { word: "call_names" },
+        engineMounted: { word: "mount_site" },
         targets: { word: "approval_targets" },
         hasBidiControls: SHOWN,
         batchToolCallIds: DECISION_READ,
@@ -212,7 +217,7 @@ class RowNotEncodable extends Error {
         this.at = at;
     }
 }
-const DIGEST_DEPTH_CAP = 128;
+const DIGEST_DEPTH_CAP = MAX_DEPTH + 1;
 function digestProjection(value, path, depth, open) {
     if (typeof value === "function")
         throw new RowNotEncodable({ path, kind: "function" });
@@ -255,24 +260,13 @@ function digestProjection(value, path, depth, open) {
         open.delete(value);
     }
 }
-export function unencodableIn(value, path) {
-    try {
-        digestProjection(value, path, 1, new Set());
-        return undefined;
-    }
-    catch (e) {
-        if (e instanceof RowNotEncodable)
-            return e.at;
-        throw e;
-    }
-}
 export function requirementsDigestOf(cp) {
     const held = Object.create(null);
     const open = new Set();
     for (const m of membersOf(cp))
         if (m.path !== "requirementsDigest")
             held[m.path] = digestProjection(m.value, m.path, 1, open);
-    const canonical = canonicalize(held);
+    const canonical = canonicalize(held, -1);
     if (canonical === UNCANONICALIZABLE)
         throw new RowNotEncodable({ path: "(row)", kind: "unreadable" });
     return createHash("sha256").update(canonical, "utf8").digest("hex");