@mnemom/mnemom 0.16.1 → 0.17.0-next.0

package/dist/lib/keyed-identity.js

@@ -0,0 +1,363 @@
+// ============================================================================
+// Keyed-mode identity manifest validator (issue #1429 / MNE-5522)
+//
+// Pure, I/O-free validator for the three-mode keyed-identity record: the
+// `cards/keyed-modes.manifest.yaml` binding plus the three protection-card
+// snapshots it references. It asserts the CROSS-ENTRY invariant — exactly the
+// three modes {observe, nudge, enforce}, one each, distinct identities, each
+// snapshot valid and matching the manifest — and REUSES `validateProtectionCard`
+// (cli/src/commands/protection.ts) for per-card ADR-037 validation rather than
+// re-implementing card rules (MNE-437: no logic-bearing duplication).
+//
+// No I/O, no process.exit: callers read the returned ValidationCheck[] and
+// render/aggregate. This is the deterministic guard exercised by the manifest
+// `test` verb (cli vitest): against inline fixtures AND against the real
+// committed cards/ files (the on-disk integration test in
+// cli/src/__tests__/keyed-identity.test.ts).
+// ============================================================================
+import { validateProtectionCard } from "../commands/protection.js";
+// The three enforcement modes a keyed identity may be pinned to. `off` is a
+// valid protection-card mode but NOT a keyed-mode target — a keyed identity
+// exists precisely to exercise one of the three ACTIVE modes side-by-side.
+export const KEYED_MODES = ["observe", "nudge", "enforce"];
+// The evaluation-battery model, pinned as ONE config fact (issue #1460 / D13 /
+// MNE-5707). This is the compile-time mirror of the AUTHORITATIVE `model:` field
+// in cards/keyed-modes.manifest.yaml — the manifest is the single source of
+// truth; this constant lets the validator (and its drift-guard test) assert the
+// manifest has not silently diverged from the value the codebase expects.
+// Holding the model fixed across all four lanes is what keeps the downstream
+// cost probe valid; a changed model invalidates it. Re-opening the model choice
+// is OUT of scope (MNE-5707).
+export const EVAL_BATTERY_MODEL = "claude-opus-5";
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Validate the keyed-mode manifest against the three parsed snapshots.
+ *
+ * @param manifest  Parsed `cards/keyed-modes.manifest.yaml` (`{ entries: [...] }`).
+ * @param snapshots Map of snapshot filename → parsed protection card, keyed by
+ *                  the `snapshot:` value each manifest entry declares.
+ * @returns Flat list of `{ name, passed, message }` checks (mirrors
+ *          ValidationCheck) so callers can render/aggregate. A returned list
+ *          with every `passed === true` means the record is internally
+ *          consistent; any `passed === false` is a failing invariant.
+ */
+export function validateKeyedModeManifest(manifest, snapshots) {
+    const checks = [];
+    const rawEntries = manifest.entries;
+    if (!Array.isArray(rawEntries)) {
+        checks.push({
+            name: "manifest.entries",
+            passed: false,
+            message: "Required: manifest must have an `entries` array (one object per keyed identity).",
+        });
+        return checks;
+    }
+    const entries = rawEntries;
+    // ── Pinned battery model: one authoritative config fact, no lane divergence ──
+    // `manifest.model` must be present, a string, and equal to the codebase's
+    // EVAL_BATTERY_MODEL mirror; any entry declaring its OWN `model` must match it
+    // (a divergent per-lane model would invalidate the cost probe — MNE-440).
+    checks.push(...modelConsistencyChecks(manifest, entries));
+    // ── Per-snapshot ADR-037 validation (reuse validateProtectionCard) ──
+    // Each entry references a snapshot by filename; validate the referenced card.
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const label = typeof entry.label === "string" ? entry.label : `entries[${i}]`;
+        const snapshotName = entry.snapshot;
+        if (typeof snapshotName !== "string" || snapshotName.length === 0) {
+            checks.push({
+                name: `${label}.snapshot`,
+                passed: false,
+                message: "Required: entry must reference a snapshot filename (string).",
+            });
+            continue;
+        }
+        const card = snapshots[snapshotName];
+        if (!isObject(card)) {
+            checks.push({
+                name: `${label}.snapshot`,
+                passed: false,
+                message: `Snapshot "${snapshotName}" was not provided (or did not parse to an object).`,
+            });
+            continue;
+        }
+        const cardChecks = validateProtectionCard(card);
+        const failed = cardChecks.filter((c) => !c.passed);
+        if (failed.length > 0) {
+            checks.push({
+                name: `${label}.snapshot`,
+                passed: false,
+                message: `Snapshot "${snapshotName}" is not a valid protection card: ${failed
+                    .map((f) => `${f.name}: ${f.message}`)
+                    .join("; ")}`,
+            });
+        }
+        else {
+            checks.push({
+                name: `${label}.snapshot`,
+                passed: true,
+                message: `${snapshotName} is a valid protection card`,
+            });
+        }
+    }
+    // ── Mode coverage: exactly {observe, nudge, enforce}, one each ──
+    const modeCounts = new Map();
+    for (const entry of entries) {
+        if (typeof entry.mode === "string") {
+            modeCounts.set(entry.mode, (modeCounts.get(entry.mode) ?? 0) + 1);
+        }
+    }
+    const missing = KEYED_MODES.filter((m) => !modeCounts.has(m));
+    const duplicated = KEYED_MODES.filter((m) => (modeCounts.get(m) ?? 0) > 1);
+    const unexpected = [...modeCounts.keys()].filter((m) => !KEYED_MODES.includes(m));
+    if (missing.length === 0 && duplicated.length === 0 && unexpected.length === 0) {
+        checks.push({
+            name: "modes.coverage",
+            passed: true,
+            message: `covers exactly ${KEYED_MODES.join(", ")}, one each`,
+        });
+    }
+    else {
+        const problems = [];
+        if (missing.length > 0)
+            problems.push(`missing: ${missing.join(", ")}`);
+        if (duplicated.length > 0)
+            problems.push(`duplicated: ${duplicated.join(", ")}`);
+        if (unexpected.length > 0)
+            problems.push(`unexpected: ${unexpected.join(", ")}`);
+        checks.push({
+            name: "modes.coverage",
+            passed: false,
+            message: `Must cover exactly ${KEYED_MODES.join(", ")}, one each. ${problems.join("; ")}.`,
+        });
+    }
+    // ── Distinct agent_id across entries ──
+    checks.push(distinctnessCheck(entries, "agent_id"));
+    // ── Distinct agent_hash across entries ──
+    checks.push(distinctnessCheck(entries, "agent_hash"));
+    // ── Each entry's mode equals its referenced snapshot's mode ──
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const label = typeof entry.label === "string" ? entry.label : `entries[${i}]`;
+        const snapshotName = entry.snapshot;
+        if (typeof snapshotName !== "string")
+            continue; // already reported above
+        const card = snapshots[snapshotName];
+        if (!isObject(card))
+            continue; // already reported above
+        if (entry.mode !== card.mode) {
+            checks.push({
+                name: `${label}.mode`,
+                passed: false,
+                message: `Manifest mode "${String(entry.mode)}" does not match snapshot "${snapshotName}" mode "${String(card.mode)}".`,
+            });
+        }
+        else {
+            checks.push({
+                name: `${label}.mode`,
+                passed: true,
+                message: `mode "${String(entry.mode)}" matches snapshot`,
+            });
+        }
+    }
+    // ── Each entry's agent_id matches its referenced snapshot's agent_id ──
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const label = typeof entry.label === "string" ? entry.label : `entries[${i}]`;
+        const snapshotName = entry.snapshot;
+        if (typeof snapshotName !== "string")
+            continue; // already reported above
+        const card = snapshots[snapshotName];
+        if (!isObject(card))
+            continue; // already reported above
+        if (entry.agent_id !== card.agent_id) {
+            checks.push({
+                name: `${label}.agent_id`,
+                passed: false,
+                message: `Manifest agent_id "${String(entry.agent_id)}" does not match snapshot "${snapshotName}" agent_id "${String(card.agent_id)}".`,
+            });
+        }
+        else {
+            checks.push({
+                name: `${label}.agent_id`,
+                passed: true,
+                message: `agent_id "${String(entry.agent_id)}" matches snapshot`,
+            });
+        }
+    }
+    // ── Direct (true-off) calibration lane shape ──
+    checks.push(...validateDirectLane(manifest, entries));
+    return checks;
+}
+/**
+ * Model-consistency checks: the manifest pins one authoritative `model`, and no
+ * entry may declare a divergent per-lane `model`. Returns one `model.pinned`
+ * check plus, for any entry that declares its own `model`, one per-entry check.
+ */
+function modelConsistencyChecks(manifest, entries) {
+    const checks = [];
+    const model = manifest.model;
+    if (typeof model !== "string" || model.length === 0) {
+        checks.push({
+            name: "model.pinned",
+            passed: false,
+            message: "Required: manifest must pin `model` (a non-empty string) — the single evaluation-battery model held fixed across all lanes.",
+        });
+        return checks;
+    }
+    if (model !== EVAL_BATTERY_MODEL) {
+        checks.push({
+            name: "model.pinned",
+            passed: false,
+            message: `Manifest model "${model}" does not equal EVAL_BATTERY_MODEL "${EVAL_BATTERY_MODEL}". The pinned battery model must not silently diverge (MNE-5707).`,
+        });
+    }
+    else {
+        checks.push({
+            name: "model.pinned",
+            passed: true,
+            message: `model pinned to "${model}" (matches EVAL_BATTERY_MODEL)`,
+        });
+    }
+    // Any entry that declares its own `model` must match the authoritative value.
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.model === undefined)
+            continue; // no per-lane override (the norm)
+        const label = typeof entry.label === "string" ? entry.label : `entries[${i}]`;
+        if (entry.model !== model) {
+            checks.push({
+                name: `${label}.model`,
+                passed: false,
+                message: `Entry model "${String(entry.model)}" diverges from the pinned manifest model "${model}". All lanes must use the identical model (MNE-440).`,
+            });
+        }
+        else {
+            checks.push({
+                name: `${label}.model`,
+                passed: true,
+                message: `entry model matches the pinned "${model}"`,
+            });
+        }
+    }
+    return checks;
+}
+/**
+ * Validate the fourth, DIRECT (true-off) calibration lane. It is a distinct
+ * top-level section, kept OUT of the three-mode `entries` coverage count. Asserts
+ * it declares exactly the direct-lane shape (`mode: off`, `path: direct`, a
+ * non-empty `secret_ref` distinct from every entry's) and declares NONE of the
+ * gateway-only fields (`snapshot`/`agent_id`/`agent_hash`) nor a per-lane `model`
+ * — the direct lane never touches the gateway, so any of those would be
+ * misleading dead config (MNE-440).
+ */
+function validateDirectLane(manifest, entries) {
+    const checks = [];
+    const raw = manifest.direct_lane;
+    if (!isObject(raw)) {
+        checks.push({
+            name: "direct_lane",
+            passed: false,
+            message: "Required: manifest must declare a `direct_lane` object (the true-off calibration path that bypasses the gateway).",
+        });
+        return checks;
+    }
+    const lane = raw;
+    // mode must be exactly "off" (true-off calibration).
+    if (lane.mode !== "off") {
+        checks.push({
+            name: "direct_lane.mode",
+            passed: false,
+            message: `direct_lane.mode must be "off" (true-off calibration); got "${String(lane.mode)}".`,
+        });
+    }
+    else {
+        checks.push({ name: "direct_lane.mode", passed: true, message: 'mode "off" (true-off)' });
+    }
+    // path must be exactly "direct".
+    if (lane.path !== "direct") {
+        checks.push({
+            name: "direct_lane.path",
+            passed: false,
+            message: `direct_lane.path must be "direct" (it bypasses the gateway); got "${String(lane.path)}".`,
+        });
+    }
+    else {
+        checks.push({ name: "direct_lane.path", passed: true, message: 'path "direct"' });
+    }
+    // secret_ref must be a non-empty string, distinct from every entry's.
+    if (typeof lane.secret_ref !== "string" || lane.secret_ref.length === 0) {
+        checks.push({
+            name: "direct_lane.secret_ref",
+            passed: false,
+            message: "direct_lane.secret_ref must be a non-empty string (secret-store reference name).",
+        });
+    }
+    else {
+        const entryRefs = new Set(entries.map((e) => e.secret_ref).filter((r) => typeof r === "string"));
+        if (entryRefs.has(lane.secret_ref)) {
+            checks.push({
+                name: "direct_lane.secret_ref",
+                passed: false,
+                message: `direct_lane.secret_ref "${lane.secret_ref}" must be distinct from every entry's secret_ref (the direct lane uses its own provider key).`,
+            });
+        }
+        else {
+            checks.push({
+                name: "direct_lane.secret_ref",
+                passed: true,
+                message: `secret_ref "${lane.secret_ref}" is distinct from all entry secret_refs`,
+            });
+        }
+    }
+    // Forbidden gateway-only / per-lane fields: declaring any is misleading dead
+    // config, because the direct lane never traverses the gateway (MNE-440).
+    const forbidden = ["snapshot", "agent_id", "agent_hash", "model"].filter((f) => lane[f] !== undefined);
+    if (forbidden.length > 0) {
+        checks.push({
+            name: "direct_lane.forbidden_fields",
+            passed: false,
+            message: `direct_lane must NOT declare ${forbidden.join(", ")}: it never traverses the gateway (no identity/card) and uses the authoritative top-level manifest.model. Remove the field(s) to avoid misleading dead config (MNE-440).`,
+        });
+    }
+    else {
+        checks.push({
+            name: "direct_lane.forbidden_fields",
+            passed: true,
+            message: "declares no gateway-only identity/card/model fields",
+        });
+    }
+    return checks;
+}
+/** Assert a field is present and mutually distinct across all entries. */
+function distinctnessCheck(entries, field) {
+    const values = entries.map((e) => e[field]);
+    if (values.some((v) => typeof v !== "string" || v.length === 0)) {
+        return {
+            name: `${field}.distinct`,
+            passed: false,
+            message: `Every entry must declare a non-empty ${field}.`,
+        };
+    }
+    const seen = new Set();
+    const dupes = new Set();
+    for (const v of values) {
+        if (seen.has(v))
+            dupes.add(v);
+        seen.add(v);
+    }
+    if (dupes.size > 0) {
+        return {
+            name: `${field}.distinct`,
+            passed: false,
+            message: `${field} must be distinct across entries; repeated: ${[...dupes].join(", ")}.`,
+        };
+    }
+    return {
+        name: `${field}.distinct`,
+        passed: true,
+        message: `${values.length} distinct ${field} value(s)`,
+    };
+}

