@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/_lib/install_reach_checks.ts

@@ -34,6 +34,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { ROADMAP_ROOT_REL, scan as scanArtifactLocation } from './agent_artifact_location.js';
+import * as installed_lock from './installed_lock.js';
+import { compare_versions } from './version_order.js';
 import type { WiringCheck } from './runtime_wiring_checks.js';
 import { TOOL_TO_HOST, residualReport } from './mcp_consent_residual.js';
 import { checkSkillReach } from './skill_reach.js';
@@ -353,7 +355,19 @@ export function readInstalledVersion(projectRoot: string): string | null {
  * such a filename, and a checker that skipped the file would have called that
  * tree clean.
  */
-export function checkVersionAxis(projectRoot: string, resolvableNow: string | null): WiringCheck {
+/** The version the GLOBAL install recorded — what every session's hooks, rules and skills run. */
+export function readGlobalVersion(): string | null {
+    const recorded = (installed_lock.read_lockfile(installed_lock.lockfile_path()) as unknown as Record<string, unknown> | null)?.[
+        'agent_config_version'
+    ];
+    return typeof recorded === 'string' && recorded.trim() !== '' ? recorded.trim().replace(/^v+/, '') : null;
+}
+
+export function checkVersionAxis(
+    projectRoot: string,
+    resolvableNow: string | null,
+    globalVersion: string | null = readGlobalVersion(),
+): WiringCheck {
     const id = 'version-axis';
     const pins = readVersionPins(projectRoot);
     const installed = readInstalledVersion(projectRoot);
@@ -364,7 +378,23 @@ export function checkVersionAxis(projectRoot: string, resolvableNow: string | nu
         pins.length === 0
             ? 'pinned: none'
             : `pinned: ${pins.map((p) => `${p.version} (${p.file}${p.legacy ? ', LEGACY filename' : ''})`).join(' · ')}`;
-    const line = `${pinText} · installed: ${installed ?? 'unknown'} · resolvable now: ${resolvableNow ?? 'unknown'}`;
+    const line =
+        `${pinText} · installed: ${installed ?? 'unknown'} · global: ${globalVersion ?? 'none'} · ` +
+        `resolvable now: ${resolvableNow ?? 'unknown'}`;
+    // Only the CLI follows a pin; hooks, rules and skills run from the global
+    // install. A pin ahead of it is a project naming a version no session runs,
+    // and nothing else in this tree compares the two.
+    const ahead = pins.filter((p) => globalVersion !== null && compare_versions(p.version, globalVersion) === 1);
+    if (ahead.length > 0) {
+        return {
+            id,
+            status: 'warn',
+            message:
+                `${line} — the pin names ${ahead.map((p) => p.version).join(', ')} but the global install, which ` +
+                `every session's hooks, rules and skills run from, is ${globalVersion as string}.`,
+            remedy: 'run `agent-config update` (it installs the pinned version globally) or `agent-config upgrade`',
+        };
+    }
     const divergent = pins.filter((p) => installed !== null && p.version !== installed);
     if (divergent.length === 0) {
         return { id, status: 'ok', message: line, remedy: '' };

package/src/scripts/_lib/lineage_backfill.ts

@@ -0,0 +1,136 @@
+/**
+ * `lineage backfill --draft` — turn the tree's existing ENC1 tokens into draft lineage rows.
+ *
+ * Years of roadmaps already carry sealed source links in their Provenance blocks. This
+ * decrypts them locally, gives each a source id, and proposes a draft row only where the
+ * block itself names a mechanism and a verdict on the token's line. Everything else is
+ * reported as unclear. It writes drafts and nothing else: confirming a draft into a ledger is
+ * the owner's step, because a row the agent confirmed itself is fabricated provenance.
+ *
+ * The decrypted output lands in `agents/.harvest-local/`, inside the work tree, so the run
+ * refuses unless git ignores that directory.
+ */
+
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { gitEnv } from './git_env.js';
+import { decrypt } from './link_crypto.js';
+import { sourceId } from './source_id.js';
+
+export const BACKFILL_DIR_REL = 'agents/.harvest-local/lineage-backfill';
+
+const TOKEN_RE = /ENC1:[A-Za-z0-9+/=]+/g;
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
+const MECHANISM_RE = /\bmechanism:\s*([a-z0-9]+(?:-[a-z0-9]+)*)/;
+const VERDICT_RE = /\bverdict:\s*(adopt|adapt|reject|already|gap|deferred)\b/;
+
+export interface DecryptedToken {
+    readonly file: string;
+    readonly line: number;
+    readonly source_id: string;
+    readonly identity: string;
+    readonly in_provenance: boolean;
+}
+
+export interface DraftRow {
+    readonly file: string;
+    readonly line: number;
+    readonly source_id: string;
+    readonly mechanism_id: string;
+    readonly verdict: string;
+}
+
+export interface BackfillResult {
+    readonly tokens: DecryptedToken[];
+    readonly drafts: DraftRow[];
+    /** `file:line` of a Provenance-block token that names no mechanism and verdict. */
+    readonly unclear: string[];
+    /** `file:line` of a token no configured key opens. */
+    readonly undecryptable: string[];
+}
+
+function git(root: string, args: string[]): { status: number; stdout: string } {
+    try {
+        return { status: 0, stdout: execFileSync('git', ['-C', root, ...args], { encoding: 'utf-8', env: gitEnv(), stdio: ['ignore', 'pipe', 'ignore'] }) };
+    } catch (e) {
+        const err = e as { status?: number; stdout?: string };
+        return { status: err.status ?? 1, stdout: err.stdout ?? '' };
+    }
+}
+
+export function isIgnored(root: string, rel: string): boolean {
+    return git(root, ['check-ignore', '-q', '--no-index', `${rel}/`]).status === 0;
+}
+
+export function scanTree(root: string, keys: readonly string[]): BackfillResult {
+    const files = git(root, ['ls-files', '-z', '--', '*.md']).stdout.split('\0').filter((f) => f !== '');
+    const result: BackfillResult = { tokens: [], drafts: [], unclear: [], undecryptable: [] };
+    for (const rel of files.sort()) {
+        let text: string;
+        try {
+            text = fs.readFileSync(path.join(root, rel), 'utf-8');
+        } catch {
+            continue;
+        }
+        if (!text.includes('ENC1:')) continue;
+        let provenanceLevel = 0;
+        text.split('\n').forEach((lineText, i) => {
+            const h = HEADING_RE.exec(lineText);
+            if (h) {
+                const level = (h[1] as string).length;
+                if (/provenance/i.test(h[2] as string)) provenanceLevel = level;
+                else if (provenanceLevel > 0 && level <= provenanceLevel) provenanceLevel = 0;
+            }
+            const tokens = lineText.match(TOKEN_RE) ?? [];
+            for (const token of tokens) {
+                const at = `${rel}:${String(i + 1)}`;
+                let identity: string;
+                try {
+                    identity = decrypt(token, [...keys]);
+                } catch {
+                    result.undecryptable.push(at);
+                    continue;
+                }
+                const id = sourceId(identity, keys[0] as string);
+                const inProvenance = provenanceLevel > 0;
+                result.tokens.push({ file: rel, line: i + 1, source_id: id, identity, in_provenance: inProvenance });
+                if (!inProvenance) continue;
+                const mech = MECHANISM_RE.exec(lineText);
+                const verdict = VERDICT_RE.exec(lineText);
+                if (mech && verdict && tokens.length === 1) {
+                    result.drafts.push({ file: rel, line: i + 1, source_id: id, mechanism_id: mech[1] as string, verdict: verdict[1] as string });
+                } else {
+                    result.unclear.push(at);
+                }
+            }
+        });
+    }
+    return result;
+}
+
+export function writeBackfill(root: string, result: BackfillResult): string {
+    const out = path.join(root, BACKFILL_DIR_REL);
+    fs.mkdirSync(out, { recursive: true, mode: 0o700 });
+    const jsonl = (rows: readonly unknown[]): string => rows.map((r) => JSON.stringify(r)).join('\n') + (rows.length > 0 ? '\n' : '');
+    fs.writeFileSync(path.join(out, 'tokens.jsonl'), jsonl(result.tokens), { mode: 0o600 });
+    fs.writeFileSync(path.join(out, 'drafts.jsonl'), jsonl(result.drafts), { mode: 0o600 });
+    const report = [
+        '# Lineage backfill — drafts for the owner to confirm',
+        '',
+        `${String(result.drafts.length)} draft(s), ${String(result.unclear.length)} unclear, ${String(result.undecryptable.length)} undecryptable, from ${String(result.tokens.length)} decrypted token(s).`,
+        'No ledger row was written. Confirming a draft is the owner\'s step.',
+        '',
+        '## Drafts',
+        '',
+        ...result.drafts.map((d) => `- ${d.file}:${String(d.line)} — ${d.mechanism_id} — ${d.verdict} — ${d.source_id}`),
+        '',
+        '## Unclear',
+        '',
+        ...result.unclear.map((u) => `- ${u}`),
+        '',
+    ].join('\n');
+    fs.writeFileSync(path.join(out, 'report.md'), report, { mode: 0o600 });
+    return out;
+}

package/src/scripts/_lib/lineage_ledger.ts

@@ -0,0 +1,211 @@
+/**
+ * The local lineage ledger — the half of source provenance that never leaves the machine.
+ *
+ * Council O5 split provenance in two. The tracked tree carries a source-free decision
+ * ledger (`provenance/mechanisms.jsonl`); everything that links a source to a mechanism —
+ * which source, at which pin, read where — lives here, under the user-global runtime:
+ *
+ *   <event4u_root>/runtime/lineage/sources.jsonl  one row per source, identity sealed
+ *   <event4u_root>/runtime/lineage/edges.jsonl    source → mechanism, pin and locator sealed
+ *
+ * Every write is refused when the target sits inside a git work tree: a ledger committed by
+ * accident would put keyed ids, relations and timestamps into public history for good,
+ * which is exactly what O5 decided against. An `EVENT4U_CONFIG_HOME` pointed into a
+ * checkout is the realistic way that happens.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { enclosingWorkTree } from './git_common_dir.js';
+import { decrypt, is_token } from './link_crypto.js';
+import { SOURCE_ID_RE } from './source_id.js';
+import { event4u_root, type EnvMap } from './user_global_paths.js';
+
+export const SOURCE_KINDS = ['repo', 'url', 'video', 'paper', 'unknown'] as const;
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+/** A pin nobody recorded. Written instead of a guess, never replaced by one. */
+export const PIN_UNKNOWN = 'unknown';
+
+export interface SourceRow {
+    readonly source_id: string;
+    readonly kind: SourceKind;
+    /** ENC1 token of the source identity (URL or opaque reference). */
+    readonly identity: string;
+    /** SPDX id, or 'unknown'. Plaintext: a license names no source. */
+    readonly license: string;
+    readonly watch: boolean;
+}
+
+export interface EdgeRow {
+    readonly source_id: string;
+    readonly mechanism_id: string;
+    /** ENC1 token of the revision the mechanism was read at, or `unknown`. */
+    readonly pin: string;
+    /** ENC1 token of where inside the source, or null when nobody recorded one. */
+    readonly locator: string | null;
+}
+
+export interface LineageFinding {
+    readonly file: 'sources.jsonl' | 'edges.jsonl';
+    readonly line: number;
+    readonly message: string;
+}
+
+export class LineageError extends Error {}
+
+export function lineageDir(env?: EnvMap | null): string {
+    return path.join(event4u_root(env), 'runtime', 'lineage');
+}
+
+/** Throws when `target` would land inside a git work tree. */
+export function assertOutsideWorkTree(target: string): void {
+    const tree = enclosingWorkTree(target);
+    if (tree !== null) {
+        throw new LineageError(
+            `refusing to write ${target}: it is inside the git work tree ${tree}, and lineage data never enters a repository`,
+        );
+    }
+}
+
+/** Atomic write (temp + rename), refused inside a work tree. */
+export function writePrivateFile(target: string, body: string): void {
+    assertOutsideWorkTree(target);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.tmp-${String(process.pid)}`;
+    fs.writeFileSync(tmp, body, { mode: 0o600 });
+    fs.renameSync(tmp, target);
+}
+
+function readJsonl(file: string): unknown[] {
+    if (!fs.existsSync(file)) return [];
+    return fs
+        .readFileSync(file, 'utf-8')
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => {
+            try {
+                return JSON.parse(l) as unknown;
+            } catch {
+                return null;
+            }
+        });
+}
+
+const jsonl = (rows: readonly unknown[]): string => rows.map((r) => JSON.stringify(r)).join('\n') + (rows.length > 0 ? '\n' : '');
+
+export interface Ledger {
+    readonly sources: SourceRow[];
+    readonly edges: EdgeRow[];
+}
+
+export function hasLedger(dir: string): boolean {
+    return fs.existsSync(path.join(dir, 'sources.jsonl'));
+}
+
+export function readLedger(dir: string): Ledger {
+    return {
+        sources: readJsonl(path.join(dir, 'sources.jsonl')) as SourceRow[],
+        edges: readJsonl(path.join(dir, 'edges.jsonl')) as EdgeRow[],
+    };
+}
+
+export function writeLedger(dir: string, ledger: Ledger): void {
+    writePrivateFile(path.join(dir, 'sources.jsonl'), jsonl(ledger.sources));
+    writePrivateFile(path.join(dir, 'edges.jsonl'), jsonl(ledger.edges));
+}
+
+/** A sealed value's plaintext, or the token itself when no key opens it. */
+function opened(value: string | null, keys: readonly string[]): string | null {
+    if (value === null || !is_token(value) || keys.length === 0) return value;
+    try {
+        return decrypt(value, [...keys]);
+    } catch {
+        return value;
+    }
+}
+
+/**
+ * Add sources and edges, keeping what is there: a known source keeps its watch flag and
+ * license. Edges are append-only: an edge is added unless the newest recorded edge for the
+ * same source and mechanism already carries its pin and locator, so a moved pin, a new
+ * locator and an `unknown` edge that becomes pinned are all recorded. Sealed fields compare
+ * by plaintext under `keys` — every seal is freshly salted, so two tokens of one pin differ.
+ * Returns the counts actually added.
+ */
+export function mergeIntoLedger(dir: string, add: Ledger, keys: readonly string[] = []): { sources: number; edges: number } {
+    const cur = readLedger(dir);
+    const known = new Set(cur.sources.map((s) => s.source_id));
+    const sources = [...cur.sources];
+    let addedSources = 0;
+    for (const s of add.sources) {
+        if (known.has(s.source_id)) continue;
+        known.add(s.source_id);
+        sources.push(s);
+        addedSources += 1;
+    }
+    const edgeKey = (e: EdgeRow): string => `${e.source_id}\0${e.mechanism_id}`;
+    const newest = new Map<string, { pin: string | null; locator: string | null }>();
+    const remember = (e: EdgeRow): void => void newest.set(edgeKey(e), { pin: opened(e.pin, keys), locator: opened(e.locator, keys) });
+    cur.edges.forEach(remember);
+    const edges = [...cur.edges];
+    let addedEdges = 0;
+    for (const e of add.edges) {
+        const last = newest.get(edgeKey(e));
+        if (last !== undefined && last.pin === opened(e.pin, keys) && last.locator === opened(e.locator, keys)) continue;
+        remember(e);
+        edges.push(e);
+        addedEdges += 1;
+    }
+    writeLedger(dir, { sources, edges });
+    return { sources: addedSources, edges: addedEdges };
+}
+
+const MECHANISM_ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+function sealedOk(value: unknown, keys: readonly string[]): boolean {
+    if (!is_token(value)) return false;
+    if (keys.length === 0) return true;
+    try {
+        decrypt(value as string, [...keys]);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Validate both files. With `keys`, every sealed field must also authenticate, so a ledger
+ * sealed under a lost key is reported rather than discovered on first use.
+ */
+export function checkLedger(dir: string, keys: readonly string[] = []): LineageFinding[] {
+    const out: LineageFinding[] = [];
+    const sourceIds = new Set<string>();
+    const sealNote = keys.length > 0 ? 'an ENC1 token that decrypts with the configured key' : 'an ENC1 token';
+    readJsonl(path.join(dir, 'sources.jsonl')).forEach((raw, i) => {
+        const at = (message: string): void => void out.push({ file: 'sources.jsonl', line: i + 1, message });
+        if (typeof raw !== 'object' || raw === null) return at('not a JSON object');
+        const r = raw as Record<string, unknown>;
+        const extra = Object.keys(r).filter((k) => !['source_id', 'kind', 'identity', 'license', 'watch'].includes(k));
+        if (extra.length > 0) at(`unexpected field(s) ${extra.join(', ')}`);
+        if (typeof r.source_id !== 'string' || !SOURCE_ID_RE.test(r.source_id)) at('source_id must be src_ plus 10 hex');
+        else if (sourceIds.has(r.source_id)) at(`duplicate source_id ${r.source_id}`);
+        else sourceIds.add(r.source_id);
+        if (!(SOURCE_KINDS as readonly unknown[]).includes(r.kind)) at(`kind must be one of ${SOURCE_KINDS.join(' | ')}`);
+        if (!sealedOk(r.identity, keys)) at(`identity must be ${sealNote}`);
+        if (typeof r.license !== 'string' || r.license === '') at("license must be an SPDX id or 'unknown'");
+        if (typeof r.watch !== 'boolean') at('watch must be true or false');
+    });
+    readJsonl(path.join(dir, 'edges.jsonl')).forEach((raw, i) => {
+        const at = (message: string): void => void out.push({ file: 'edges.jsonl', line: i + 1, message });
+        if (typeof raw !== 'object' || raw === null) return at('not a JSON object');
+        const r = raw as Record<string, unknown>;
+        const extra = Object.keys(r).filter((k) => !['source_id', 'mechanism_id', 'pin', 'locator'].includes(k));
+        if (extra.length > 0) at(`unexpected field(s) ${extra.join(', ')}`);
+        if (typeof r.source_id !== 'string' || !sourceIds.has(r.source_id)) at(`source_id ${String(r.source_id)} names no row in sources.jsonl`);
+        if (typeof r.mechanism_id !== 'string' || !MECHANISM_ID_RE.test(r.mechanism_id)) at('mechanism_id must be a kebab-case slug');
+        if (r.pin !== PIN_UNKNOWN && !sealedOk(r.pin, keys)) at(`pin must be '${PIN_UNKNOWN}' or ${sealNote}`);
+        if (r.locator !== null && !sealedOk(r.locator, keys)) at(`locator must be null or ${sealNote}`);
+    });
+    return out;
+}

package/src/scripts/_lib/lineage_map.ts

@@ -0,0 +1,55 @@
+/**
+ * Two lineage views, deliberately unequal (council O6).
+ *
+ * The tracked view lives next to the repo's shared map and lists mechanisms by verdict —
+ * nothing else. Not a source id, not an identity, not a per-source count: a list of what one
+ * source fed is more identifying than the source's name would be.
+ *
+ * The source view is the owner's: source → mechanisms with identities decrypted, rendered
+ * from the local ledger into the user-global home and never into a work tree.
+ */
+
+import type { MechanismRecord } from '../lint_harvest_provenance.js';
+import type { Ledger } from './lineage_ledger.js';
+import { latestDecisions, lineageFrom } from './lineage_query.js';
+
+/** The tracked view's place: beside the shared map, carried over by every map redraw. */
+export const LINEAGE_VIEW_REL = 'agents/map/lineage.md';
+
+const VERDICT_ORDER: readonly MechanismRecord['verdict'][] = ['adopt', 'adapt', 'already', 'gap', 'deferred', 'reject'];
+
+export function renderTrackedLineage(rows: readonly MechanismRecord[]): string {
+    const latest = [...latestDecisions(rows).values()];
+    const out = [
+        '# Lineage — mechanisms by verdict',
+        '',
+        `Generated by \`code-graph map --lineage\` from \`provenance/mechanisms.jsonl\`: ${String(latest.length)} mechanism(s), latest decision each.`,
+        '',
+    ];
+    for (const verdict of VERDICT_ORDER) {
+        const group = latest.filter((r) => r.verdict === verdict).sort((a, b) => a.mechanism_id.localeCompare(b.mechanism_id));
+        if (group.length === 0) continue;
+        out.push(`## ${verdict} (${String(group.length)})`, '');
+        for (const r of group) {
+            const where = r.realised_in?.length ? ` — ${r.realised_in.map((p) => `\`${p}\``).join(', ')}` : '';
+            const owner = r.roadmap ? ` — owner \`${r.roadmap}\`` : '';
+            out.push(`- \`${r.mechanism_id}\` (${r.decided_at})${where}${owner}`);
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}
+
+export function renderSourceLineage(ledger: Ledger, keys: readonly string[], rows: readonly MechanismRecord[]): string {
+    const out = ['# Lineage — sources (local, never shared)', ''];
+    for (const s of [...ledger.sources].sort((a, b) => a.source_id.localeCompare(b.source_id))) {
+        const found = lineageFrom(ledger, s.source_id, keys, rows);
+        if (found === null) continue;
+        out.push(`## ${s.source_id} — ${found.identity}`, '', `kind ${s.kind} · license ${s.license} · watch ${s.watch ? 'on' : 'off'}`, '');
+        for (const m of found.mechanisms) {
+            out.push(`- ${m.mechanism_id} — ${m.verdict ?? 'no decision'} — pin ${m.pin}${m.locator ? ` — at ${m.locator}` : ''}`);
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}

package/src/scripts/_lib/lineage_query.ts

@@ -0,0 +1,140 @@
+/**
+ * Read-side of the lineage ledgers: what a mechanism is, what is missing, what was turned down,
+ * and — on the owner's machine only — which mechanisms one source fed.
+ *
+ * The tracked ledger is read leniently here: a row whose `realised_in` no longer exists is
+ * exactly what `lineage of` has to show, so this does not drop it the way the linter flags it.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { MECHANISMS_REL, parseLedgerText, stripLineSuffix, type MechanismRecord } from '../lint_harvest_provenance.js';
+import { PIN_UNKNOWN, type Ledger, type SourceRow } from './lineage_ledger.js';
+import { decrypt } from './link_crypto.js';
+import { SOURCE_ID_RE, sourceId } from './source_id.js';
+
+/** Every well-shaped row of `<root>/provenance/mechanisms.jsonl`, in decision order. */
+export function readDecisions(root: string): MechanismRecord[] {
+    const file = path.join(root, MECHANISMS_REL);
+    if (!fs.existsSync(file)) return [];
+    const rows = parseLedgerText(fs.readFileSync(file, 'utf-8'))
+        .parsed.map((p) => p.value)
+        .filter((v): v is MechanismRecord => typeof v === 'object' && v !== null && typeof (v as MechanismRecord).mechanism_id === 'string');
+    // Stable sort: the file is append-only, so file order breaks a same-day tie.
+    return rows.map((r, i) => ({ r, i })).sort((a, b) => a.r.decided_at.localeCompare(b.r.decided_at) || a.i - b.i).map((x) => x.r);
+}
+
+export function latestDecisions(rows: readonly MechanismRecord[]): Map<string, MechanismRecord> {
+    const out = new Map<string, MechanismRecord>();
+    for (const r of rows) out.set(r.mechanism_id, r);
+    return out;
+}
+
+export interface RealisedEdge {
+    readonly path: string;
+    /** `broken` when the file is not in the working tree — moved or deleted. */
+    readonly status: 'ok' | 'broken';
+    /** Whether the code graph has the file as a node; null when no graph was available. */
+    readonly in_graph: boolean | null;
+}
+
+export interface LineageEntry {
+    readonly mechanism_id: string;
+    readonly verdict: MechanismRecord['verdict'];
+    readonly decided_at: string;
+    readonly realised: RealisedEdge[];
+    readonly decisions: number;
+}
+
+/**
+ * The lineage of one mechanism id, or of every mechanism realised in one path. Each
+ * `realised_in` is resolved against the working tree — a moved or deleted file is a broken
+ * edge rather than a silent stale claim — and, given the code graph's node lookup, against
+ * the graph too, so an edge the graph has not indexed yet is visible as such.
+ */
+export function lineageOf(root: string, query: string, graph: { has(id: string): boolean } | null = null): LineageEntry[] {
+    const rows = readDecisions(root);
+    const latest = latestDecisions(rows);
+    const q = stripLineSuffix(query.replace(/^\.\//, ''));
+    const hits = [...latest.values()].filter(
+        (r) => r.mechanism_id === query || (r.realised_in ?? []).some((p) => stripLineSuffix(p) === q),
+    );
+    return hits
+        .sort((a, b) => a.mechanism_id.localeCompare(b.mechanism_id))
+        .map((r) => ({
+            mechanism_id: r.mechanism_id,
+            verdict: r.verdict,
+            decided_at: r.decided_at,
+            realised: (r.realised_in ?? []).map((p) => {
+                const bare = stripLineSuffix(p);
+                return {
+                    path: bare,
+                    status: fs.existsSync(path.join(root, bare)) ? ('ok' as const) : ('broken' as const),
+                    in_graph: graph === null ? null : graph.has(bare),
+                };
+            }),
+            decisions: rows.filter((x) => x.mechanism_id === r.mechanism_id).length,
+        }));
+}
+
+export interface GapEntry {
+    readonly mechanism_id: string;
+    readonly verdict: 'gap' | 'deferred';
+    readonly owner: string;
+    readonly decided_at: string;
+    readonly reopen_if?: string;
+}
+
+/**
+ * `gap` and `deferred` mechanisms that nothing has closed since. A later adopt, adapt or
+ * already closes one; so does a later reject — unless it carries `reopen_if`, in which case
+ * the mechanism stays listed with the condition, because the rejection itself says it may
+ * come back.
+ */
+export function gaps(rows: readonly MechanismRecord[]): GapEntry[] {
+    const open = new Map<string, GapEntry>();
+    for (const r of rows) {
+        if (r.verdict === 'gap' || r.verdict === 'deferred') {
+            open.set(r.mechanism_id, { mechanism_id: r.mechanism_id, verdict: r.verdict, owner: r.roadmap ?? 'open', decided_at: r.decided_at });
+        } else if (r.verdict === 'reject' && r.reopen_if !== undefined) {
+            const cur = open.get(r.mechanism_id);
+            if (cur) open.set(r.mechanism_id, { ...cur, reopen_if: r.reopen_if });
+        } else {
+            open.delete(r.mechanism_id);
+        }
+    }
+    return [...open.values()].sort((a, b) => a.mechanism_id.localeCompare(b.mechanism_id));
+}
+
+/** Mechanisms whose latest decision is a rejection. */
+export function rejected(rows: readonly MechanismRecord[]): MechanismRecord[] {
+    return [...latestDecisions(rows).values()].filter((r) => r.verdict === 'reject').sort((a, b) => a.mechanism_id.localeCompare(b.mechanism_id));
+}
+
+export interface SourceLineage {
+    readonly source: SourceRow;
+    readonly identity: string;
+    readonly mechanisms: { mechanism_id: string; verdict: MechanismRecord['verdict'] | null; pin: string; locator: string | null }[];
+}
+
+/** Source → mechanisms. `query` is a source id or a plaintext identity, hashed with `keys[0]`. */
+export function lineageFrom(ledger: Ledger, query: string, keys: readonly string[], rows: readonly MechanismRecord[]): SourceLineage | null {
+    const id = SOURCE_ID_RE.test(query) ? query : sourceId(query, keys[0] as string);
+    const source = ledger.sources.find((s) => s.source_id === id);
+    if (source === undefined) return null;
+    const latest = latestDecisions(rows);
+    const open = (token: string | null): string | null => (token === null ? null : decrypt(token, [...keys]));
+    return {
+        source,
+        identity: open(source.identity) as string,
+        mechanisms: ledger.edges
+            .filter((e) => e.source_id === id)
+            .map((e) => ({
+                mechanism_id: e.mechanism_id,
+                verdict: latest.get(e.mechanism_id)?.verdict ?? null,
+                pin: e.pin === PIN_UNKNOWN ? PIN_UNKNOWN : (open(e.pin) as string),
+                locator: open(e.locator),
+            })),
+    };
+}