@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/design_sync_ledger.ts

@@ -0,0 +1,142 @@
+/**
+ * The design-sync ledger (road-to-a-canvas-the-code-owns step 4.1).
+ *
+ * One `.claude/design-system/sync-ledger.json` per `.design-sync/config.json`,
+ * stating for every token path and component export which side holds what, and
+ * what the user decided. The repository is the only store of the design
+ * system; the canvas holds a projection of it. The ledger is how the user sees
+ * the difference before the host's own `/design-sync` — which only the user
+ * starts — overwrites anything.
+ *
+ * **A row without a disposition fails validation.** `plan` writes `pending` on
+ * every row that needs a decision; `reconcile` is not finished while one is
+ * left (`stage: 'reconciled'`). The key itself is mandatory at every stage, so
+ * a row cannot be written that the user was never shown.
+ *
+ * The anchor hash is OPTIONAL by design: the base of a three-way comparison is
+ * the git commit the projection was made from, never the host's anchor, whose
+ * layout is unverified at the current host.
+ */
+
+export const LEDGER_SCHEMA = 'design-sync-ledger/v1';
+export const LEDGER_RELATIVE = '.claude/design-system/sync-ledger.json';
+
+export const ROW_CLASSES = [
+    'in-sync',
+    'code-only',
+    'remote-generated',
+    'remote-only:collides',
+    'remote-only:twin',
+    'conflict',
+    'orphan',
+    'unknown',
+] as const;
+export type RowClass = (typeof ROW_CLASSES)[number];
+
+export const PROJECTION_STATES = ['prepared', 'user-reported-ran', 'host-artifacts-observed', 'picker-confirmed'] as const;
+export type ProjectionState = (typeof PROJECTION_STATES)[number];
+
+/** `pending` is a placeholder the user has not answered, never a decision. */
+export const DISPOSITIONS = ['pending', 'no-action', 'keep-code', 'take-remote', 'import-as-brief', 'keep-as-exploration'] as const;
+export type Disposition = (typeof DISPOSITIONS)[number];
+
+export interface LedgerRow {
+    key: string;
+    kind: 'token' | 'component';
+    class: RowClass;
+    base: string | null;
+    code: string | null;
+    remote: string | null;
+    disposition: Disposition;
+    /** Pre-filled by `reconcile` from the `ui_authority` posture — a proposal, not a decision. */
+    proposed?: { side: 'code' | 'remote'; primary_source: string; constraints: string[] };
+}
+
+export interface Projection {
+    projectId: string | null;
+    commit: string | null;
+    anchor_hash?: string;
+    state: ProjectionState;
+}
+
+export interface Baseline {
+    path: string;
+    projection_commit: string | null;
+}
+
+export interface Ledger {
+    schema: typeof LEDGER_SCHEMA;
+    scope_root: string;
+    config: string;
+    projection: Projection;
+    remote_reachable: boolean;
+    rows: LedgerRow[];
+    baselines?: Baseline[];
+    authority?: Record<string, unknown>;
+    briefs?: Array<Record<string, unknown>>;
+    /** Render-check counts the user accepted, by dotted field path, with the reason. */
+    render_dispositions?: Record<string, string>;
+    handover?: { recommended: boolean | null; reason: string };
+}
+
+const NEEDS_NO_DECISION: ReadonlySet<RowClass> = new Set(['in-sync', 'remote-generated', 'code-only']);
+
+/** The disposition `plan` writes when nothing has been decided yet. */
+export function defaultDisposition(cls: RowClass): Disposition {
+    return NEEDS_NO_DECISION.has(cls) ? 'no-action' : 'pending';
+}
+
+/**
+ * Validate a parsed ledger. `plan` stage accepts `pending`; `reconciled` stage
+ * does not, which is what makes "every row has a disposition" checkable.
+ */
+export function validateLedger(value: unknown, stage: 'plan' | 'reconciled' = 'plan'): string[] {
+    const errors: string[] = [];
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return ['ledger is not a JSON object'];
+    const l = value as Record<string, unknown>;
+    if (l['schema'] !== LEDGER_SCHEMA) errors.push(`schema must be "${LEDGER_SCHEMA}"`);
+    if (typeof l['scope_root'] !== 'string' || l['scope_root'] === '') errors.push('scope_root must be a non-empty string');
+    if (typeof l['config'] !== 'string') errors.push('config must name the .design-sync/config.json it belongs to');
+    const p = l['projection'] as Record<string, unknown> | undefined;
+    if (typeof p !== 'object' || p === null) errors.push('projection is required');
+    else {
+        if (p['projectId'] !== null && typeof p['projectId'] !== 'string') errors.push('projection.projectId must be a string or null');
+        if (p['commit'] !== null && typeof p['commit'] !== 'string') errors.push('projection.commit must be a string or null');
+        if (p['anchor_hash'] !== undefined && typeof p['anchor_hash'] !== 'string') errors.push('projection.anchor_hash, when present, must be a string');
+        if (!PROJECTION_STATES.includes(p['state'] as ProjectionState)) {
+            errors.push(`projection.state must be one of ${PROJECTION_STATES.join(', ')}`);
+        }
+    }
+    if (typeof l['remote_reachable'] !== 'boolean') errors.push('remote_reachable must be a boolean');
+    if (!Array.isArray(l['rows'])) return [...errors, 'rows must be an array'];
+    const seen = new Set<string>();
+    (l['rows'] as unknown[]).forEach((raw, i) => {
+        const r = (raw ?? {}) as Record<string, unknown>;
+        const at = `rows[${i}]${typeof r['key'] === 'string' ? ` (${r['key']})` : ''}`;
+        if (typeof r['key'] !== 'string' || r['key'] === '') errors.push(`${at}: key is required`);
+        else if (seen.has(`${String(r['kind'])}:${r['key']}`)) errors.push(`${at}: duplicate key`);
+        else seen.add(`${String(r['kind'])}:${r['key']}`);
+        if (r['kind'] !== 'token' && r['kind'] !== 'component') errors.push(`${at}: kind must be token or component`);
+        if (!ROW_CLASSES.includes(r['class'] as RowClass)) errors.push(`${at}: class must be one of ${ROW_CLASSES.join(', ')}`);
+        if (!('disposition' in r)) errors.push(`${at}: has no disposition`);
+        else if (!DISPOSITIONS.includes(r['disposition'] as Disposition)) errors.push(`${at}: disposition "${String(r['disposition'])}" is not one of ${DISPOSITIONS.join(', ')}`);
+        else if (stage === 'reconciled' && r['disposition'] === 'pending') errors.push(`${at}: disposition is still pending`);
+    });
+    return errors;
+}
+
+/** Deterministic serialisation — the idempotence of `plan` rests on it. */
+export function serializeLedger(ledger: Ledger): string {
+    const sortDeep = (v: unknown): unknown => {
+        if (Array.isArray(v)) return v.map(sortDeep);
+        if (typeof v === 'object' && v !== null) {
+            return Object.fromEntries(
+                Object.keys(v as Record<string, unknown>)
+                    .sort()
+                    .map((k) => [k, sortDeep((v as Record<string, unknown>)[k])]),
+            );
+        }
+        return v;
+    };
+    return `${JSON.stringify(sortDeep(ledger), null, 2)}\n`;
+}