package/dist/lib/protection-drift.d.ts

@@ -0,0 +1,117 @@
+/**
+ * protection-drift.ts — pure comparison between a COMMITTED protection-card
+ * snapshot (a file under `cards/`) and the LIVE canonical protection card
+ * returned by the platform.
+ *
+ * Split follows the convention `mnemom-api/src/composition/reconcile-flat-columns.ts`
+ * established: the decision logic is a pure, network-free module so it can be
+ * unit-tested exhaustively; the thin driver that actually fetches the live card
+ * lives in the command layer (`commands/protection.ts` → `mnemom protection drift`).
+ *
+ * WHAT IS BEING COMPARED (read this before extending):
+ *   - `committed` is a repo SNAPSHOT of the agent-scope card — human-authored,
+ *     declared intent. See `cards/README.md`.
+ *   - `live` is the CANONICAL COMPOSED card (`GET /v1/protection/agent/:id`,
+ *     via `getProtectionCard()`), i.e. the OUTPUT of
+ *     `composeProtectionCard(platform, org, teams…, agent)` with strictest-wins
+ *     mode resolution.
+ *   These are NOT the same object. A snapshot field matching the composed card
+ *   means "the effective posture is what the repo says it should be" — it does
+ *   NOT mean "publishing this snapshot would reproduce the live card". A
+ *   stricter scope upstream (org / team / platform floor) can raise the composed
+ *   mode above whatever the agent-scope card asks for.
+ */
+/**
+ * Fields on the canonical card that are re-derived on every compose and
+ * therefore carry no posture meaning. Comparing them would make any drift check
+ * permanently red.
+ *
+ *   - `card_version`: `compose.ts` sets it to
+ *     `protection/${new Date().toISOString().slice(0, 10)}` — a wall-clock stamp
+ *     of the LAST COMPOSE, not a semantic version. It changes whenever anything
+ *     recomposes, and never changes while the card sits untouched.
+ *   - `content_hash` / `composed_at` / `agent_protection_card_id` /
+ *     `updated_at` / `created_at` / `needs_recompose`: storage + provenance
+ *     bookkeeping written by the composer and the canonical-write RPC.
+ *
+ * The first version of this list was written from the composer's own field
+ * names. That was the wrong source: the list has to match what the SERIALIZER
+ * emits. A live read of `GET /v1/protection/agent/:id` on us-1 (2026-07-28)
+ * returns exactly:
+ *
+ *   mode, card_id, agent_id, issued_at, thresholds, card_version,
+ *   screen_surfaces, trusted_sources, protected_surface, _composition,
+ *   content_hash, version
+ *
+ * so `composed_at`, `created_at`, `updated_at`, `needs_recompose` and
+ * `agent_protection_card_id` never appear at all (kept below anyway — harmless,
+ * and they do appear on the raw DB row some callers pass in), while four
+ * derived fields the serializer DOES emit were missing: `card_id` (the
+ * server-stamped canonical id, provenance `kind: server_stamped`), `issued_at`
+ * (a compose-time stamp), `_composition` (the whole provenance envelope,
+ * `layer: derived` throughout, and itself containing `_composition.composed_at`)
+ * and `version` (the serializer's envelope version, not a posture field).
+ * Without them `--strict` reports four permanent `unrecorded` holes that no
+ * snapshot can ever close, which is precisely the state that would make an
+ * operator stop trusting the check.
+ *
+ * KNOWN COST of ignoring `version`: it is the serializer's envelope version, so
+ * a schema bump (2 → 3) passes silently here. That is the intended trade — a
+ * serializer version is not a posture claim, and an envelope change that alters
+ * a posture field will still surface as a mismatch or an unrecorded field. If
+ * the envelope version ever starts carrying posture semantics, drop it from
+ * this list.
+ */
+export declare const VOLATILE_FIELDS: readonly string[];
+export interface FieldMismatch {
+    /** Dotted path, e.g. `mode` or `screen_surfaces.tool_calls`. */
+    path: string;
+    committed: unknown;
+    live: unknown;
+}
+export interface DriftResult {
+    /**
+     * A field is present in BOTH the snapshot and the live card but the values
+     * differ. This is unambiguous drift: the repo's declared posture is not the
+     * posture actually in force. Always a failure.
+     */
+    mismatches: FieldMismatch[];
+    /**
+     * A top-level field the LIVE card carries that the snapshot does not record
+     * at all. Not a value conflict — a COVERAGE hole: that part of the live
+     * posture has no committed representation, so it could change with no diff.
+     * Reported always; fatal only under `strict`.
+     */
+    unrecorded: string[];
+    /**
+     * A top-level field the SNAPSHOT declares that the live card does not carry.
+     * The declared intent is simply not in force. Always a failure — treated as a
+     * mismatch against `undefined` would lose the distinction, so it is its own
+     * bucket.
+     */
+    missingLive: string[];
+    /** Volatile fields skipped, for transparency in the report. */
+    ignored: string[];
+}
+/**
+ * Compare a committed snapshot against the live canonical card.
+ *
+ * Pure: no I/O, no clock, no env. Both arguments are already-parsed objects.
+ */
+export declare function compareProtectionCards(committed: Record<string, unknown>, live: Record<string, unknown>): DriftResult;
+/**
+ * Policy: does this result fail the check?
+ *
+ * `mismatches` and `missingLive` always fail — the repo says one thing and the
+ * live posture is another. `unrecorded` is a coverage gap: reported by default,
+ * fatal only under `--strict`, so the check can go green today on a partial
+ * snapshot while still surfacing exactly which parts of the live posture remain
+ * unversioned. See `cards/README.md`.
+ */
+export declare function isDrift(result: DriftResult, opts?: {
+    strict?: boolean;
+}): boolean;
+/** Human-readable multi-line report. Returned, not printed, so it is testable. */
+export declare function formatDriftReport(result: DriftResult, opts?: {
+    strict?: boolean;
+}): string;

