@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/code_graph/query.ts

@@ -0,0 +1,290 @@
+/**
+ * Query tier — one engine, two sources (ADR-124 § 2). Runs identically over
+ * the native cache and a consumer-shipped `graph.json`; every answer names
+ * which source answered. BFS/DFS with a token budget; hybrid seed-matching
+ * (exact id / label → BM25 fallback via `_lib/lexical_index.ts`). All string
+ * fields pass the retrieved-content sanitizer before returning.
+ */
+import * as fs from 'node:fs';
+
+import { LexicalIndex, tokenize } from '../_lib/lexical_index.js';
+import { sanitizeLabel } from './sanitize.js';
+import { emitSqliteTwin, loadSerializedFromTwin } from './sqlite_store.js';
+import type { CodeEdge, CodeGraph } from './types.js';
+import { validateGraph } from './validate.js';
+
+const APPROX_CHARS_PER_TOKEN = 4;
+
+export interface LoadedGraph {
+    graph: CodeGraph;
+    source: string; // attribution path
+    byId: Map<string, CodeGraph['nodes'][number]>;
+    out: Map<string, CodeEdge[]>;
+    in: Map<string, CodeEdge[]>;
+    lex: LexicalIndex;
+}
+
+export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
+    // Prefer the derived SQLite twin (ADR-129): checksum/stat-verified against
+    // the canonical JSON, byte-identical content, ~1/90 the load cost at
+    // consumer scale. Fallback = parse the JSON — and best-effort re-emit the
+    // twin from it (zero-touch rebuild-on-drift, Phase 7).
+    const fromTwin = loadSerializedFromTwin(graphPath);
+    const raw = fromTwin ?? fs.readFileSync(graphPath, 'utf-8');
+    const parsed = JSON.parse(raw) as unknown;
+    const v = validateGraph(parsed);
+    if (!v.ok) throw new Error(`invalid graph at ${graphPath}: ${v.errors.slice(0, 3).join('; ')}`);
+    const graph = parsed as CodeGraph;
+    if (fromTwin === null) {
+        emitSqliteTwin(graph, raw, graphPath);
+    }
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    const outM = new Map<string, CodeEdge[]>();
+    const inM = new Map<string, CodeEdge[]>();
+    const add = (m: Map<string, CodeEdge[]>, k: string, e: CodeEdge): void => {
+        const arr = m.get(k);
+        if (arr) arr.push(e);
+        else m.set(k, [e]);
+    };
+    for (const e of graph.edges) {
+        add(outM, e.source, e);
+        add(inM, e.target, e);
+    }
+    const lex = new LexicalIndex(graph.nodes.map((n) => ({ id: n.id, text: `${n.label} ${n.id}` })));
+    return { graph, source, byId, out: outM, in: inM, lex };
+}
+
+interface SeedResolution {
+    ids: string[];
+    /** true when NEITHER an exact-id nor an exact-label match was found and
+     * resolution fell back to BM25 — a best-guess, not a confirmed hit. */
+    weak: boolean;
+}
+
+/** Resolve a free-text seed to node ids: exact id → exact label → BM25. */
+function resolveSeedsTiered(g: LoadedGraph, seed: string, limit = 5): SeedResolution {
+    if (g.byId.has(seed)) return { ids: [seed], weak: false };
+    const exactLabel = g.graph.nodes.filter((n) => n.label === seed).map((n) => n.id);
+    if (exactLabel.length) return { ids: exactLabel.slice(0, limit), weak: false };
+    const ranked = g.lex.rank(tokenize(seed)).filter((r) => r.score > 0);
+    return { ids: ranked.slice(0, limit).map((r) => r.id), weak: true };
+}
+
+/** Resolve a free-text seed to node ids: exact id → exact label → BM25. */
+export function resolveSeeds(g: LoadedGraph, seed: string, limit = 5): string[] {
+    return resolveSeedsTiered(g, seed, limit).ids;
+}
+
+function label(g: LoadedGraph, id: string): string {
+    return sanitizeLabel(g.byId.get(id)?.label ?? id);
+}
+function edgeLine(g: LoadedGraph, e: CodeEdge): string {
+    const cand = e.candidates?.length ? ` [${e.candidates.map((c) => sanitizeLabel(c)).join(', ')}]` : '';
+    return `${e.confidence} ${sanitizeLabel(e.source)} --${e.relation}--> ${sanitizeLabel(e.target)}${cand}`;
+}
+
+/**
+ * A file + (when known) a 1-based inclusive line range worth reading directly
+ * — surfaced whenever the engine dropped or under-trusted something instead
+ * of silently truncating it (Phase 9 D4: "a read plan instead of silent
+ * truncation").
+ */
+export interface RecommendedRead {
+    path: string;
+    lines: [number, number] | null;
+}
+
+export interface QueryResult {
+    source: string;
+    seeds: string[];
+    lines: string[];
+    truncated: boolean;
+    recommended_reads: RecommendedRead[];
+}
+
+function readKey(r: RecommendedRead): string {
+    return r.lines ? `${r.path}:${r.lines[0]}-${r.lines[1]}` : r.path;
+}
+
+/** A node's file + line range, or `null` for an unresolved `symbol:*`
+ * placeholder (nothing real to read) or a node with no location info. */
+function recommendedReadFor(g: LoadedGraph, id: string): RecommendedRead | null {
+    const n = g.byId.get(id);
+    if (!n) return null;
+    const loc = n.source_location;
+    return { path: n.source_file, lines: loc.length >= 3 ? [loc[0] as number, loc[2] as number] : null };
+}
+
+/** One relation line plus the node id (if any) a reader should go inspect
+ * directly when this line gets dropped by the budget. */
+interface LineEntry {
+    text: string;
+    focusId?: string;
+}
+
+/**
+ * Apply the token budget to `entries`, then translate BOTH failure classes
+ * this delta targets into a deterministic `recommended_reads` list: every
+ * entry the budget dropped, plus every read the caller already flagged as
+ * weak (an under-threshold/BM25-fallback seed match) — deduped by
+ * path+line-range, insertion-ordered for determinism.
+ */
+function budgetedLines(
+    g: LoadedGraph,
+    source: string,
+    seeds: string[],
+    entries: LineEntry[],
+    budget: number,
+    weakSeedReads: RecommendedRead[] = [],
+): QueryResult {
+    const cap = budget * APPROX_CHARS_PER_TOKEN;
+    const kept: string[] = [];
+    const dropped: LineEntry[] = [];
+    let used = 0;
+    let truncated = false;
+    for (const entry of entries) {
+        if (!truncated && used + entry.text.length <= cap) {
+            kept.push(entry.text);
+            used += entry.text.length + 1;
+        } else {
+            truncated = true;
+            dropped.push(entry);
+        }
+    }
+    const recommended = new Map<string, RecommendedRead>();
+    for (const r of weakSeedReads) recommended.set(readKey(r), r);
+    for (const entry of dropped) {
+        if (!entry.focusId) continue;
+        const r = recommendedReadFor(g, entry.focusId);
+        if (r) recommended.set(readKey(r), r);
+    }
+    return { source, seeds, lines: kept, truncated, recommended_reads: [...recommended.values()] };
+}
+
+function weakSeedReads(g: LoadedGraph, resolution: SeedResolution): RecommendedRead[] {
+    if (!resolution.weak) return [];
+    const out: RecommendedRead[] = [];
+    for (const id of resolution.ids) {
+        const r = recommendedReadFor(g, id);
+        if (r) out.push(r);
+    }
+    return out;
+}
+
+/** `query <seed>` — the seed's direct (1-hop) outgoing relations. */
+export function query(g: LoadedGraph, seed: string, budget = 1500): QueryResult {
+    const resolution = resolveSeedsTiered(g, seed);
+    const seeds = resolution.ids;
+    const entries: LineEntry[] = [];
+    for (const s of seeds) for (const e of g.out.get(s) ?? []) entries.push({ text: edgeLine(g, e), focusId: e.target });
+    return budgetedLines(g, g.source, seeds.map((s) => label(g, s)), entries, budget, weakSeedReads(g, resolution));
+}
+
+/** `explain <seed>` — 2-hop neighbourhood (out-edges of seeds + their targets). */
+export function explain(g: LoadedGraph, seed: string, budget = 1500): QueryResult {
+    const resolution = resolveSeedsTiered(g, seed);
+    const seeds = resolution.ids;
+    const seen = new Set<string>();
+    const entries: LineEntry[] = [];
+    const frontier = [...seeds];
+    for (let hop = 0; hop < 2 && frontier.length; hop += 1) {
+        const next: string[] = [];
+        for (const s of frontier.splice(0)) {
+            if (seen.has(s)) continue;
+            seen.add(s);
+            for (const e of g.out.get(s) ?? []) {
+                entries.push({ text: edgeLine(g, e), focusId: e.target });
+                next.push(e.target);
+            }
+        }
+        frontier.push(...next);
+    }
+    return budgetedLines(g, g.source, seeds.map((s) => label(g, s)), entries, budget, weakSeedReads(g, resolution));
+}
+
+/** `affected <target>` — reverse BFS: who calls / references the target. */
+export function affected(g: LoadedGraph, target: string, depth = 2, budget = 1500): QueryResult {
+    const resolution = resolveSeedsTiered(g, target);
+    const seeds = resolution.ids;
+    const seen = new Set<string>(seeds);
+    const entries: LineEntry[] = [];
+    let frontier = [...seeds];
+    for (let d = 0; d < depth && frontier.length; d += 1) {
+        const next: string[] = [];
+        for (const t of frontier) {
+            for (const e of g.in.get(t) ?? []) {
+                // the newly-discovered node here is the CALLER (e.source) —
+                // e.target is already a known seed, so that side carries no
+                // new read-plan information.
+                entries.push({ text: edgeLine(g, e), focusId: e.source });
+                if (!seen.has(e.source)) {
+                    seen.add(e.source);
+                    next.push(e.source);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return budgetedLines(g, g.source, seeds.map((s) => label(g, s)), entries, budget, weakSeedReads(g, resolution));
+}
+
+/** `path <a> <b>` — shortest undirected path (direction preserved per edge). */
+export function path(g: LoadedGraph, a: string, b: string, budget = 1500): QueryResult {
+    const startRes = resolveSeedsTiered(g, a, 1);
+    const goalRes = resolveSeedsTiered(g, b, 1);
+    const starts = startRes.ids;
+    const goals = new Set(goalRes.ids);
+    if (!starts.length || !goals.size) return { source: g.source, seeds: [], lines: [], truncated: false, recommended_reads: [] };
+    const start = starts[0] as string;
+    const prev = new Map<string, CodeEdge>();
+    const seen = new Set<string>([start]);
+    let frontier = [start];
+    let hit: string | null = goals.has(start) ? start : null;
+    while (frontier.length && !hit) {
+        const next: string[] = [];
+        for (const cur of frontier) {
+            const adj = [...(g.out.get(cur) ?? []), ...(g.in.get(cur) ?? [])];
+            for (const e of adj) {
+                const nb = e.source === cur ? e.target : e.source;
+                if (seen.has(nb)) continue;
+                seen.add(nb);
+                prev.set(nb, e);
+                if (goals.has(nb)) {
+                    hit = nb;
+                    break;
+                }
+                next.push(nb);
+            }
+            if (hit) break;
+        }
+        frontier = next;
+    }
+    const seedReads = [...weakSeedReads(g, startRes), ...weakSeedReads(g, goalRes)];
+    if (!hit) {
+        return {
+            source: g.source,
+            seeds: [label(g, start)],
+            lines: ['(no path found)'],
+            truncated: false,
+            recommended_reads: [...new Map(seedReads.map((r) => [readKey(r), r])).values()],
+        };
+    }
+    const chain: CodeEdge[] = [];
+    let cur = hit;
+    while (prev.has(cur)) {
+        const e = prev.get(cur) as CodeEdge;
+        chain.unshift(e);
+        cur = e.source === cur ? e.target : e.source;
+    }
+    const entries = chain.map((e) => ({ text: edgeLine(g, e), focusId: e.target }));
+    return budgetedLines(g, g.source, [label(g, start), label(g, hit)], entries, budget, seedReads);
+}
+
+/** Merge several `QueryResult`s (e.g. one per `--since` seed) into one,
+ * de-duplicating `recommended_reads` by path+line-range so a read plan never
+ * repeats the same file twice across merged seeds. */
+export function mergeRecommendedReads(results: readonly QueryResult[]): RecommendedRead[] {
+    const merged = new Map<string, RecommendedRead>();
+    for (const r of results) for (const rr of r.recommended_reads) merged.set(readKey(rr), rr);
+    return [...merged.values()];
+}

package/src/scripts/code_graph/sanitize.ts

@@ -0,0 +1,30 @@
+/**
+ * Retrieved-content sanitizer. Graph node labels, file paths, and target ids
+ * are attacker-writable in a hostile repo; every string field passes through
+ * here before it re-enters the agent's context (hostile-repo injection row,
+ * ADR-124 risk register). Strips control + bidi/zero-width chars, collapses
+ * whitespace, caps length. Independent reimplementation — no coupling to any
+ * external label sanitizer.
+ *
+ * Filtering is done by codepoint (not a regex literal) so no control byte
+ * ever appears in this source file.
+ */
+const MAX_LABEL = 160;
+
+/** True for C0/C1 controls, DEL, zero-width, bidi override/isolate, BOM. */
+function isStrippable(cp: number): boolean {
+    if (cp <= 0x1f) return true; // C0 controls (incl. tab/newline → space)
+    if (cp >= 0x7f && cp <= 0x9f) return true; // DEL + C1 controls
+    if (cp >= 0x200b && cp <= 0x200f) return true; // zero-width + LRM/RLM
+    if (cp >= 0x202a && cp <= 0x202e) return true; // bidi embeds/overrides
+    if (cp >= 0x2066 && cp <= 0x2069) return true; // bidi isolates
+    if (cp === 0xfeff) return true; // BOM / ZWNBSP
+    return false;
+}
+
+export function sanitizeLabel(s: string, cap = MAX_LABEL): string {
+    let out = '';
+    for (const ch of s) out += isStrippable(ch.codePointAt(0) as number) ? ' ' : ch;
+    const cleaned = out.replace(/\s+/g, ' ').trim();
+    return cleaned.length > cap ? cleaned.slice(0, cap - 1) + '…' : cleaned;
+}

package/src/scripts/code_graph/sqlite_store.ts

@@ -0,0 +1,174 @@
+/**
+ * Derived SQLite twin of the code-graph JSON cache (ADR-129, Phase 6 of
+ * road-to-reachable-code-memory).
+ *
+ * `build` additionally emits `<cache>.sqlite3` beside the canonical JSON;
+ * the query path PREFERS the SQLite twin (cheap freshness check via the
+ * JSON's stat + stored source_checksum) and falls back to parsing the JSON
+ * when the twin is absent, stale, corrupt, version-mismatched, or the
+ * runtime has no `node:sqlite` (engines floor is Node >=20.11; the module
+ * needs >=22.5 — sqlite_guard's lazy import keeps old Nodes on the JSON
+ * path).
+ *
+ * INVARIANTS (ADR-129):
+ * - JSON stays canonical and byte-deterministic; the SQLite file is a
+ *   derived, gitignored, disposable accelerator. Rollback = delete it.
+ * - Answers are byte-identical on both stores — the loader reconstructs the
+ *   exact `CodeGraph` object (`serializeGraph` equality is the test).
+ * - Rollback triggers (recorded, not ship gates): query p95 <= 50 ms and
+ *   heap <= 10 MB on the SQLite path — a miss reverts THAT store to the
+ *   JSON fallback plus an incident note.
+ * - Zero-touch upgrades (Phase 7): `PRAGMA user_version` stamps the schema;
+ *   a mismatch / corrupt / absent twin is silently rebuilt from the
+ *   committed truth (the JSON) on the next load — never a user action.
+ */
+import * as fs from 'node:fs';
+
+import {
+    isSqliteAvailableSync,
+    loadSqliteSync,
+    readUserVersion,
+    stampUserVersion,
+} from '../_lib/sqlite_guard.js';
+import type { CodeEdge, CodeGraph, CodeNode } from './types.js';
+
+/** Bump on ANY table/column change — a mismatch sends readers to the JSON. */
+export const GRAPH_STORE_VERSION = 1;
+
+/** Derived twin path for a JSON cache path.
+ * cache-invalidation: versioned via PRAGMA user_version (GRAPH_STORE_VERSION), not the filename. */
+export function sqliteTwinPath(jsonPath: string): string {
+    return jsonPath.endsWith('.json') ? `${jsonPath.slice(0, -5)}.sqlite3` : `${jsonPath}.sqlite3`;
+}
+
+/**
+ * Emit the SQLite twin beside the JSON cache. Best-effort: returns false
+ * (never throws) when `node:sqlite` is unavailable or the write fails — the
+ * JSON path remains the source of truth either way.
+ *
+ * Storage model: nodes/edges land in real tables (queryable, and the FTS-free
+ * structure the rollback triggers measure), while `meta.graph_json` carries
+ * the byte-exact canonical serialization so the loader can guarantee
+ * byte-identical answers without re-deriving key order.
+ */
+export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: string): boolean {
+    if (!isSqliteAvailableSync()) return false;
+    const twin = sqliteTwinPath(jsonPath);
+    const tmp = `${twin}.tmp-${process.pid}`;
+    try {
+        const { DatabaseSync } = loadSqliteSync('code_graph.sqlite_store');
+        let stat: fs.Stats;
+        try {
+            stat = fs.statSync(jsonPath);
+        } catch {
+            return false; // no canonical JSON — nothing to twin
+        }
+        fs.rmSync(tmp, { force: true });
+        const db = new DatabaseSync(tmp);
+        try {
+            db.exec('PRAGMA journal_mode = MEMORY');
+            db.exec(
+                'CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);' +
+                    'CREATE TABLE nodes (id TEXT PRIMARY KEY, label TEXT NOT NULL, kind TEXT, source_file TEXT, l0 INTEGER, l1 INTEGER, l2 INTEGER, l3 INTEGER);' +
+                    'CREATE TABLE edges (source TEXT NOT NULL, target TEXT NOT NULL, relation TEXT NOT NULL, confidence TEXT NOT NULL, candidates TEXT);' +
+                    'CREATE INDEX edges_source ON edges(source);' +
+                    'CREATE INDEX edges_target ON edges(target);',
+            );
+            const meta = db.prepare('INSERT INTO meta (key, value) VALUES (?, ?)');
+            meta.run('source_checksum', graph.source_checksum);
+            meta.run('json_size', String(stat.size));
+            meta.run('json_mtime_ms', String(stat.mtimeMs));
+            meta.run('graph_json', serialized);
+            const insNode = db.prepare(
+                'INSERT INTO nodes (id, label, kind, source_file, l0, l1, l2, l3) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+            );
+            for (const n of graph.nodes) {
+                const loc = n.source_location ?? [];
+                insNode.run(
+                    n.id,
+                    n.label,
+                    (n as { kind?: string }).kind ?? null,
+                    n.source_file ?? null,
+                    (loc[0] as number | undefined) ?? null,
+                    (loc[1] as number | undefined) ?? null,
+                    (loc[2] as number | undefined) ?? null,
+                    (loc[3] as number | undefined) ?? null,
+                );
+            }
+            const insEdge = db.prepare(
+                'INSERT INTO edges (source, target, relation, confidence, candidates) VALUES (?, ?, ?, ?, ?)',
+            );
+            for (const e of graph.edges) {
+                insEdge.run(e.source, e.target, e.relation, e.confidence, e.candidates ? JSON.stringify(e.candidates) : null);
+            }
+            stampUserVersion(db, GRAPH_STORE_VERSION);
+        } finally {
+            db.close();
+        }
+        fs.renameSync(tmp, twin);
+        return true;
+    } catch {
+        fs.rmSync(tmp, { force: true });
+        return false;
+    }
+}
+
+/**
+ * Load the canonical serialization from a FRESH SQLite twin, or null when the
+ * twin is absent / stale (JSON changed since emission) / corrupt /
+ * version-mismatched / unsupported runtime. Callers fall back to reading the
+ * JSON — and best-effort re-emit the twin from it (zero-touch rebuild).
+ */
+export function loadSerializedFromTwin(jsonPath: string): string | null {
+    if (!isSqliteAvailableSync()) return null;
+    const twin = sqliteTwinPath(jsonPath);
+    if (!fs.existsSync(twin)) return null;
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(jsonPath);
+    } catch {
+        return null; // canonical JSON gone — the twin has no truth to mirror
+    }
+    try {
+        const { DatabaseSync } = loadSqliteSync('code_graph.sqlite_store');
+        const db = new DatabaseSync(twin, { readOnly: true });
+        try {
+            if (readUserVersion(db) !== GRAPH_STORE_VERSION) return null;
+            const rows = db.prepare('SELECT key, value FROM meta').all() as { key: string; value: string }[];
+            const meta = new Map(rows.map((r) => [r.key, r.value]));
+            if (meta.get('json_size') !== String(stat.size)) return null;
+            if (meta.get('json_mtime_ms') !== String(stat.mtimeMs)) return null;
+            const serialized = meta.get('graph_json');
+            return serialized && serialized.length > 0 ? serialized : null;
+        } finally {
+            db.close();
+        }
+    } catch {
+        // Corrupt twin is a non-event: drop it so the next build re-emits.
+        fs.rmSync(twin, { force: true });
+        return null;
+    }
+}
+
+/** Structured node/edge access for future in-process consumers (kept minimal:
+ * the loader above guarantees byte-identical answers; these are for tooling). */
+export function twinCounts(jsonPath: string): { nodes: number; edges: number } | null {
+    if (!isSqliteAvailableSync()) return null;
+    const twin = sqliteTwinPath(jsonPath);
+    if (!fs.existsSync(twin)) return null;
+    try {
+        const { DatabaseSync } = loadSqliteSync('code_graph.sqlite_store');
+        const db = new DatabaseSync(twin, { readOnly: true });
+        try {
+            const n = db.prepare('SELECT COUNT(*) AS c FROM nodes').get() as { c: number };
+            const e = db.prepare('SELECT COUNT(*) AS c FROM edges').get() as { c: number };
+            return { nodes: n.c, edges: e.c };
+        } finally {
+            db.close();
+        }
+    } catch {
+        return null;
+    }
+}
+
+export type { CodeEdge, CodeGraph, CodeNode };

package/src/scripts/code_graph/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared types for the native code-graph engine (Class-A, ADR-124).
+ *
+ * The graph shape is deliberately identical to what the interop tier consumes
+ * and to `discovery_graph.ts`'s edge-confidence scale — one code path serves
+ * the native cache, a consumer-shipped `graph.json`, and any future consumer
+ * of the shape. Deterministic + LLM-free + no network: identical source →
+ * identical graph bytes (enforced by the golden-checksum test).
+ */
+
+/** Launch set — the stacks this suite's consumers actually run. */
+export type Lang = 'php' | 'typescript' | 'javascript';
+
+/** Same scale as `discovery_graph.ts::EdgeConfidence` (reused, not forked). */
+export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+
+/** Relations the extractor emits. */
+export type Relation = 'calls' | 'imports' | 'uses' | 'inherits' | 'member';
+
+export interface CodeNode {
+    /** Path-qualified from day one: `<relpath>#<symbol>` (collision-free). */
+    id: string;
+    label: string;
+    kind: 'file' | 'class' | 'interface' | 'trait' | 'function' | 'method' | 'skipped';
+    source_file: string;
+    /** 1-based [startLine, startCol, endLine, endCol]; [] for synthetic nodes. */
+    source_location: readonly number[];
+}
+
+export interface CodeEdge {
+    source: string;
+    target: string;
+    relation: Relation;
+    confidence: EdgeConfidence;
+    /**
+     * Present only on AMBIGUOUS / multi-candidate edges: the resolved-target
+     * candidates by id. An AMBIGUOUS edge is "correct" when the true target is
+     * among these (the honest-taxonomy acceptance rule).
+     */
+    candidates?: string[];
+}
+
+export interface CodeGraph {
+    schema_version: number;
+    /** content-addressed to the file-manifest checksum (cache key). */
+    source_checksum: string;
+    /** launch-set languages actually seen in this build. */
+    languages: Lang[];
+    /** ABI version of the grammars used (pinned; asserted by the smoke test). */
+    grammar_abi: number;
+    /** per-confidence-class edge counts, so the honesty split is visible. */
+    edge_confidence_counts: Record<EdgeConfidence, number>;
+    nodes: CodeNode[];
+    edges: CodeEdge[];
+}
+
+export const SCHEMA_VERSION = 1;
+
+/** Deterministic per-file byte cap — files above this become a SKIPPED node. */
+export const MAX_FILE_BYTES = 1_000_000;
+
+/** file-extension → language, launch set only. */
+export const EXT_LANG: Readonly<Record<string, Lang>> = {
+    '.php': 'php',
+    '.ts': 'typescript',
+    '.tsx': 'typescript',
+    '.mts': 'typescript',
+    '.cts': 'typescript',
+    '.js': 'javascript',
+    '.jsx': 'javascript',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+};
+
+/** Grammar wasm filename per language (in `tree-sitter-wasms/out/`). */
+export const GRAMMAR_WASM: Readonly<Record<Lang, string>> = {
+    php: 'tree-sitter-php.wasm',
+    typescript: 'tree-sitter-typescript.wasm',
+    javascript: 'tree-sitter-javascript.wasm',
+};
+
+/** The single ABI version the pinned grammar set is built against. */
+export const EXPECTED_GRAMMAR_ABI = 14;

package/src/scripts/code_graph/validate.ts

@@ -0,0 +1,63 @@
+/**
+ * Schema gate — validate a graph.json (native cache or consumer-shipped)
+ * before any consumer trusts it. Pure, no IO.
+ */
+import type { CodeGraph } from './types.js';
+
+const RELATIONS = new Set(['calls', 'imports', 'uses', 'inherits', 'member']);
+const CONFIDENCES = new Set(['EXTRACTED', 'INFERRED', 'AMBIGUOUS']);
+const KINDS = new Set(['file', 'class', 'interface', 'trait', 'function', 'method', 'skipped']);
+
+export interface ValidateResult {
+    ok: boolean;
+    errors: string[];
+}
+
+export function validateGraph(g: unknown): ValidateResult {
+    const errors: string[] = [];
+    const push = (m: string): void => {
+        if (errors.length < 50) errors.push(m);
+    };
+    if (typeof g !== 'object' || g === null) return { ok: false, errors: ['graph is not an object'] };
+    const obj = g as Record<string, unknown>;
+    if (typeof obj['schema_version'] !== 'number') push('schema_version must be a number');
+    if (typeof obj['source_checksum'] !== 'string') push('source_checksum must be a string');
+    if (!Array.isArray(obj['nodes'])) push('nodes must be an array');
+    if (!Array.isArray(obj['edges'])) push('edges must be an array');
+    if (errors.length) return { ok: false, errors };
+
+    const nodes = obj['nodes'] as unknown[];
+    const ids = new Set<string>();
+    nodes.forEach((n, i) => {
+        if (typeof n !== 'object' || n === null) return push(`node[${i}] not an object`);
+        const nn = n as Record<string, unknown>;
+        if (typeof nn['id'] !== 'string') push(`node[${i}].id must be a string`);
+        else ids.add(nn['id']);
+        if (!KINDS.has(nn['kind'] as string)) push(`node[${i}].kind invalid: ${String(nn['kind'])}`);
+        if (typeof nn['source_file'] !== 'string') push(`node[${i}].source_file must be a string`);
+        if (!Array.isArray(nn['source_location'])) push(`node[${i}].source_location must be an array`);
+    });
+
+    (obj['edges'] as unknown[]).forEach((e, i) => {
+        if (typeof e !== 'object' || e === null) return push(`edge[${i}] not an object`);
+        const ee = e as Record<string, unknown>;
+        if (typeof ee['source'] !== 'string') push(`edge[${i}].source must be a string`);
+        if (typeof ee['target'] !== 'string') push(`edge[${i}].target must be a string`);
+        if (!RELATIONS.has(ee['relation'] as string)) push(`edge[${i}].relation invalid: ${String(ee['relation'])}`);
+        if (!CONFIDENCES.has(ee['confidence'] as string))
+            push(`edge[${i}].confidence invalid: ${String(ee['confidence'])}`);
+        // a source must be a known node; targets may be unresolved `symbol:` refs
+        if (typeof ee['source'] === 'string' && !ids.has(ee['source'] as string))
+            push(`edge[${i}].source is not a known node: ${String(ee['source'])}`);
+        if (ee['candidates'] !== undefined && !Array.isArray(ee['candidates']))
+            push(`edge[${i}].candidates must be an array when present`);
+    });
+
+    return { ok: errors.length === 0, errors };
+}
+
+/** Narrowing helper for callers that then treat the value as CodeGraph. */
+export function assertGraph(g: unknown): asserts g is CodeGraph {
+    const r = validateGraph(g);
+    if (!r.ok) throw new Error(`invalid graph: ${r.errors.join('; ')}`);
+}

package/src/scripts/condense.ts

@@ -965,17 +965,25 @@ function _read_rule_packs(): string[] | null {
 }
 
 /**
- * Whether a rule source file projects under the given workspace + pack
- * scopes. Both scopes are independent constraints: when configured, the
- * rule's frontmatter list must intersect (installed workspaces AND
- * installed packs). Kernel always projects; untagged axes fail safe.
+ * Whether a rule source file projects under the given workspace + pack +
+ * role scopes. Each configured scope is an independent constraint: the
+ * rule's frontmatter list must intersect it. Kernel always projects;
+ * untagged axes fail safe.
+ *
+ * `role_scope` is the subagent-role axis (road-to-lean-agent-init Phase 4):
+ * a `roles:` frontmatter list, parallel to `workspaces:`/`packs:`, so a
+ * review-worker subagent's rule projection can be scoped to review-shaped
+ * rules instead of the full set. Additive — the new param defaults to
+ * `null` (no role filtering), so every existing 2- and 3-arg call site
+ * compiles and behaves unchanged.
  */
 export function rule_in_scope(
     source_path: string,
     scope: readonly string[] | null,
     pack_scope: readonly string[] | null = null,
+    role_scope: readonly string[] | null = null,
 ): boolean {
-    if (scope === null && pack_scope === null) {
+    if (scope === null && pack_scope === null && role_scope === null) {
         return true;
     }
     const [meta] = _parse_frontmatter(_readText(source_path));
@@ -994,7 +1002,7 @@ export function rule_in_scope(
         }
         return values.some((v) => configured.includes(v));
     };
-    return axis('workspaces', scope) && axis('packs', pack_scope);
+    return axis('workspaces', scope) && axis('packs', pack_scope) && axis('roles', role_scope);
 }
 
 /** List rule basenames under RULES_SOURCE, workspace/pack scope applied. */