@crawlcheck/sdk 1.10.0 → 1.12.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,46 @@ 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`.
+
+### Continuity in your agent framework (1.12.0)
+
+The same check where the framework fetches an MCP server's tool list, against your approved lockfile. No CrawlCheck call, no key, no new dependency: each adapter uses the framework you already have.
+
+```js
+import { withContinuity, loadMcpToolsWithContinuity } from "@crawlcheck/sdk";
+
+// OpenAI Agents SDK (@openai/agents)
+const server = new MCPServerStreamableHttp({ url });
+await server.connect();
+const agent = new Agent({ name: "a", instructions: "...", mcpServers: [withContinuity(server, lock, { mode: "observe" })] });
+
+// LangChain (@langchain/mcp-adapters)
+const client = new MultiServerMCPClient({ mcpServers: { shop: { url } } });
+const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "observe" });
+```
+
+`observe` records every difference (`console.warn`, `onRecord`, `server.continuity.records` / `tools.continuity.records`) and passes the tools through. `review` pauses the whole server on any change until `confirm` says yes. `enforce` applies the policy: a changed or new tool is withheld from the agent, and a call to it is refused, until `confirm({ tool, continuity })` re-approves it; the rest stay usable. A refusal throws `ContinuityRefused` (with `.record`). A yes is remembered for that exact definition, so a framework that lists tools every turn does not ask twice. For CrewAI, use the Python package (`crawlcheck.crewai.with_continuity`).
 
 ## 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/frameworks.d.ts

@@ -0,0 +1,39 @@
+export declare class ContinuityRefused extends Error {
+    why: any;
+    record: any;
+    tool: any;
+    constructor(why: any, record?: null, tool?: null);
+}
+/** The shared gate. lock: an approved mcp-lockfile (with lock.parts so a change can be named). */
+export declare function continuityGate(lock: any, opts?: {}): {
+    mode: any;
+    records: never[];
+    record: null;
+    paused: Set<any>;
+    keepRecord(rec: any): Promise<any>;
+    ask(req: any): Promise<boolean>;
+    /** Compare the offered tools with the lock and apply the mode. Returns the record; throws ContinuityRefused. */
+    check(tools: any, meta?: {}): Promise<any>;
+    /** Record a check that could not compare anything. Throws ContinuityRefused outside observe. */
+    fail(cls: any, detail: any): Promise<any>;
+    /** The tools the agent may see: all of them in observe mode, else without the paused ones. */
+    allowed(tools: any, nameOf?: (t: any) => any): any;
+    /** Refuse a call to a paused tool (a framework that cached an earlier list could still try it). */
+    callOk(name: any): boolean;
+};
+/**
+ * OpenAI Agents SDK (@openai/agents): wrap an MCP server (MCPServerStdio, MCPServerStreamableHttp, MCPServerSSE or your
+ * own MCPServer) so every listTools() the SDK makes is checked against lock. Everything else is the server's own.
+ *   const guarded = withContinuity(server, lock, { mode: "observe" });  new Agent({ name, instructions, mcpServers: [guarded] })
+ * The records are at guarded.continuity.records.
+ */
+export declare function withContinuity(server: any, lock: any, opts?: {}): any;
+/**
+ * LangChain (@langchain/mcp-adapters): loadMcpTools with the continuity check.
+ *   const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "observe" })
+ * client: a MultiServerMCPClient (its connection for serverName is used) or a connected MCP SDK Client. The list is read
+ * once (every page) and the LangChain tools are converted from exactly the definitions that were compared.
+ * opts.adapters: the @langchain/mcp-adapters module (default: imported on first use); opts.loadOptions: its
+ * LoadMcpToolsOptions. The gate (records) is opts.gate, or read them from opts.onRecord.
+ */
+export declare function loadMcpToolsWithContinuity(serverName: any, client: any, lock: any, opts?: {}): Promise<any>;