@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/code_graph/query.ts

@@ -9,6 +9,7 @@ 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';
 
@@ -24,10 +25,19 @@ export interface LoadedGraph {
 }
 
 export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
-    const parsed = JSON.parse(fs.readFileSync(graphPath, 'utf-8')) as unknown;
+    // 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[]>();
@@ -44,13 +54,25 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     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. */
-export function resolveSeeds(g: LoadedGraph, seed: string, limit = 5): string[] {
-    if (g.byId.has(seed)) return [seed];
+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 exactLabel.slice(0, limit);
+    if (exactLabel.length) return { ids: exactLabel.slice(0, limit), weak: false };
     const ranked = g.lex.rank(tokenize(seed)).filter((r) => r.score > 0);
-    return ranked.slice(0, limit).map((r) => r.id);
+    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 {
@@ -61,42 +83,109 @@ function edgeLine(g: LoadedGraph, e: CodeEdge): string {
     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;
 }
 
-function budgetedLines(source: string, seeds: string[], lines: string[], budget: number): QueryResult {
+/** 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 l of lines) {
-        if (used + l.length > cap) {
+    for (const entry of entries) {
+        if (!truncated && used + entry.text.length <= cap) {
+            kept.push(entry.text);
+            used += entry.text.length + 1;
+        } else {
             truncated = true;
-            break;
+            dropped.push(entry);
         }
-        kept.push(l);
-        used += l.length + 1;
     }
-    return { source, seeds, lines: kept, truncated };
+    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 seeds = resolveSeeds(g, seed);
-    const lines: string[] = [];
-    for (const s of seeds) for (const e of g.out.get(s) ?? []) lines.push(edgeLine(g, e));
-    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+    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 seeds = resolveSeeds(g, seed);
+    const resolution = resolveSeedsTiered(g, seed);
+    const seeds = resolution.ids;
     const seen = new Set<string>();
-    const lines: string[] = [];
+    const entries: LineEntry[] = [];
     const frontier = [...seeds];
     for (let hop = 0; hop < 2 && frontier.length; hop += 1) {
         const next: string[] = [];
@@ -104,26 +193,30 @@ export function explain(g: LoadedGraph, seed: string, budget = 1500): QueryResul
             if (seen.has(s)) continue;
             seen.add(s);
             for (const e of g.out.get(s) ?? []) {
-                lines.push(edgeLine(g, e));
+                entries.push({ text: edgeLine(g, e), focusId: e.target });
                 next.push(e.target);
             }
         }
         frontier.push(...next);
     }
-    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+    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 seeds = resolveSeeds(g, target);
+    const resolution = resolveSeedsTiered(g, target);
+    const seeds = resolution.ids;
     const seen = new Set<string>(seeds);
-    const lines: string[] = [];
+    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) ?? []) {
-                lines.push(edgeLine(g, e));
+                // 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);
@@ -132,14 +225,16 @@ export function affected(g: LoadedGraph, target: string, depth = 2, budget = 150
         }
         frontier = next;
     }
-    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+    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 starts = resolveSeeds(g, a, 1);
-    const goals = new Set(resolveSeeds(g, b, 1));
-    if (!starts.length || !goals.size) return { source: g.source, seeds: [], lines: [], truncated: false };
+    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]);
@@ -164,7 +259,16 @@ export function path(g: LoadedGraph, a: string, b: string, budget = 1500): Query
         }
         frontier = next;
     }
-    if (!hit) return { source: g.source, seeds: [label(g, start)], lines: ['(no path found)'], truncated: false };
+    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)) {
@@ -172,5 +276,15 @@ export function path(g: LoadedGraph, a: string, b: string, budget = 1500): Query
         chain.unshift(e);
         cur = e.source === cur ? e.target : e.source;
     }
-    return budgetedLines(g.source, [label(g, start), label(g, hit)], chain.map((e) => edgeLine(g, e)), budget);
+    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/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/compile_router.ts

@@ -50,16 +50,14 @@ const SETTINGS_PATH = project_settings_path(ROOT);
 // workspace-independent by definition.
 export const SCHEMA_VERSION = 2;
 
-// Compile-time rule toggles. Maps rule-id → settings predicate.
-// Rule omitted from router.json when predicate returns False.
-const COMPILE_TIME_TOGGLES: Record<string, (s: JsonObject) => boolean> = {
-    'telegraph-speak': (s: JsonObject): boolean => {
-        const tg = (s['telegraph'] as JsonObject | undefined) ?? {};
-        const enabled = tg['enabled'] === undefined ? true : tg['enabled'];
-        const speak = tg['speak'] === undefined ? true : tg['speak'];
-        return Boolean(enabled) && Boolean(speak);
-    },
-};
+// Compile-time rule toggles — the definition moved to
+// `_lib/compile_time_toggles.ts` on 2026-07-29 so the PROJECTOR honours it too.
+// Router membership alone was never zero-cost: a disabled rule kept shipping as a
+// file, and the host reads the file (docs/adrs/telegraph/0002 § part 1).
+// Re-exported here because tests and downstream consumers pin this name.
+import { COMPILE_TIME_TOGGLES, rule_is_compile_enabled } from './_lib/compile_time_toggles.js';
+
+export { COMPILE_TIME_TOGGLES };
 
 // Maps legacy tier values to the router-canonical names. See
 // docs/contracts/rule-router.md § Backward compatibility.
@@ -204,10 +202,8 @@ function _collect(): JsonObject {
             continue;
         }
         const rule_id = _stem(p);
-        if (rule_id in COMPILE_TIME_TOGGLES) {
-            if (!(COMPILE_TIME_TOGGLES[rule_id] as (s: JsonObject) => boolean)(settings)) {
-                continue;
-            }
+        if (!rule_is_compile_enabled(rule_id, settings)) {
+            continue;
         }
         const rule_type = String(fm['type'] ?? 'auto');
         // Manual rules are reference-only (ADR-004) — no router emission.

package/src/scripts/condense.sh

@@ -4,12 +4,11 @@
 # Usage:
 #   ./scripts/condense.sh              # sync non-.md files + cleanup
 #   ./scripts/condense.sh --list       # list ALL .md files
-#   ./scripts/condense.sh --changed    # list .md files changed since last condensation
+#   ./scripts/condense.sh --changed    # list .md files whose projection is out of date
 #   ./scripts/condense.sh --check      # check if dirs are in sync
-#   ./scripts/condense.sh --mark-done <path>  # mark file as condensed
-#   ./scripts/condense.sh --mark-all-done     # mark all files as condensed
 #
-# .md condensation is done by the Augment agent interactively.
+# .md files are projected verbatim with the path rewriter applied — --sync
+# writes them; there is no separate condensation step.
 
 set -euo pipefail