package/src/scripts/_lib/design_sync_plan.ts

@@ -0,0 +1,177 @@
+/**
+ * `/design-system:sync plan` — classify every token and component across base,
+ * code and remote (road-to-a-canvas-the-code-owns steps 3.3, 4.3, 4.5).
+ *
+ * **The base is a commit, not the anchor (3.3).** With a projection commit in
+ * the ledger, the base is the code-side `design-system.json` as it stood at that
+ * commit, read with `git show <commit>:<path>`. Without one the comparison is
+ * two-way and a value difference is `unknown` — never a guessed three-way. Rows
+ * are keyed by token path or component export name; two rows with equal values
+ * and different keys are two rows.
+ *
+ * **Unknown is not empty (4.3).** An unreachable remote makes every row
+ * `unknown` and withholds the handover recommendation, because "nothing on the
+ * canvas collides" and "the canvas could not be read" must never print the same
+ * count. A missing `projectId` pin blocks the handover outright.
+ *
+ * **No upload route (4.4).** Nothing here writes to the canvas, calls the host's
+ * sync, or touches the network; `plan` writes the ledger and no other file.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+import type { DesignSystem } from './design_system_import.js';
+import {
+    LEDGER_SCHEMA,
+    type Ledger,
+    type LedgerRow,
+    type Projection,
+    type RowClass,
+    defaultDisposition,
+} from './design_sync_ledger.js';
+
+interface Entry {
+    kind: 'token' | 'component';
+    value: string;
+    path?: string;
+}
+
+/** One entry per token path and per component export name. */
+export function flatten(ds: DesignSystem | null): Map<string, Entry> {
+    const out = new Map<string, Entry>();
+    if (ds === null) return out;
+    const put = (prefix: string, rec: Record<string, string> | undefined): void => {
+        for (const [k, v] of Object.entries(rec ?? {})) out.set(`${prefix}.${k}`, { kind: 'token', value: v });
+    };
+    put('colors.light', ds.colors?.light);
+    put('colors.dark', ds.colors?.dark);
+    put('radius', ds.radius);
+    put('shadow', ds.shadow);
+    put('motion.durations', ds.motion?.durations);
+    put('motion.easings', ds.motion?.easings);
+    for (const f of ds.typography?.families ?? []) out.set(`typography.families.${f.role}`, { kind: 'token', value: f.name });
+    for (const s of ds.typography?.scale ?? []) out.set(`typography.scale.${s.step}`, { kind: 'token', value: s.size });
+    if (ds.spacing?.scale?.length) out.set('spacing.scale', { kind: 'token', value: JSON.stringify(ds.spacing.scale) });
+    const paths = (ds._meta?.['component_paths'] as Record<string, string> | undefined) ?? {};
+    for (const c of ds.components ?? []) {
+        const value = JSON.stringify({ classes: [...(c.observed.classes ?? [])].sort(), props: [...(c.observed.props ?? [])].sort() });
+        out.set(c.name, { kind: 'component', value, ...(paths[c.name] !== undefined ? { path: paths[c.name] } : {}) });
+    }
+    return out;
+}
+
+export function classify(
+    base: Entry | undefined,
+    code: Entry | undefined,
+    remote: Entry | undefined,
+    ctx: { baseKnown: boolean; remoteReachable: boolean; codePaths: ReadonlySet<string> },
+): RowClass {
+    if (!ctx.remoteReachable) return 'unknown';
+    if (code !== undefined && remote !== undefined) {
+        if (code.value === remote.value) return 'in-sync';
+        if (!ctx.baseKnown) return 'unknown';
+        return base !== undefined && remote.value === base.value ? 'remote-generated' : 'conflict';
+    }
+    if (code !== undefined) return 'code-only';
+    if (remote === undefined) return 'unknown';
+    if (ctx.baseKnown && base !== undefined) return 'orphan';
+    return remote.path !== undefined && ctx.codePaths.has(remote.path) ? 'remote-only:collides' : 'remote-only:twin';
+}
+
+export interface PlanInput {
+    scopeRoot: string;
+    config: string;
+    code: DesignSystem;
+    remote: DesignSystem | null;
+    base: DesignSystem | null;
+    projection: Omit<Projection, 'state'> & { state?: Projection['state'] };
+    previous?: Ledger | null;
+}
+
+export interface Handover {
+    recommended: boolean | null;
+    reason: string;
+}
+
+export function planLedger(input: PlanInput): Ledger & { handover: Handover } {
+    const code = flatten(input.code);
+    const remote = flatten(input.remote);
+    const base = flatten(input.base);
+    const remoteReachable = input.remote !== null;
+    const codePaths = new Set([...code.values()].map((e) => e.path).filter((p): p is string => p !== undefined));
+    const ctx = { baseKnown: input.base !== null, remoteReachable, codePaths };
+    const prior = new Map((input.previous?.rows ?? []).map((r) => [`${r.kind}:${r.key}`, r]));
+
+    const keys = [...new Set([...code.keys(), ...remote.keys(), ...(remoteReachable ? base.keys() : [])])].sort();
+    const rows: LedgerRow[] = [];
+    for (const key of keys) {
+        const b = base.get(key);
+        const c = code.get(key);
+        const r = remote.get(key);
+        const kind = (c ?? r ?? b)?.kind ?? 'token';
+        if (c === undefined && r === undefined) continue; // gone from both sides
+        const cls = classify(b, c, r, ctx);
+        const row: LedgerRow = {
+            key,
+            kind,
+            class: cls,
+            base: b?.value ?? null,
+            code: c?.value ?? null,
+            remote: r?.value ?? null,
+            disposition: defaultDisposition(cls),
+        };
+        const old = prior.get(`${kind}:${key}`);
+        if (old !== undefined && old.class === row.class && old.code === row.code && old.remote === row.remote) {
+            row.disposition = old.disposition;
+            if (old.proposed !== undefined) row.proposed = old.proposed;
+        }
+        rows.push(row);
+    }
+
+    const pending = rows.filter((r) => r.disposition === 'pending').length;
+    let handover: Handover;
+    if (!remoteReachable) handover = { recommended: null, reason: 'the remote could not be read — every row is unknown, so no recommendation is made' };
+    else if (input.projection.projectId === null) handover = { recommended: false, reason: 'blocked — .design-sync/config.json pins no projectId' };
+    else if (pending > 0) handover = { recommended: false, reason: `${pending} row(s) await a disposition — run reconcile first` };
+    else handover = { recommended: true, reason: 'every row is dispositioned; the user may run /design-sync' };
+
+    return {
+        schema: LEDGER_SCHEMA,
+        scope_root: input.scopeRoot,
+        config: input.config,
+        projection: {
+            projectId: input.projection.projectId,
+            commit: input.projection.commit,
+            ...(input.projection.anchor_hash !== undefined ? { anchor_hash: input.projection.anchor_hash } : {}),
+            state: input.projection.state ?? input.previous?.projection.state ?? 'prepared',
+        },
+        remote_reachable: remoteReachable,
+        rows,
+        ...(input.previous?.baselines !== undefined ? { baselines: input.previous.baselines } : {}),
+        ...(input.previous?.authority !== undefined ? { authority: input.previous.authority } : {}),
+        ...(input.previous?.briefs !== undefined ? { briefs: input.previous.briefs } : {}),
+        handover,
+    };
+}
+
+/** The two counts the user reads before any sync: what it would overwrite, what it would leave twinned. */
+export function planCounts(ledger: Pick<Ledger, 'rows'>): { overwrite: number; twin: number; unknown: number; pending: number } {
+    const n = (pred: (r: LedgerRow) => boolean): number => ledger.rows.filter(pred).length;
+    return {
+        overwrite: n((r) => r.class === 'remote-only:collides' || r.class === 'conflict'),
+        twin: n((r) => r.class === 'remote-only:twin'),
+        unknown: n((r) => r.class === 'unknown'),
+        pending: n((r) => r.disposition === 'pending'),
+    };
+}
+
+/** The base: the code-side file as it stood at the projection commit, or null. */
+export function readBaseAtCommit(cwd: string, commit: string, relPath: string): DesignSystem | null {
+    if (!/^[0-9a-f]{4,64}$/i.test(commit) || relPath.includes('\0')) return null;
+    try {
+        const text = execFileSync('git', ['show', `${commit}:${relPath}`], { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        return JSON.parse(text) as DesignSystem;
+    } catch {
+        return null;
+    }
+}

package/src/scripts/_lib/design_sync_reconcile.ts

@@ -0,0 +1,159 @@
+/**
+ * `/design-system:sync reconcile` — one authority, one store, one UI owner
+ * (road-to-a-canvas-the-code-owns steps 5.1, 6.1, 6.2, 8.3).
+ *
+ * **The resolver sets the posture; the user disposes each row (5.1).**
+ * `resolveUiAuthority` is called ONCE per scope: the canvas snapshot is the
+ * `reference` with its maturity, the code is the `incumbent`, a registered
+ * palette or type lock is a `hard_constraint`, the user's stated intent is
+ * `user`. Each `conflict` row is pre-filled with the side that posture points
+ * at and carries the posture as provenance; the resolver's own `conflicts[]` are
+ * copied verbatim. There is no value ranking beside the resolver — a proposal is
+ * a reading of the posture, and every row still needs the user's disposition.
+ *
+ * **A brief, not a write (6.1).** A remote-only component the user imports
+ * becomes a brief — the remote contract as the spec — handed to the run's UI
+ * owner, whose own coverage records each mechanic as honoured, translated or
+ * flagged (`design-artifact-lifecycle.md`). This module writes no component.
+ *
+ * **Tiers only as the detector records them (6.2).** A brief carries the tier
+ * names `detect_component_taxonomy` recorded for the project; when it recorded
+ * none, the brief carries no tier and proposes no vocabulary.
+ */
+
+import {
+    type ReferenceMaturity,
+    type Signals,
+    type UiAuthority,
+    resolveUiAuthority,
+} from './ui_authority.js';
+import { DISPOSITIONS, type Disposition, type Ledger, type LedgerRow } from './design_sync_ledger.js';
+
+export interface ReconcileInput {
+    referenceMaturity: Exclude<ReferenceMaturity, null>;
+    referencePath?: string;
+    incumbent: { coherent: boolean; palette?: string[]; type_families?: string[] };
+    locks: { palette: boolean; type_family: boolean };
+    userIntent?: Signals['user'];
+    dispositions: Record<string, Disposition>;
+    /** The tiers `detect_component_taxonomy` recorded, or none. */
+    tiers: string[];
+    owner: 'fe-design' | 'directives/ui';
+}
+
+/** Build the resolver's signals — the one place the sync inputs meet `ui_authority`. */
+export function authoritySignals(input: ReconcileInput): Signals {
+    const hard: NonNullable<Signals['hard_constraints']> = [];
+    if (input.locks.palette) hard.push('preserve_palette');
+    if (input.locks.type_family) hard.push('preserve_type_family');
+    return {
+        reference: { maturity: input.referenceMaturity, ...(input.referencePath !== undefined ? { path: input.referencePath } : {}) },
+        incumbent: input.incumbent,
+        ...(input.userIntent !== undefined ? { user: input.userIntent } : {}),
+        ...(hard.length > 0 ? { hard_constraints: hard } : {}),
+    };
+}
+
+/** Which constraint, if any, binds a row — read off the key, never off the value. */
+function bindingConstraint(row: LedgerRow, a: UiAuthority): string | null {
+    if (row.key.startsWith('colors.') && a.constraints.preserve_palette) return 'preserve_palette';
+    if (row.key.startsWith('typography.families.') && a.constraints.preserve_type_family) return 'preserve_type_family';
+    return null;
+}
+
+/** The side a posture points at for one conflict row. A proposal, never a disposition. */
+export function proposeSide(row: LedgerRow, a: UiAuthority): NonNullable<LedgerRow['proposed']> {
+    const constraints = Object.entries(a.constraints)
+        .filter(([, v]) => v === true)
+        .map(([k]) => k)
+        .sort();
+    const bound = bindingConstraint(row, a);
+    const side = bound !== null || a.primary_source.kind === 'incumbent' ? 'code' : 'remote';
+    return { side, primary_source: a.primary_source.kind, constraints };
+}
+
+export interface Brief {
+    component: string;
+    spec: string;
+    contract: string | null;
+    owner: ReconcileInput['owner'];
+    coverage: string;
+    tiers?: string[];
+}
+
+export function briefFor(row: LedgerRow, input: Pick<ReconcileInput, 'owner' | 'tiers'>): Brief {
+    return {
+        component: row.key,
+        spec: 'the remote snapshot markup and contract for this export — the spec, not a starting point',
+        contract: row.remote,
+        owner: input.owner,
+        coverage: 'the owner records each mechanic as honoured, translated or flagged; this command writes no component',
+        ...(input.tiers.length > 0 ? { tiers: [...input.tiers] } : {}),
+    };
+}
+
+const REMOTE_ONLY = new Set(['remote-only:twin', 'remote-only:collides']);
+
+export function reconcileLedger(ledger: Ledger, input: ReconcileInput): { ledger: Ledger; errors: string[] } {
+    const authority = resolveUiAuthority(authoritySignals(input));
+    const errors: string[] = [];
+    const rows = ledger.rows.map((r) => ({ ...r }));
+    for (const row of rows) {
+        if (row.class === 'conflict') row.proposed = proposeSide(row, authority);
+        const wanted = input.dispositions[row.key];
+        if (wanted === undefined) continue;
+        if (!DISPOSITIONS.includes(wanted) || wanted === 'pending') {
+            errors.push(`${row.key}: "${String(wanted)}" is not a disposition`);
+            continue;
+        }
+        if ((wanted === 'import-as-brief' || wanted === 'keep-as-exploration') && !(row.kind === 'component' && REMOTE_ONLY.has(row.class))) {
+            errors.push(`${row.key}: ${wanted} applies only to a remote-only component`);
+            continue;
+        }
+        row.disposition = wanted;
+    }
+    for (const key of Object.keys(input.dispositions)) {
+        if (!rows.some((r) => r.key === key)) errors.push(`${key}: no such row in the ledger`);
+    }
+    const briefs = rows.filter((r) => r.disposition === 'import-as-brief').map((r) => briefFor(r, input));
+    for (const r of rows) if (r.disposition === 'pending') errors.push(`${r.key}: ${r.class} row has no disposition yet`);
+    const out: Ledger = {
+        ...ledger,
+        rows,
+        authority: {
+            primary_source: authority.primary_source,
+            change_intent: authority.change_intent,
+            constraints: authority.constraints,
+            conflicts: authority.conflicts,
+            verification: authority.verification,
+            provenance: authority.provenance,
+        },
+        briefs: briefs as unknown as Array<Record<string, unknown>>,
+    };
+    return { ledger: out, errors };
+}
+
+export interface MatrixRow {
+    chapter: string;
+    claim: string;
+    evidence: 'element-screenshot' | 'not-implemented';
+    status: string;
+}
+
+/** One `design-review` fidelity-matrix row per reconciled component, evidence kind named (8.3). */
+export function matrixRows(ledger: Ledger): MatrixRow[] {
+    return ledger.rows
+        .filter((r) => r.kind === 'component' && r.disposition !== 'pending')
+        .map((r) => {
+            const baseline = (ledger.baselines ?? []).find((b) => b.path.includes(r.key));
+            return {
+                chapter: r.key,
+                claim: `contract ${r.remote ?? r.code ?? '(none)'} (${r.class})`,
+                evidence: baseline !== undefined ? 'element-screenshot' : 'not-implemented',
+                status:
+                    baseline !== undefined
+                        ? `${r.disposition}; baseline ${baseline.path}`
+                        : `${r.disposition}; no baseline recorded for this component in the ledger`,
+            };
+        });
+}

package/src/scripts/_lib/design_sync_verify.ts

@@ -0,0 +1,99 @@
+/**
+ * `/design-system:sync verify` — the review gates that read the projection
+ * (road-to-a-canvas-the-code-owns steps 7.2, 8.1, 8.4).
+ *
+ * **Baseline stamp (7.2).** Visual baselines touched in a run are listed in the
+ * ledger with the projection commit they were made against. A baseline made
+ * against a different projection commit than the ledger's current one is
+ * `stale`: it compares the code with a canvas state nobody holds any more.
+ *
+ * **Render check consumed (8.1).** The host writes `.render-check.json`. Any
+ * non-zero failure count in it — `variantsIdentical` included, the field name the
+ * 2.1.296 binary carries — without a recorded disposition fails the run. The file
+ * layout beyond that name is unverified at the current host, so the reader is
+ * shape-tolerant: it walks every numeric field whose name reads as a failure.
+ *
+ * **One verdict vocabulary (8.4).** A gate that could not run reports
+ * `unverified` or `degraded` with a reason — `ui_authority`'s `verification`
+ * values — never a silent pass.
+ */
+
+import type { Verification } from './ui_authority.js';
+import type { Ledger } from './design_sync_ledger.js';
+
+export const FAILURE_FIELD = /(fail|error|mismatch|missing|broken|identical)/i;
+
+/** Every non-zero failure count in a render-check document, by dotted path. */
+export function renderCheckFailures(doc: unknown): Record<string, number> {
+    const out: Record<string, number> = {};
+    const visit = (v: unknown, at: string, depth: number): void => {
+        if (depth > 6 || typeof v !== 'object' || v === null) return;
+        for (const [k, child] of Object.entries(v as Record<string, unknown>)) {
+            const p = at === '' ? k : `${at}.${k}`;
+            if (typeof child === 'number' && child > 0 && FAILURE_FIELD.test(k)) out[p] = child;
+            else if (Array.isArray(child) && child.length > 0 && FAILURE_FIELD.test(k)) out[p] = child.length;
+            else visit(child, p, depth + 1);
+        }
+    };
+    visit(doc, '', 0);
+    return out;
+}
+
+export interface VerifyResult {
+    verification: Verification;
+    reasons: string[];
+    failures: string[];
+    stale_baselines: string[];
+}
+
+export interface VerifyInput {
+    /** The parsed `.render-check.json`, or null when it could not be read. */
+    renderCheck: unknown;
+    /** Dispositions the user recorded for render-check counts, by dotted field path. */
+    renderDispositions: Record<string, string>;
+}
+
+export function verifyLedger(ledger: Ledger, input: VerifyInput): VerifyResult {
+    const reasons: string[] = [];
+    const failures: string[] = [];
+    let verification: Verification = 'verified';
+
+    for (const r of ledger.rows) if (r.disposition === 'pending') failures.push(`row ${r.key} (${r.class}) has no disposition`);
+
+    const current = ledger.projection.commit;
+    const stale = (ledger.baselines ?? [])
+        .filter((b) => current !== null && b.projection_commit !== current)
+        .map((b) => `${b.path} (made against ${b.projection_commit ?? 'no projection'}, current ${String(current)})`);
+    if (current === null && (ledger.baselines ?? []).length > 0) {
+        verification = 'degraded';
+        reasons.push('the ledger names no projection commit, so baseline staleness cannot be decided');
+    }
+
+    if (!ledger.remote_reachable) {
+        verification = 'unverified';
+        reasons.push('the remote could not be read when the ledger was planned — every class is unknown');
+    }
+    if (input.renderCheck === null) {
+        if (verification === 'verified') verification = 'unverified';
+        reasons.push('no .render-check.json was readable — the host render check did not run or was not found');
+    } else {
+        for (const [field, count] of Object.entries(renderCheckFailures(input.renderCheck))) {
+            if (input.renderDispositions[field] === undefined) failures.push(`render check ${field} = ${count} with no disposition`);
+        }
+    }
+    // A ledger with an unresolved row or a stale baseline did not pass, so the
+    // verdict says so on its own — a caller reading `verification` alone must
+    // never see `verified` beside a failure.
+    if (verification === 'verified' && (failures.length > 0 || stale.length > 0)) {
+        verification = 'degraded';
+        reasons.push(`${failures.length} unresolved failure(s) and ${stale.length} stale baseline(s)`);
+    }
+    return { verification, reasons, failures, stale_baselines: stale };
+}
+
+/** Record the baselines a run touched against the current projection commit. */
+export function stampBaselines(ledger: Ledger, paths: readonly string[]): Ledger {
+    const keep = (ledger.baselines ?? []).filter((b) => !paths.includes(b.path));
+    const added = paths.map((p) => ({ path: p, projection_commit: ledger.projection.commit }));
+    return { ...ledger, baselines: [...keep, ...added].sort((a, b) => a.path.localeCompare(b.path)) };
+}