@crawlcheck/sdk 1.10.0 → 1.11.0

package/README.md

@@ -16,6 +16,24 @@ const { proceed, receipt } = await cc.guard("example.com", "read", { agent: "MyA
 // The receipt is a signed crawlcheck-decision; guard() verified it here and checked its key against the published directory.
 ```
 
+Since 1.11.0 `guard()` also returns `acceptance`: the separate questions a single "verified" used to answer at once, so nothing can mistake "signature valid" for "safe to proceed".
+
+| field | the question |
+|---|---|
+| `integrity_valid` | are the bytes unchanged (hashes, signature, proof paths)? |
+| `issuer_trusted` | is the signing key one CrawlCheck publishes? (`null` offline without pinned keys) |
+| `key_policy_valid` | may that key sign this object at its signing time? |
+| `freshness_valid` | inside its validity window, not dated in the future, no longer-lived than the action allows? |
+| `subject_matches` | for this domain, this action, a known decision, bound to a resolve answer? |
+| `operation_matches` / `replay_safe` | for the exact operation and nonce this request sent? (`null` when none was sent) |
+| `baseline_matches` | do the tools match the approved baseline? (`null` when no baseline was given) |
+| `assessment_complete` | did every check run, on a fully measured answer? |
+| `policy_source` | which policy produced the decision (`crawlcheck_default`, `caller_policy`, `template:<name>`, `policy_file:<id>`) |
+| `evidence_level` | `A` record integrity, `B` reproducible decision, `C` corroborated reading (the receipt's `evidence_assurance`) |
+| `policy_result` | `proceed`, `pause` or `deny`; `accepted` is `policy_result === "proceed"` |
+
+`acceptanceOf(receipt, verification, checkDecision(receipt, want))` computes the same split for a receipt you hold. A receipt is evidence and a recommendation: whether your agent acts is decided by your deployment's policy, and every receipt names the policy that produced it (`authority`). `POST https://crawlcheck.io/api/v1/preflight/replay` with a receipt re-runs the decision from the archived answer and the inputs the receipt carries; `GET /api/v1/preflight/rules` serves the rule tables that hash to `engine.rules_sha256`.
+
 Every verification returns `integrity_valid`, `issuer_trusted` and `accepted`. Act on `accepted`: it needs the signing key to be one CrawlCheck publishes, so a document someone signed with their own key is `verified` offline but never `accepted`. The client methods (`verifyDocument`, `verifyOffline`, `verifyReceiptOffline`, `guard`) check the published key directory for you.
 
 Since 1.9.1 a key the rotation record lists as retired still counts for its own signing window when the expected purpose is worked out: after a decision-key rotation, receipts the old decision key signed inside its window verify, and no other key may sign a decision made while that key was live (key-policy suite cases retired-decision-key-*).
@@ -120,7 +138,27 @@ try { await client.connect(new StreamableHTTPClientTransport(new URL(url))); }
 catch (e) { if (e instanceof McpPreflightRefused) console.log(e.stage, e.why, e.receipt.decision); else throw e; }
 ```
 
-`block`, `unsupported`, an unverifiable receipt, or `require_confirmation` with no yes refuse the connect before `initialize`. Other client stacks use the bare hooks: `mcpPreflight(cc, opts)` returns `beforeConnect`, `afterConnect` and `beforeToolCall`. A runnable demo is in `examples/mcp-preflight-demo.mjs`.
+`block`, `unsupported`, an unverifiable receipt, or `require_confirmation` with no yes refuse the connect before `initialize`.
+
+### Tool-interface continuity (1.11.0)
+
+The promise, and only this one: your agent does not silently proceed with a changed tool definition when your policy requires renewed approval ([spec](https://crawlcheck.io/spec/continuity)). Store per-part hashes with the lockfile (`lock.parts = await lockParts(tools)`) so a change is named, then pick a mode:
+
+```js
+const client = withPreflight(new Client(...), new CrawlCheck(), {
+  lock: approvedLock,                 // tools, tools_sha256, parts, server.url, approved_at
+  confirm: async (r) => askTheUser(r),   // r.continuity is the record; r.tool names a paused tool
+  continuity: { mode: "observe", onRecord: (rec) => log.write(rec) },   // then "review", then "enforce"
+});
+```
+
+| mode | what happens |
+|---|---|
+| `observe` | nothing is blocked; every check is recorded with what the policy *would* have done (`would`) |
+| `review` | every change pauses the session for a person; integrity failures still deny |
+| `enforce` | the policy applies: a changed or new tool is paused on its own (`pause_tool`) while the rest stay usable; integrity failures deny |
+
+The default policy (`CONTINUITY_DEFAULT_POLICY`) pauses added, changed-description, changed-schema and changed-annotation tools, refreshes expired evidence, pauses on an unreachable server or service, a truncated or unreadable tool list, a stale baseline or an unexpected policy version, and denies on an invalid signature, an unpublished or retired key, or a different server. Override any effect; the integrity classes stay `deny` unless you set `allow_integrity_override`, and the record says so. Exceptions (`{ tool, class, until, by, reason }`) proceed as `proceed_recorded`, never as an ordinary pass. Every record (`crawlcheck-continuity-record`) names the baseline, what was observed, each event, the policy's sha256, the mode, the outcome and its own `record_sha256`. It states interface continuity at the check point: not code attestation, not a judgement that a tool is harmless, not user authorisation. `continuityCheck(lock, tools, opts)` and `continuityFailure(cls, opts)` run the same logic without a client; the Python SDK reproduces every record byte for byte (shared golden file `test/fixtures/continuity.json`). Other client stacks use the bare hooks: `mcpPreflight(cc, opts)` returns `beforeConnect`, `afterConnect` and `beforeToolCall`. A runnable demo is in `examples/mcp-preflight-demo.mjs`.
 
 ## Do not trust the API: check the evidence yourself
 

package/dist/continuity.d.ts

@@ -0,0 +1,105 @@
+export declare const CONTINUITY_EFFECTS: string[];
+export declare const CONTINUITY_CHANGE_CLASSES: string[];
+export declare const CONTINUITY_FAILURE_CLASSES: string[];
+/** The default operator policy. Every value can be overridden; the record names the policy's sha256, so what decided is attributable. */
+export declare const CONTINUITY_DEFAULT_POLICY: Readonly<{
+    v: 1;
+    id: "crawlcheck-continuity-default";
+    max_baseline_age_days: 90;
+    effects: Readonly<{
+        unchanged: "proceed";
+        tool_added: "pause_tool";
+        tool_removed: "proceed";
+        description_changed: "pause_tool";
+        schema_changed: "pause_tool";
+        annotations_changed: "pause_tool";
+        tool_changed: "pause_tool";
+        evidence_expired: "refresh";
+        signature_invalid: "deny";
+        key_unknown: "deny";
+        key_retired: "deny";
+        server_identity_mismatch: "deny";
+        server_unavailable: "pause";
+        tool_list_truncated: "pause";
+        response_malformed: "pause";
+        baseline_stale: "pause";
+        policy_version_mismatch: "pause";
+        check_timeout: "pause";
+        service_unavailable: "pause";
+        decision_refused: "deny";
+    }>;
+}>;
+/** Per-part hashes of one tool, so a change can be named (description, schema, annotations). */
+export declare function lockToolParts(t: any): Promise<{
+    description_sha256: string;
+    schema_sha256: string;
+    annotations_sha256: string;
+}>;
+/** parts for a lockfile: { [tool name]: lockToolParts(tool) }. Store it as lock.parts next to lock.tools. */
+export declare function lockParts(tools: any): Promise<{}>;
+/** The policy in force: the default with the operator's values over it, and its sha256 (what the record names). */
+export declare function continuityPolicy(p: any): Promise<{
+    v: number;
+    id: string;
+    max_baseline_age_days: any;
+    effects: Readonly<{
+        unchanged: "proceed";
+        tool_added: "pause_tool";
+        tool_removed: "proceed";
+        description_changed: "pause_tool";
+        schema_changed: "pause_tool";
+        annotations_changed: "pause_tool";
+        tool_changed: "pause_tool";
+        evidence_expired: "refresh";
+        signature_invalid: "deny";
+        key_unknown: "deny";
+        key_retired: "deny";
+        server_identity_mismatch: "deny";
+        server_unavailable: "pause";
+        tool_list_truncated: "pause";
+        response_malformed: "pause";
+        baseline_stale: "pause";
+        policy_version_mismatch: "pause";
+        check_timeout: "pause";
+        service_unavailable: "pause";
+        decision_refused: "deny";
+    }>;
+    allow_integrity_override: boolean;
+} & {
+    sha256: string;
+}>;
+/**
+ * Compare the offered tools with the approved baseline (an mcp-lockfile, ideally with lock.parts) and apply the policy.
+ * opts: mode ("observe" | "review" | "enforce", default "enforce"), policy, exceptions [{tool, class, until, by, reason}],
+ * complete (false when tools/list returned a nextCursor you did not follow), server (the URL checked), serverIdentity
+ * (the URL the baseline was approved for; differs -> server_identity_mismatch), expectPolicySha256, now (ms).
+ */
+export declare function continuityCheck(lock: any, tools: any, opts?: {}): Promise<any>;
+/** A record for a check that could not compare anything (the server, the evidence or the service failed). cls: one of CONTINUITY_FAILURE_CLASSES. */
+export declare function continuityFailure(cls: any, opts?: {}): Promise<any>;
+/**
+ * Acceptance, split: the separate questions a single "verified: true" used to answer at once, for one decision receipt.
+ * receipt: the crawlcheck-decision. verification: verifyDocument()'s result (integrity_valid, issuer_trusted, key_policy_valid,
+ * unavailable). scope: checkDecision()'s result (its fields). opts: allowWarn, confirmed (true when a person approved a
+ * require_confirmation), lock (a continuity record or checkLock result for the same server).
+ * policy_result: proceed | pause | deny. accepted is policy_result === "proceed". Never act on integrity_valid alone.
+ */
+export declare function acceptanceOf(receipt: any, verification: any, scope: any, opts?: {}): {
+    integrity_valid: boolean;
+    issuer_trusted: any;
+    key_policy_valid: any;
+    freshness_valid: boolean;
+    subject_matches: boolean;
+    operation_matches: any;
+    replay_safe: any;
+    baseline_matches: null;
+    assessment_complete: boolean;
+    decision: any;
+    policy_source: any;
+    evidence_level: any;
+    policy_result: string;
+    accepted: boolean;
+    why: any[];
+};
+/** Which failure class a refused guard() result is (for continuityFailure). */
+export declare function continuityClassOf(g: any): "check_timeout" | "decision_refused" | "evidence_expired" | "key_retired" | "key_unknown" | "response_malformed" | "server_identity_mismatch" | "service_unavailable" | "signature_invalid";

package/dist/continuity.js

@@ -0,0 +1,284 @@
+// Tool-interface continuity (https://crawlcheck.io/spec/continuity), 1.11.0.
+//
+// The promise, and only this one: an agent does not silently proceed with a changed tool definition when the operator's
+// policy requires renewed approval. The check compares the tools a server offers now with the baseline the operator
+// approved (an mcp-lockfile), classifies every difference, applies the operator's policy, and returns a record of what
+// was compared, which policy decided, and what the runtime was told to do.
+//
+// What it does NOT establish: that a tool is harmless, that its publisher is honest, that the code behind an unchanged
+// description is unchanged, that a user authorised a call, or that no prompt injection exists. It is interface
+// continuity at the check point (before a session, or before a call when you call it there), not code attestation.
+//
+// Three modes, for the pilot ladder:
+//   observe   record what the policy would do; never change execution (outcome is always proceed, enforced false)
+//   review    every change goes to a person (pause); integrity failures still deny
+//   enforce   the policy's effects apply as written
+// Effects, weakest to strongest: proceed, proceed_recorded (an approved exception), refresh, pause_tool, pause, deny.
+// A failed exact comparison is never overridden by an interpretive assessment: nothing here reads descriptions for intent.
+import { canon } from "./verify.js";
+const subtle = globalThis.crypto && globalThis.crypto.subtle;
+const enc = new TextEncoder();
+const hex = (u8) => Array.from(u8, (b) => b.toString(16).padStart(2, "0")).join("");
+async function sha256Hex(s) { return hex(new Uint8Array(await subtle.digest("SHA-256", enc.encode(s)))); }
+export const CONTINUITY_EFFECTS = ["proceed", "proceed_recorded", "refresh", "pause_tool", "pause", "deny"];
+export const CONTINUITY_CHANGE_CLASSES = ["tool_added", "tool_removed", "description_changed", "schema_changed", "annotations_changed", "tool_changed"];
+export const CONTINUITY_FAILURE_CLASSES = ["evidence_expired", "signature_invalid", "key_unknown", "key_retired", "server_identity_mismatch", "server_unavailable", "tool_list_truncated", "response_malformed", "baseline_stale", "policy_version_mismatch", "check_timeout", "service_unavailable", "decision_refused"];
+const INTEGRITY = ["signature_invalid", "key_unknown", "key_retired", "server_identity_mismatch"];
+/** The default operator policy. Every value can be overridden; the record names the policy's sha256, so what decided is attributable. */
+export const CONTINUITY_DEFAULT_POLICY = Object.freeze({
+    v: 1, id: "crawlcheck-continuity-default", max_baseline_age_days: 90,
+    effects: Object.freeze({
+        unchanged: "proceed", tool_added: "pause_tool", tool_removed: "proceed", description_changed: "pause_tool", schema_changed: "pause_tool",
+        annotations_changed: "pause_tool", tool_changed: "pause_tool", evidence_expired: "refresh", signature_invalid: "deny", key_unknown: "deny",
+        key_retired: "deny", server_identity_mismatch: "deny", server_unavailable: "pause", tool_list_truncated: "pause", response_malformed: "pause",
+        baseline_stale: "pause", policy_version_mismatch: "pause", check_timeout: "pause", service_unavailable: "pause", decision_refused: "deny"
+    })
+});
+const WHY = {
+    tool_added: "a tool the baseline does not list is offered", tool_removed: "a tool in the baseline is no longer offered",
+    description_changed: "the tool's description differs from the approved one", schema_changed: "the tool's input schema differs from the approved one",
+    annotations_changed: "the tool's annotations differ from the approved ones", tool_changed: "the tool differs from the approved one (the baseline has no per-part hashes, so the part is unknown)",
+    evidence_expired: "the evidence is past its validity window", signature_invalid: "a signature over the evidence does not verify",
+    key_unknown: "the evidence is signed by a key that is not published", key_retired: "the signing policy rejects the key for this object at its signing time",
+    server_identity_mismatch: "the server answering is not the one the baseline names", server_unavailable: "the server could not be reached, so nothing was compared",
+    tool_list_truncated: "the tool list is incomplete (a further page was not read)", response_malformed: "the tool list could not be parsed",
+    baseline_stale: "the approved baseline is older than the policy allows", policy_version_mismatch: "the policy in force is not the version the deployment expects",
+    check_timeout: "the check did not finish in time", service_unavailable: "the verification service could not be reached; the local fallback applies",
+    decision_refused: "CrawlCheck's signed decision for the server's host did not allow the connection"
+};
+/** Per-part hashes of one tool, so a change can be named (description, schema, annotations). */
+export async function lockToolParts(t) {
+    const schema = t?.inputSchema ?? t?.input_schema ?? null;
+    return { description_sha256: await sha256Hex(canon(t?.description ?? null)), schema_sha256: await sha256Hex(canon(schema)), annotations_sha256: await sha256Hex(canon(t?.annotations ?? null)) };
+}
+/** parts for a lockfile: { [tool name]: lockToolParts(tool) }. Store it as lock.parts next to lock.tools. */
+export async function lockParts(tools) { const o = {}; for (const t of (tools ?? []).slice(0, 300))
+    o[String(t?.name ?? "").slice(0, 120)] = await lockToolParts(t); return o; }
+async function toolHash(t) { return sha256Hex(canon({ name: t?.name ?? null, description: t?.description ?? null, inputSchema: t?.inputSchema ?? t?.input_schema ?? null, annotations: t?.annotations ?? null })); }
+/** The policy in force: the default with the operator's values over it, and its sha256 (what the record names). */
+export async function continuityPolicy(p) {
+    const base = CONTINUITY_DEFAULT_POLICY, given = p && typeof p === "object" ? p : {};
+    const effects = Object.assign({}, base.effects);
+    for (const [k, v] of Object.entries(given.effects || {})) {
+        if (!(k in base.effects))
+            throw new Error("unknown continuity class: " + k);
+        if (CONTINUITY_EFFECTS.indexOf(v) < 0)
+            throw new Error("unknown effect for " + k + ": " + v);
+        effects[k] = v;
+    }
+    for (const k of INTEGRITY)
+        if (effects[k] !== "deny" && given.allow_integrity_override !== true)
+            throw new Error(k + " must stay deny (set allow_integrity_override to change it, and the record will say so)");
+    const pol = { v: 1, id: String(given.id || base.id), max_baseline_age_days: Number.isFinite(given.max_baseline_age_days) ? given.max_baseline_age_days : base.max_baseline_age_days, effects, allow_integrity_override: given.allow_integrity_override === true };
+    return Object.assign(pol, { sha256: await sha256Hex(canon(pol)) });
+}
+const rank = (e) => CONTINUITY_EFFECTS.indexOf(e);
+function excFor(exceptions, cls, tool, now) {
+    return (exceptions || []).find((x) => x && (x.class === cls || x.class === "*") && (x.tool === tool || (!x.tool && !tool) || x.tool === "*") && (!x.until || Date.parse(x.until) > now)) || null;
+}
+function modeEffect(mode, cls, eff) {
+    if (mode === "review" && eff !== "proceed" && eff !== "proceed_recorded")
+        return INTEGRITY.indexOf(cls) > -1 ? "deny" : "pause";
+    return eff;
+}
+async function finish(rec, mode) {
+    const would = rec.events.reduce((m, e) => (rank(e.policy_effect) > rank(m) ? e.policy_effect : m), "proceed");
+    const eff = rec.events.reduce((m, e) => (rank(e.effect) > rank(m) ? e.effect : m), "proceed");
+    rec.would = would;
+    rec.enforced = mode !== "observe";
+    rec.outcome = mode === "observe" ? "proceed" : eff === "pause_tool" ? "proceed" : eff === "proceed_recorded" ? "proceed" : eff;
+    rec.paused_tools = mode === "observe" ? [] : rec.events.filter((e) => e.effect === "pause_tool" && e.tool).map((e) => e.tool);
+    rec.why = rec.events.filter((e) => e.class !== "unchanged").map((e) => (e.tool ? e.tool + ": " : "") + e.why + " -> " + e.effect + (e.exception ? " (exception by " + (e.exception.by || "?") + ")" : ""));
+    if (!rec.why.length)
+        rec.why = ["the offered tools match the approved baseline"];
+    rec.record_sha256 = await sha256Hex(canon(rec));
+    return rec;
+}
+function base(opts, pol, mode) {
+    return { kind: "crawlcheck-continuity-record", v: 1, checked_at: new Date(opts.now ?? Date.now()).toISOString(), mode, server: opts.server ?? null,
+        policy: { id: pol.id, sha256: pol.sha256, integrity_override: pol.allow_integrity_override },
+        claims: "interface continuity at this check point: the offered tool definitions were compared with the approved baseline. Not code attestation, not a judgement that any tool is harmless, not user authorisation.",
+        events: [] };
+}
+function ev(rec, pol, mode, cls, tool, exceptions, now, detail) {
+    const pe = pol.effects[cls];
+    let eff = modeEffect(mode, cls, pe);
+    const ex = INTEGRITY.indexOf(cls) < 0 ? excFor(exceptions, cls, tool, now) : null;
+    if (ex && eff !== "deny")
+        eff = "proceed_recorded";
+    const e = { class: cls, tool: tool ?? null, why: WHY[cls] || cls, policy_effect: pe, effect: eff };
+    if (ex)
+        e.exception = { by: ex.by ?? null, reason: ex.reason ?? null, until: ex.until ?? null };
+    if (detail)
+        e.detail = detail;
+    rec.events.push(e);
+}
+/**
+ * Compare the offered tools with the approved baseline (an mcp-lockfile, ideally with lock.parts) and apply the policy.
+ * opts: mode ("observe" | "review" | "enforce", default "enforce"), policy, exceptions [{tool, class, until, by, reason}],
+ * complete (false when tools/list returned a nextCursor you did not follow), server (the URL checked), serverIdentity
+ * (the URL the baseline was approved for; differs -> server_identity_mismatch), expectPolicySha256, now (ms).
+ */
+export async function continuityCheck(lock, tools, opts = {}) {
+    const mode = opts.mode || "enforce";
+    if (["observe", "review", "enforce"].indexOf(mode) < 0)
+        throw new Error("mode must be observe, review or enforce");
+    const pol = await continuityPolicy(opts.policy), now = opts.now ?? Date.now(), X = opts.exceptions;
+    const rec = base(opts, pol, mode);
+    if (!Array.isArray(tools)) {
+        ev(rec, pol, mode, "response_malformed", null, X, now);
+        return finish(rec, mode);
+    }
+    const rows = [];
+    for (const t of tools.slice(0, 300))
+        rows.push({ name: String(t?.name ?? "").slice(0, 120), sha256: await toolHash(t), t });
+    const cur = {};
+    rows.forEach((r) => { cur[r.name] = r; });
+    const listHash = await sha256Hex(rows.map((r) => r.sha256).sort().join("\n"));
+    const was = {};
+    (lock?.tools ?? []).forEach((r) => { was[r.name] = r.sha256; });
+    const approvedAt = Date.parse(lock?.approved_at ?? "");
+    rec.baseline = { tools_sha256: lock?.tools_sha256 ?? null, approved_at: lock?.approved_at ?? null, age_days: isFinite(approvedAt) ? Math.floor((now - approvedAt) / 864e5) : null, server: lock?.server?.url ?? null, per_part: !!(lock && lock.parts) };
+    rec.observed = { tools_sha256: listHash, count: rows.length, complete: opts.complete !== false };
+    if (opts.expectPolicySha256 && opts.expectPolicySha256 !== pol.sha256)
+        ev(rec, pol, mode, "policy_version_mismatch", null, X, now, "expected " + opts.expectPolicySha256 + ", in force " + pol.sha256);
+    const want = opts.serverIdentity ?? lock?.server?.url ?? null;
+    if (want && opts.server && String(want).replace(/\/+$/, "") !== String(opts.server).replace(/\/+$/, ""))
+        ev(rec, pol, mode, "server_identity_mismatch", null, X, now, "baseline approved for " + want + ", checked " + opts.server);
+    if (rec.baseline.age_days !== null && rec.baseline.age_days > pol.max_baseline_age_days)
+        ev(rec, pol, mode, "baseline_stale", null, X, now, rec.baseline.age_days + " days old; the policy allows " + pol.max_baseline_age_days);
+    if (opts.complete === false)
+        ev(rec, pol, mode, "tool_list_truncated", null, X, now);
+    for (const n of Object.keys(cur).filter((n) => !(n in was)).sort())
+        ev(rec, pol, mode, "tool_added", n, X, now);
+    if (opts.complete !== false)
+        for (const n of Object.keys(was).filter((n) => !(n in cur)).sort())
+            ev(rec, pol, mode, "tool_removed", n, X, now);
+    for (const n of Object.keys(cur).filter((n) => n in was && was[n] !== cur[n].sha256).sort()) {
+        const P = lock && lock.parts && lock.parts[n];
+        if (!P) {
+            ev(rec, pol, mode, "tool_changed", n, X, now);
+            continue;
+        }
+        const q = await lockToolParts(cur[n].t);
+        let any = false;
+        if (q.description_sha256 !== P.description_sha256) {
+            ev(rec, pol, mode, "description_changed", n, X, now);
+            any = true;
+        }
+        if (q.schema_sha256 !== P.schema_sha256) {
+            ev(rec, pol, mode, "schema_changed", n, X, now);
+            any = true;
+        }
+        if (q.annotations_sha256 !== P.annotations_sha256) {
+            ev(rec, pol, mode, "annotations_changed", n, X, now);
+            any = true;
+        }
+        if (!any)
+            ev(rec, pol, mode, "tool_changed", n, X, now, "the name or a field outside description, schema and annotations changed");
+    }
+    if (!rec.events.length)
+        rec.events.push({ class: "unchanged", tool: null, why: "the offered tools match the approved baseline", policy_effect: pol.effects.unchanged, effect: modeEffect(mode, "unchanged", pol.effects.unchanged) });
+    return finish(rec, mode);
+}
+/** A record for a check that could not compare anything (the server, the evidence or the service failed). cls: one of CONTINUITY_FAILURE_CLASSES. */
+export async function continuityFailure(cls, opts = {}) {
+    if (CONTINUITY_FAILURE_CLASSES.indexOf(cls) < 0)
+        throw new Error("unknown failure class: " + cls);
+    const mode = opts.mode || "enforce", pol = await continuityPolicy(opts.policy), now = opts.now ?? Date.now();
+    const rec = base(opts, pol, mode);
+    rec.baseline = null;
+    rec.observed = null;
+    ev(rec, pol, mode, cls, null, opts.exceptions, now, opts.detail);
+    return finish(rec, mode);
+}
+/**
+ * Acceptance, split: the separate questions a single "verified: true" used to answer at once, for one decision receipt.
+ * receipt: the crawlcheck-decision. verification: verifyDocument()'s result (integrity_valid, issuer_trusted, key_policy_valid,
+ * unavailable). scope: checkDecision()'s result (its fields). opts: allowWarn, confirmed (true when a person approved a
+ * require_confirmation), lock (a continuity record or checkLock result for the same server).
+ * policy_result: proceed | pause | deny. accepted is policy_result === "proceed". Never act on integrity_valid alone.
+ */
+export function acceptanceOf(receipt, verification, scope, opts = {}) {
+    const r = receipt && typeof receipt === "object" ? receipt : {}, v = verification || {}, f = (scope && scope.fields) || {}, why = [];
+    const out = {
+        integrity_valid: v.integrity_valid === true, issuer_trusted: v.issuer_trusted === undefined ? null : v.issuer_trusted, key_policy_valid: v.key_policy_valid === undefined ? null : v.key_policy_valid,
+        freshness_valid: f.times_present === true && f.not_expired === true && f.not_future === true && f.lifetime_ok === true,
+        subject_matches: f.kind_ok === true && f.domain_matches === true && f.action_matches === true && f.decision_known === true && f.resolve_bound === true,
+        operation_matches: f.operation_matches === undefined ? null : f.operation_matches, replay_safe: f.nonce_matches === undefined ? null : f.nonce_matches,
+        baseline_matches: null, assessment_complete: Array.isArray(v.unavailable) && v.unavailable.length === 0 && !!r.resolve && r.resolve.status === "measured",
+        decision: typeof r.decision === "string" ? r.decision : null, policy_source: (r.authority && r.authority.policy_source) || null,
+        evidence_level: (r.evidence_assurance && r.evidence_assurance.level) || null, policy_result: "deny", accepted: false, why
+    };
+    const L = opts.lock;
+    if (L && L.kind === "crawlcheck-continuity-record")
+        out.baseline_matches = L.events.every((e) => e.class === "unchanged");
+    else if (L && L.verdict)
+        out.baseline_matches = L.verdict === "unchanged";
+    else if (r.assessed && r.assessed.expected_tools_sha256)
+        out.baseline_matches = r.assessed.matches === undefined ? null : r.assessed.matches;
+    if (!out.integrity_valid)
+        why.push("integrity: a check over the receipt's bytes failed or none ran");
+    if (out.issuer_trusted !== true)
+        why.push(out.issuer_trusted === null ? "issuer: not checked (no published key ids)" : "issuer: the signing key is not published");
+    if (out.key_policy_valid === false)
+        why.push("key policy: the key may not sign this object at its signing time");
+    if (!out.freshness_valid)
+        why.push("freshness: expired, dated in the future, missing times, or longer-lived than the action allows");
+    if (!out.subject_matches)
+        why.push("subject: the receipt is for another domain, action or answer, or its decision is unknown");
+    if (out.operation_matches === false)
+        why.push("operation: the receipt is scoped to another operation");
+    if (out.replay_safe === false)
+        why.push("replay: the receipt does not carry this request's nonce");
+    const hard = why.length > 0;
+    if (hard)
+        out.policy_result = "deny";
+    else if (out.baseline_matches === false) {
+        out.policy_result = "pause";
+        why.push("baseline: the tools differ from the approved baseline; re-approve before proceeding");
+    }
+    else if (out.decision === "allow")
+        out.policy_result = "proceed";
+    else if (out.decision === "warn") {
+        out.policy_result = opts.allowWarn ? "proceed" : "pause";
+        if (!opts.allowWarn)
+            why.push("decision is warn and warn is not allowed");
+    }
+    else if (out.decision === "require_confirmation") {
+        out.policy_result = opts.confirmed === true ? "proceed" : "pause";
+        if (opts.confirmed !== true)
+            why.push("a person must confirm");
+    }
+    else {
+        out.policy_result = "deny";
+        why.push("decision is " + out.decision);
+    }
+    out.accepted = out.policy_result === "proceed";
+    return out;
+}
+/** Which failure class a refused guard() result is (for continuityFailure). */
+export function continuityClassOf(g) {
+    if (!g)
+        return "service_unavailable";
+    const why = (g.why || []).join("; "), A = g.acceptance;
+    if (!g.receipt)
+        return /timed? ?out|abort/i.test(why) ? "check_timeout" : "service_unavailable";
+    if (A) {
+        if (!A.integrity_valid)
+            return "signature_invalid";
+        if (A.issuer_trusted !== true)
+            return "key_unknown";
+        if (A.key_policy_valid === false)
+            return "key_retired";
+        if (!A.freshness_valid)
+            return "evidence_expired";
+        if (!A.subject_matches)
+            return "server_identity_mismatch";
+        if (A.operation_matches === false || A.replay_safe === false)
+            return "server_identity_mismatch";
+    }
+    else if (g.verification === null)
+        return "response_malformed";
+    return "decision_refused";
+}

package/dist/index.d.ts

@@ -1,6 +1,131 @@
 import type { paths, components } from "./gen/openapi.js";
 import * as S from "./staple.js";
 export type { paths, components };
+export interface Acceptance {
+    integrity_valid: boolean;
+    issuer_trusted: boolean | null;
+    key_policy_valid: boolean | null;
+    freshness_valid: boolean;
+    subject_matches: boolean;
+    operation_matches: boolean | null;
+    replay_safe: boolean | null;
+    baseline_matches: boolean | null;
+    assessment_complete: boolean;
+    decision: string | null;
+    policy_source: string | null;
+    evidence_level: "A" | "B" | "C" | null;
+    policy_result: "proceed" | "pause" | "deny";
+    accepted: boolean;
+    why: string[];
+}
+export type ContinuityEffect = "proceed" | "proceed_recorded" | "refresh" | "pause_tool" | "pause" | "deny";
+export interface ContinuityPolicy {
+    v?: 1;
+    id?: string;
+    max_baseline_age_days?: number;
+    effects?: Partial<Record<string, ContinuityEffect>>;
+    allow_integrity_override?: boolean;
+}
+export interface ContinuityException {
+    tool?: string;
+    class: string;
+    until?: string;
+    by?: string;
+    reason?: string;
+}
+export interface ContinuityEvent {
+    class: string;
+    tool: string | null;
+    why: string;
+    policy_effect: ContinuityEffect;
+    effect: ContinuityEffect;
+    exception?: {
+        by: string | null;
+        reason: string | null;
+        until: string | null;
+    };
+    detail?: string;
+}
+export interface ContinuityRecord {
+    kind: "crawlcheck-continuity-record";
+    v: 1;
+    checked_at: string;
+    mode: "observe" | "review" | "enforce";
+    server: string | null;
+    policy: {
+        id: string;
+        sha256: string;
+        integrity_override: boolean;
+    };
+    claims: string;
+    baseline: {
+        tools_sha256: string | null;
+        approved_at: string | null;
+        age_days: number | null;
+        server: string | null;
+        per_part: boolean;
+    } | null;
+    observed: {
+        tools_sha256: string;
+        count: number;
+        complete: boolean;
+    } | null;
+    events: ContinuityEvent[];
+    would: ContinuityEffect;
+    enforced: boolean;
+    outcome: "proceed" | "refresh" | "pause" | "deny";
+    paused_tools: string[];
+    why: string[];
+    record_sha256: string;
+}
+export interface ContinuityOptions {
+    mode?: "observe" | "review" | "enforce";
+    policy?: ContinuityPolicy;
+    exceptions?: ContinuityException[];
+    complete?: boolean;
+    server?: string;
+    serverIdentity?: string;
+    expectPolicySha256?: string;
+    now?: number;
+    detail?: string;
+}
+export declare const CONTINUITY_DEFAULT_POLICY: {
+    v: 1;
+    id: string;
+    max_baseline_age_days: number;
+    effects: Record<string, ContinuityEffect>;
+};
+export declare const CONTINUITY_CHANGE_CLASSES: string[];
+export declare const CONTINUITY_FAILURE_CLASSES: string[];
+/** Compare offered tools with the approved baseline and apply the operator's policy; returns the record to keep. */
+export declare const continuityCheck: (lock: McpLock, tools: unknown, opts?: ContinuityOptions) => Promise<ContinuityRecord>;
+/** The record for a check that could not compare (server, evidence or service failed). */
+export declare const continuityFailure: (cls: string, opts?: ContinuityOptions) => Promise<ContinuityRecord>;
+/** The policy in force (default + yours) and its sha256. */
+export declare const continuityPolicy: (p?: ContinuityPolicy) => Promise<Required<ContinuityPolicy> & {
+    sha256: string;
+}>;
+/** Per-part hashes (description, schema, annotations) so a change can be named. Store lockParts(tools) as lock.parts. */
+export declare const lockToolParts: (t: McpTool) => Promise<{
+    description_sha256: string;
+    schema_sha256: string;
+    annotations_sha256: string;
+}>;
+export declare const lockParts: (tools: McpTool[]) => Promise<Record<string, {
+    description_sha256: string;
+    schema_sha256: string;
+    annotations_sha256: string;
+}>>;
+/** The separate acceptance questions for one decision receipt. Act on policy_result, never on integrity_valid alone. */
+/** Which continuity failure class a refused guard() result is. */
+export declare const continuityClassOf: (g: GuardResult | null) => string;
+export declare const acceptanceOf: (receipt: unknown, verification: unknown, scope: {
+    fields?: unknown;
+} | null, opts?: {
+    allowWarn?: boolean;
+    confirmed?: boolean | null;
+    lock?: unknown;
+}) => Acceptance;
 /** One verifier check. ok: true passed, false FAILED, null could not run (why says why) - never a pass. */
 export interface VerifyCheck {
     id: string;
@@ -180,7 +305,12 @@ export interface McpLock {
     tools: {
         name: string;
         sha256: string;
-    }[];
+    }[]; /** 1.11.0: per-part hashes (lockParts) so continuityCheck can name what changed. */
+    parts?: Record<string, {
+        description_sha256: string;
+        schema_sha256: string;
+        annotations_sha256: string;
+    }>;
     descriptions?: Record<string, string>;
     server?: {
         url?: string | null;
@@ -303,16 +433,31 @@ export interface DecisionWant {
  * time window, per-action lifetime, known decision, resolve binding); the signature and issuer are checked by
  * verifyDocument. guard() runs both. https://crawlcheck.io/spec/guard
  */
+export interface DecisionScopeFields {
+    kind_ok: boolean;
+    domain_matches: boolean;
+    action_matches: boolean;
+    operation_matches?: boolean;
+    nonce_matches?: boolean;
+    times_present: boolean;
+    not_expired: boolean;
+    not_future: boolean;
+    lifetime_ok: boolean;
+    decision_known: boolean;
+    resolve_bound: boolean;
+}
 export declare function checkDecision(receipt: unknown, want: DecisionWant): {
     ok: boolean;
     why: string[];
+    fields: DecisionScopeFields;
 };
 export interface GuardResult {
     proceed: boolean;
     receipt: DecisionReceipt | null;
     verification: (DocumentVerification & Trust) | null;
     header: Record<string, string> | null;
-    why: string[];
+    why: string[]; /** 1.11.0: the separate acceptance questions (integrity, issuer, key policy, freshness, subject, operation, replay, baseline, completeness) and policy_result. Null when no receipt came back. */
+    acceptance: Acceptance | null;
     split_view?: LogFork[]; /** Set when the domain was refused from the held revocation list, with no network call. */
     revoked?: RevokedEntry;
 }
@@ -528,6 +673,10 @@ export interface McpPreflightOptions extends PreflightOptions {
     local?: "allow" | "refuse";
     /** The server URL when the transport does not expose it. */
     serverUrl?: string;
+    /** 1.11.0: tool-interface continuity with lock. mode observe (record only), review (changes go to confirm), enforce (the policy applies). Every check is kept in state.records and passed to onRecord. https://crawlcheck.io/spec/continuity */
+    continuity?: ContinuityOptions & {
+        onRecord?: (record: ContinuityRecord) => unknown;
+    };
     onlineKeys?: boolean;
 }
 export interface McpPreflightState {
@@ -536,8 +685,11 @@ export interface McpPreflightState {
     receipt: DecisionReceipt | null;
     verification: (DocumentVerification & Trust) | null;
     decidedAt: number;
-    lockCheck: McpLockCheck | null;
+    lockCheck: McpLockCheck | ContinuityRecord | null;
     approved: Set<string> | null;
+    continuity: ContinuityRecord | null;
+    records: ContinuityRecord[];
+    pausedTools: Set<string> | null;
 }
 export interface McpPreflightHooks {
     state: McpPreflightState;
@@ -547,7 +699,9 @@ export interface McpPreflightHooks {
         receipt: DecisionReceipt | null;
         verification?: DocumentVerification & Trust;
     }>;
-    afterConnect(tools: McpTool[]): Promise<McpLockCheck | null>;
+    afterConnect(tools: McpTool[] | null, meta?: {
+        nextCursor?: string | null;
+    } | null): Promise<McpLockCheck | ContinuityRecord | null>;
     beforeToolCall(name: string, annotations?: unknown): Promise<{
         receipt: DecisionReceipt | null;
     }>;