package/dist/lib/protection-drift.js

@@ -0,0 +1,180 @@
+/**
+ * protection-drift.ts — pure comparison between a COMMITTED protection-card
+ * snapshot (a file under `cards/`) and the LIVE canonical protection card
+ * returned by the platform.
+ *
+ * Split follows the convention `mnemom-api/src/composition/reconcile-flat-columns.ts`
+ * established: the decision logic is a pure, network-free module so it can be
+ * unit-tested exhaustively; the thin driver that actually fetches the live card
+ * lives in the command layer (`commands/protection.ts` → `mnemom protection drift`).
+ *
+ * WHAT IS BEING COMPARED (read this before extending):
+ *   - `committed` is a repo SNAPSHOT of the agent-scope card — human-authored,
+ *     declared intent. See `cards/README.md`.
+ *   - `live` is the CANONICAL COMPOSED card (`GET /v1/protection/agent/:id`,
+ *     via `getProtectionCard()`), i.e. the OUTPUT of
+ *     `composeProtectionCard(platform, org, teams…, agent)` with strictest-wins
+ *     mode resolution.
+ *   These are NOT the same object. A snapshot field matching the composed card
+ *   means "the effective posture is what the repo says it should be" — it does
+ *   NOT mean "publishing this snapshot would reproduce the live card". A
+ *   stricter scope upstream (org / team / platform floor) can raise the composed
+ *   mode above whatever the agent-scope card asks for.
+ */
+/**
+ * Fields on the canonical card that are re-derived on every compose and
+ * therefore carry no posture meaning. Comparing them would make any drift check
+ * permanently red.
+ *
+ *   - `card_version`: `compose.ts` sets it to
+ *     `protection/${new Date().toISOString().slice(0, 10)}` — a wall-clock stamp
+ *     of the LAST COMPOSE, not a semantic version. It changes whenever anything
+ *     recomposes, and never changes while the card sits untouched.
+ *   - `content_hash` / `composed_at` / `agent_protection_card_id` /
+ *     `updated_at` / `created_at` / `needs_recompose`: storage + provenance
+ *     bookkeeping written by the composer and the canonical-write RPC.
+ *
+ * The first version of this list was written from the composer's own field
+ * names. That was the wrong source: the list has to match what the SERIALIZER
+ * emits. A live read of `GET /v1/protection/agent/:id` on us-1 (2026-07-28)
+ * returns exactly:
+ *
+ *   mode, card_id, agent_id, issued_at, thresholds, card_version,
+ *   screen_surfaces, trusted_sources, protected_surface, _composition,
+ *   content_hash, version
+ *
+ * so `composed_at`, `created_at`, `updated_at`, `needs_recompose` and
+ * `agent_protection_card_id` never appear at all (kept below anyway — harmless,
+ * and they do appear on the raw DB row some callers pass in), while four
+ * derived fields the serializer DOES emit were missing: `card_id` (the
+ * server-stamped canonical id, provenance `kind: server_stamped`), `issued_at`
+ * (a compose-time stamp), `_composition` (the whole provenance envelope,
+ * `layer: derived` throughout, and itself containing `_composition.composed_at`)
+ * and `version` (the serializer's envelope version, not a posture field).
+ * Without them `--strict` reports four permanent `unrecorded` holes that no
+ * snapshot can ever close, which is precisely the state that would make an
+ * operator stop trusting the check.
+ *
+ * KNOWN COST of ignoring `version`: it is the serializer's envelope version, so
+ * a schema bump (2 → 3) passes silently here. That is the intended trade — a
+ * serializer version is not a posture claim, and an envelope change that alters
+ * a posture field will still surface as a mismatch or an unrecorded field. If
+ * the envelope version ever starts carrying posture semantics, drop it from
+ * this list.
+ */
+export const VOLATILE_FIELDS = [
+    "_composition",
+    "agent_protection_card_id",
+    "card_id",
+    "card_version",
+    "composed_at",
+    "content_hash",
+    "created_at",
+    "issued_at",
+    "needs_recompose",
+    "updated_at",
+    "version",
+];
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Structural equality good enough for card values (scalars, arrays, nested objects). */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ka = Object.keys(a).sort();
+        const kb = Object.keys(b).sort();
+        return ka.length === kb.length && ka.every((k, i) => k === kb[i] && deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/**
+ * Recurse into nested objects so a one-surface flip reports as
+ * `screen_surfaces.tool_calls` rather than dumping both whole objects.
+ * Keys the live side has but the snapshot does not, BELOW the top level, are
+ * reported as nested `unrecorded` paths (same coverage-hole semantics).
+ */
+function walk(committed, live, prefix, out) {
+    for (const key of Object.keys(committed)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (!prefix && VOLATILE_FIELDS.includes(key)) {
+            out.ignored.push(path);
+            continue;
+        }
+        const c = committed[key];
+        const l = live[key];
+        if (!(key in live)) {
+            out.missingLive.push(path);
+            continue;
+        }
+        if (isPlainObject(c) && isPlainObject(l)) {
+            walk(c, l, path, out);
+            continue;
+        }
+        if (!deepEqual(c, l)) {
+            out.mismatches.push({ path, committed: c, live: l });
+        }
+    }
+    for (const key of Object.keys(live)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (!prefix && VOLATILE_FIELDS.includes(key)) {
+            if (!out.ignored.includes(path))
+                out.ignored.push(path);
+            continue;
+        }
+        if (!(key in committed))
+            out.unrecorded.push(path);
+    }
+}
+/**
+ * Compare a committed snapshot against the live canonical card.
+ *
+ * Pure: no I/O, no clock, no env. Both arguments are already-parsed objects.
+ */
+export function compareProtectionCards(committed, live) {
+    const out = { mismatches: [], unrecorded: [], missingLive: [], ignored: [] };
+    walk(committed, live, "", out);
+    out.mismatches.sort((a, b) => a.path.localeCompare(b.path));
+    out.unrecorded.sort();
+    out.missingLive.sort();
+    out.ignored.sort();
+    return out;
+}
+/**
+ * Policy: does this result fail the check?
+ *
+ * `mismatches` and `missingLive` always fail — the repo says one thing and the
+ * live posture is another. `unrecorded` is a coverage gap: reported by default,
+ * fatal only under `--strict`, so the check can go green today on a partial
+ * snapshot while still surfacing exactly which parts of the live posture remain
+ * unversioned. See `cards/README.md`.
+ */
+export function isDrift(result, opts = {}) {
+    if (result.mismatches.length > 0 || result.missingLive.length > 0)
+        return true;
+    return opts.strict === true && result.unrecorded.length > 0;
+}
+/** Human-readable multi-line report. Returned, not printed, so it is testable. */
+export function formatDriftReport(result, opts = {}) {
+    const lines = [];
+    for (const m of result.mismatches) {
+        lines.push(`MISMATCH  ${m.path}: committed=${JSON.stringify(m.committed)} live=${JSON.stringify(m.live)}`);
+    }
+    for (const p of result.missingLive) {
+        lines.push(`MISSING   ${p}: declared in the committed snapshot, absent from the live card`);
+    }
+    for (const p of result.unrecorded) {
+        const tag = opts.strict === true ? "UNRECORDED" : "unrecorded";
+        lines.push(`${tag.padEnd(9)} ${p}: present on the live card, not represented in the snapshot`);
+    }
+    if (result.ignored.length > 0) {
+        lines.push(`ignored   volatile/derived fields: ${result.ignored.join(", ")}`);
+    }
+    if (lines.length === 0)
+        lines.push("no differences");
+    return lines.join("\n");
+}