@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/code_graph/sqlite_store.ts

@@ -32,8 +32,39 @@ import {
 } 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;
+/**
+ * Bump on ANY table/column change — a mismatch sends readers to the JSON.
+ *
+ * 1 → 2 (2.1): `edges` gained `resolved_via` and `provider`; `nodes` gained
+ * indexes on `label` and `source_file`; `meta` gained `node_count` /
+ * `edge_count`. A v1 twin has none of them, and the indexed read path below
+ * would silently answer from missing columns.
+ *
+ * 2 → 3 (2.2): those two columns are now REQUIRED on every edge. A v2 twin has
+ * the columns but may have written them NULL, from a graph built before the
+ * fields existed — which reads back as a valid edge carrying a fabricated
+ * mechanism. Refusing it costs nothing, because the twin is derived and the
+ * next build re-emits it.
+ *
+ * 3 → 4 (3.2): the `Relation` union gained `tests`, so a v3 twin carries no
+ * `tests` rows for a graph whose JSON has them. No COLUMN changed, which is
+ * precisely why the bump is needed rather than optional: a v3 twin would read
+ * back cleanly, answer `tests-for` with the empty set, and the caller could not
+ * tell "nothing tests this" from "this twin predates the relation". An index
+ * that answers a question it cannot answer is worse than one that refuses.
+ */
+export const GRAPH_STORE_VERSION = 4;
+
+/**
+ * Edge count at or above which the indexed read path replaces the blob path.
+ *
+ * A DECLARED threshold, not a measured crossover — nothing establishes that
+ * 50k is where the two paths actually cross. Below it, building the in-memory
+ * Maps is cheap enough that the extra SQL round-trips per hop are not worth
+ * paying; above it, `JSON.parse` plus two `Map`s over every edge is the
+ * dominant cost and it is paid before the first question is answered.
+ */
+export const INDEXED_READ_MIN_EDGES = 50_000;
 
 /** Derived twin path for a JSON cache path.
  * cache-invalidation: versioned via PRAGMA user_version (GRAPH_STORE_VERSION), not the filename. */
@@ -70,15 +101,25 @@ export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: s
             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 TABLE edges (source TEXT NOT NULL, target TEXT NOT NULL, relation TEXT NOT NULL, confidence TEXT NOT NULL, candidates TEXT, ambiguity_reason TEXT, resolved_via TEXT, provider TEXT);' +
                     'CREATE INDEX edges_source ON edges(source);' +
-                    'CREATE INDEX edges_target ON edges(target);',
+                    'CREATE INDEX edges_target ON edges(target);' +
+                    // Seed resolution and the changed-file seed set are the two
+                    // reads that would otherwise scan every node. `id` needs no
+                    // index — it is the PRIMARY KEY.
+                    'CREATE INDEX nodes_label ON nodes(label);' +
+                    'CREATE INDEX nodes_source_file ON nodes(source_file);',
             );
             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);
+            // Counts live in meta so a reader can pick its path from one row
+            // instead of a COUNT(*) over the table it is deciding whether to
+            // read at all.
+            meta.run('node_count', String(graph.nodes.length));
+            meta.run('edge_count', String(graph.edges.length));
             const insNode = db.prepare(
                 'INSERT INTO nodes (id, label, kind, source_file, l0, l1, l2, l3) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
             );
@@ -96,10 +137,20 @@ export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: s
                 );
             }
             const insEdge = db.prepare(
-                'INSERT INTO edges (source, target, relation, confidence, candidates) VALUES (?, ?, ?, ?, ?)',
+                'INSERT INTO edges (source, target, relation, confidence, candidates, ambiguity_reason, resolved_via, provider) ' +
+                    'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
             );
             for (const e of graph.edges) {
-                insEdge.run(e.source, e.target, e.relation, e.confidence, e.candidates ? JSON.stringify(e.candidates) : null);
+                insEdge.run(
+                    e.source,
+                    e.target,
+                    e.relation,
+                    e.confidence,
+                    e.candidates ? JSON.stringify(e.candidates) : null,
+                    e.ambiguity_reason ?? null,
+                    e.resolved_via,
+                    e.provider,
+                );
             }
             stampUserVersion(db, GRAPH_STORE_VERSION);
         } finally {
@@ -150,6 +201,211 @@ export function loadSerializedFromTwin(jsonPath: string): string | null {
     }
 }
 
+/**
+ * A per-node / per-edge read API over the twin — the thing this module did not
+ * export before (road-to-a-graph-that-is-shipped D7).
+ *
+ * Every export it had took a PATH and returned the whole graph: the serialized
+ * blob, or a pair of counts. So "the query path prefers SQLite" was true and
+ * bought nothing — `loadSerializedFromTwin` hands back the entire
+ * serialization, and the caller then parses it and builds a `Map` over every
+ * node and every edge. The twin was a cheaper blob transport, never an index.
+ *
+ * These reads take an id, a label, or a file, and touch only the rows that
+ * answer. Statements are prepared once per handle because a BFS calls
+ * `edgesTo` once per frontier node, and re-preparing per hop would hand back
+ * the constant factor the index just removed.
+ *
+ * The handle owns an open database and MUST be closed. Every method is safe
+ * after `close()` only in the sense that it will throw — callers hold it for
+ * the duration of one query and release it.
+ */
+export interface GraphIndex {
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly sourceChecksum: string;
+    getNode(id: string): CodeNode | undefined;
+    hasNode(id: string): boolean;
+    /** Out-edges: everything `id` points at. */
+    edgesFrom(id: string): CodeEdge[];
+    /** In-edges: everything pointing at `id` — the reverse-BFS direction. */
+    edgesTo(id: string): CodeEdge[];
+    /** Exact-label resolution, served by `nodes_label`. */
+    idsByLabel(label: string, limit: number): string[];
+    /** Non-file nodes declared in any of `files` — the changed-seed lookup. */
+    idsInFiles(files: readonly string[]): string[];
+    /** Every node id, sorted. A whole-table read, for `dead` only — see
+     * `LoadedGraph.allNodeIds`. */
+    allNodeIds(): string[];
+    /** Every node's id + searchable text. The ONLY whole-table read, and it
+     * exists because a BM25 fallback genuinely needs the corpus. Callers reach
+     * it only after an exact id AND an exact label both missed. */
+    lexicalCorpus(): { id: string; text: string }[];
+    close(): void;
+}
+
+interface NodeRow {
+    id: string;
+    label: string;
+    kind: string | null;
+    source_file: string | null;
+    l0: number | null;
+    l1: number | null;
+    l2: number | null;
+    l3: number | null;
+}
+
+interface EdgeRow {
+    source: string;
+    target: string;
+    relation: string;
+    confidence: string;
+    candidates: string | null;
+    ambiguity_reason: string | null;
+    resolved_via: string | null;
+    provider: string | null;
+}
+
+function toNode(r: NodeRow): CodeNode {
+    const loc = [r.l0, r.l1, r.l2, r.l3].filter((v): v is number => typeof v === 'number');
+    return {
+        id: r.id,
+        label: r.label,
+        kind: (r.kind ?? 'file') as CodeNode['kind'],
+        source_file: r.source_file ?? '',
+        source_location: loc,
+    };
+}
+
+function toEdge(r: EdgeRow): CodeEdge {
+    const e: CodeEdge = {
+        source: r.source,
+        target: r.target,
+        relation: r.relation as CodeEdge['relation'],
+        confidence: r.confidence as CodeEdge['confidence'],
+        // The SQL columns are nullable, the TypeScript fields are not. A null
+        // can only come from a twin emitted before these fields existed, which
+        // GRAPH_STORE_VERSION already refuses — so this coalesce is unreachable
+        // in a healthy tree and is written to fail READABLE rather than to
+        // fabricate: `name-lookup` is the weakest mechanism, so a mislabelled
+        // edge is under-trusted rather than over-trusted by Phase 3's filter.
+        resolved_via: (r.resolved_via ?? 'name-lookup') as CodeEdge['resolved_via'],
+        provider: (r.provider ?? 'native') as CodeEdge['provider'],
+    };
+    if (r.candidates) e.candidates = JSON.parse(r.candidates) as string[];
+    if (r.ambiguity_reason === 'receiver-unknown' || r.ambiguity_reason === 'hierarchy-unresolved') {
+        e.ambiguity_reason = r.ambiguity_reason;
+    }
+    return e;
+}
+
+/**
+ * Open the twin for INDEXED reads, or null when it cannot serve them.
+ *
+ * Null on exactly the conditions `loadSerializedFromTwin` already refuses on —
+ * absent, stale against the JSON's size/mtime, corrupt, version-mismatched, no
+ * `node:sqlite` — so the two paths agree about when the twin is trustworthy
+ * and a caller never has to ask twice.
+ */
+export function openGraphIndex(jsonPath: string): GraphIndex | 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;
+    }
+    try {
+        const { DatabaseSync } = loadSqliteSync('code_graph.sqlite_store');
+        const db = new DatabaseSync(twin, { readOnly: true });
+        try {
+            if (readUserVersion(db) !== GRAPH_STORE_VERSION) {
+                db.close();
+                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) || meta.get('json_mtime_ms') !== String(stat.mtimeMs)) {
+                db.close();
+                return null;
+            }
+            const nodeCount = Number(meta.get('node_count') ?? NaN);
+            const edgeCount = Number(meta.get('edge_count') ?? NaN);
+            if (!Number.isFinite(nodeCount) || !Number.isFinite(edgeCount)) {
+                // A v2 twin always carries both. Missing means something wrote
+                // this file that is not this module, and guessing the counts
+                // would be worse than declining.
+                db.close();
+                return null;
+            }
+
+            const qNode = db.prepare('SELECT * FROM nodes WHERE id = ?');
+            const qFrom = db.prepare('SELECT * FROM edges WHERE source = ?');
+            const qTo = db.prepare('SELECT * FROM edges WHERE target = ?');
+            const qLabel = db.prepare('SELECT id FROM nodes WHERE label = ? LIMIT ?');
+
+            return {
+                nodeCount,
+                edgeCount,
+                sourceChecksum: meta.get('source_checksum') ?? '',
+                getNode(id) {
+                    const r = qNode.get(id) as unknown as NodeRow | undefined;
+                    return r ? toNode(r) : undefined;
+                },
+                hasNode(id) {
+                    return (qNode.get(id) as unknown as NodeRow | undefined) !== undefined;
+                },
+                edgesFrom(id) {
+                    return (qFrom.all(id) as unknown as EdgeRow[]).map(toEdge);
+                },
+                edgesTo(id) {
+                    return (qTo.all(id) as unknown as EdgeRow[]).map(toEdge);
+                },
+                idsByLabel(labelText, limit) {
+                    return (qLabel.all(labelText, limit) as { id: string }[]).map((r) => r.id);
+                },
+                idsInFiles(files) {
+                    if (files.length === 0) return [];
+                    // Chunked because SQLite caps bound parameters (999 on the
+                    // conservative default build) and a changed-file set from a
+                    // wide diff can exceed it.
+                    const out: string[] = [];
+                    const CHUNK = 400;
+                    for (let i = 0; i < files.length; i += CHUNK) {
+                        const slice = files.slice(i, i + CHUNK);
+                        const marks = slice.map(() => '?').join(',');
+                        const stmt = db.prepare(
+                            `SELECT id FROM nodes WHERE kind != 'file' AND source_file IN (${marks})`,
+                        );
+                        for (const r of stmt.all(...slice) as { id: string }[]) out.push(r.id);
+                    }
+                    return out;
+                },
+                allNodeIds() {
+                    return (db.prepare('SELECT id FROM nodes ORDER BY id').all() as { id: string }[]).map(
+                        (r) => r.id,
+                    );
+                },
+                lexicalCorpus() {
+                    return (db.prepare('SELECT id, label FROM nodes').all() as { id: string; label: string }[]).map(
+                        (r) => ({ id: r.id, text: `${r.label} ${r.id}` }),
+                    );
+                },
+                close() {
+                    db.close();
+                },
+            };
+        } catch (err) {
+            db.close();
+            throw err;
+        }
+    } catch {
+        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 {

package/src/scripts/code_graph/types.ts

@@ -14,8 +14,97 @@ 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';
+/**
+ * Relations the graph carries.
+ *
+ * `calls` / `imports` / `uses` / `inherits` / `member` come from the extractor.
+ * `tests` is DERIVED in the build pass (`road-to-a-graph-that-is-shipped` 3.2):
+ * a test file that imports an in-repo symbol from a non-test file is asserted
+ * to test it, `resolved_via: 'test-import'`, `confidence: 'INFERRED'`. The two
+ * halves of that are deliberately split across the two axes — the import is a
+ * syntactic fact, so it is EXTRACTED evidence, while "this test tests that
+ * subject" is an inference from a naming convention, which is what INFERRED
+ * says. Deriving it in `buildGraph` rather than in the extractor keeps the
+ * extractor per-file and pure: the predicate needs only the two paths, and no
+ * grammar can see whether a file is a test.
+ */
+export type Relation = 'calls' | 'imports' | 'uses' | 'inherits' | 'member' | 'tests';
+
+/**
+ * HOW an edge's target was arrived at — the mechanism, not the confidence.
+ *
+ * The two axes are independent and conflating them is what this field fixes.
+ * `confidence` says how much to trust the target; `resolved_via` says what
+ * produced it, which is the axis a consumer filters on. Phase 3's verbs accept
+ * an edge when `resolved_via` is not in `{name-lookup, dynamic}` — a rule that
+ * cannot be expressed in the confidence scale at all, because a `name-lookup`
+ * hit and a same-file hit can both be INFERRED.
+ *
+ * Four of the eight occur today, and saying which is the point of an enum that
+ * is wider than its current population:
+ *
+ * · `same-file` — a local declaration in the using file. The language's own
+ *   shadowing rule makes this the strongest binding there is.
+ * · `import-specifier` — an import/`use` binding: the file states where the
+ *   name comes from.
+ * · `name-lookup` — the repo-wide same-name table, or an attempted lookup that
+ *   found nothing and left a `symbol:` pseudo-target. A guess either way, and
+ *   the value that says so.
+ * · `dynamic` — a receiver the extractor cannot type (`$obj->m()`, an
+ *   unresolved `C::m()`), or a hierarchy rooted outside the repository.
+ *
+ * The remaining four are declared and currently unemitted: `path-alias` and
+ * `psr4` arrive with the resolution tiers in step 2.3, and `route-table` /
+ * `test-import` with the relations Phase 3 adds. They are in the union now so
+ * that adding them later is a build change rather than a schema change.
+ */
+export type ResolvedVia =
+    | 'same-file'
+    | 'import-specifier'
+    | 'path-alias'
+    | 'psr4'
+    | 'route-table'
+    | 'test-import'
+    | 'name-lookup'
+    | 'dynamic';
+
+/**
+ * WHICH engine produced the edge.
+ *
+ * One value, and the field exists anyway: an edge with no provider is
+ * indistinguishable from an edge whose provider nobody recorded, and the whole
+ * point of a mixed graph — should one ever exist — is being able to tell them
+ * apart. Kill register K2 forbids an external provider entering `src/`, so this
+ * stays a single-member union until a decision changes that.
+ */
+export type EdgeProvider = 'native';
+
+/**
+ * The two mechanisms that are GUESSES rather than statements.
+ *
+ * `name-lookup` is the repo-wide same-name table (or a lookup that found
+ * nothing); `dynamic` is a receiver the extractor cannot type. Everything else
+ * names where the target came from.
+ *
+ * Declared HERE, beside `ResolvedVia`, rather than in the query tier that first
+ * needed it — because the BUILD pass needs it too, and the reason is a defect an
+ * independent review demonstrated: a derived edge stamped with a trustworthy
+ * mechanism while its own evidence was a guess LAUNDERS the guess. A PHP
+ * `use Two\Mailer` with no `composer.json` binds by base name, so the `imports`
+ * edge is `name-lookup` and may point at `One\Mailer`; deriving a `tests` edge
+ * from it and tagging that `test-import` made a wrong target trustworthy to
+ * every consumer of the filter. One set, two readers, and the build pass can no
+ * longer disagree with the query tier about what a guess is.
+ */
+export const GUESS_RESOLVED_VIA: ReadonlySet<ResolvedVia> = new Set<ResolvedVia>([
+    'name-lookup',
+    'dynamic',
+]);
+
+/** Does this edge's target rest on a stated fact rather than a guess? */
+export function isStatedResolution(resolved_via: ResolvedVia): boolean {
+    return !GUESS_RESOLVED_VIA.has(resolved_via);
+}
 
 export interface CodeNode {
     /** Path-qualified from day one: `<relpath>#<symbol>` (collision-free). */
@@ -45,6 +134,14 @@ export interface CodeEdge {
     target: string;
     relation: Relation;
     confidence: EdgeConfidence;
+    /**
+     * REQUIRED. Not optional, so "no edge lacks either field" is a property the
+     * type system enforces at every construction site rather than a rule a
+     * linter has to re-check afterwards.
+     */
+    resolved_via: ResolvedVia;
+    /** REQUIRED, for the same reason. */
+    provider: EdgeProvider;
     /**
      * Present only on AMBIGUOUS / multi-candidate edges: the resolved-target
      * candidates by id. An AMBIGUOUS edge is "correct" when the true target is
@@ -105,6 +202,23 @@ export interface CodeGraph {
 }
 
 /**
+ * Bumped 3 → 4 by `road-to-a-graph-that-is-shipped` 3.2: the `Relation` union
+ * gained `tests`, and the build pass now derives those edges. A cached sidecar
+ * written at v3 carries per-file extracts that are still correct — `tests` is
+ * derived from `imports`, not extracted — but `readSidecar` refuses a version
+ * mismatch anyway, and that refusal is the right conservative default: the
+ * alternative is a version check that has to reason about WHICH schema changes
+ * a sidecar survives, which is a rule that rots silently the first time someone
+ * adds an extractor field. A full re-extraction is the cost of being sure.
+ *
+ * Bumped 2 → 3 by `road-to-a-graph-that-is-shipped` 2.2: every `CodeEdge` now
+ * carries `resolved_via` and `provider`. A cached sidecar written at v2 has
+ * neither, so `--update` would reuse untagged edges beside tagged ones and
+ * produce a graph whose `resolved_via` histogram silently under-counts —
+ * exactly the mixed-graph failure the previous bump describes. `readSidecar`
+ * refuses a version mismatch, which is what makes that impossible rather than
+ * merely unlikely.
+ *
  * Bumped 1 → 2 by `road-to-the-graph-that-lies-confidently`: `CodeNode.kind`
  * gained three members, `CodeGraph` gained `suppressed_edge_counts`, and the
  * per-file extract sidecar gained the import specifier. A cached sidecar
@@ -113,7 +227,7 @@ export interface CodeGraph {
  * file — a silently mixed graph. `readSidecar` refuses a version mismatch, so
  * the bump is what makes that impossible rather than merely unlikely.
  */
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 4;
 
 /** Deterministic per-file byte cap — files above this become a SKIPPED node. */
 export const MAX_FILE_BYTES = 1_000_000;

package/src/scripts/code_graph/validate.ts

@@ -4,8 +4,23 @@
  */
 import type { CodeGraph } from './types.js';
 
-const RELATIONS = new Set(['calls', 'imports', 'uses', 'inherits', 'member']);
+/** Mirrors `Relation` in types.ts. `tests` is derived by the build pass (3.2),
+ * not extracted, and is validated on exactly the same terms as the rest. */
+const RELATIONS = new Set(['calls', 'imports', 'uses', 'inherits', 'member', 'tests']);
 const CONFIDENCES = new Set(['EXTRACTED', 'INFERRED', 'AMBIGUOUS']);
+/** Mirrors `ResolvedVia` in types.ts — the full union, including the four
+ * values no build emits yet (2.3 and Phase 3 add them). */
+const RESOLVED_VIA = new Set([
+    'same-file',
+    'import-specifier',
+    'path-alias',
+    'psr4',
+    'route-table',
+    'test-import',
+    'name-lookup',
+    'dynamic',
+]);
+const PROVIDERS = new Set(['native']);
 const KINDS = new Set([
     'file',
     'class',
@@ -57,6 +72,16 @@ export function validateGraph(g: unknown): ValidateResult {
         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'])}`);
+        // Both are REQUIRED (2.2). Checked as presence-and-membership rather
+        // than membership alone, because an absent field and a misspelled one
+        // are different defects: absent means the build did not tag the edge,
+        // misspelled means the taxonomy drifted.
+        if (ee['resolved_via'] === undefined) push(`edge[${i}].resolved_via is required`);
+        else if (!RESOLVED_VIA.has(ee['resolved_via'] as string))
+            push(`edge[${i}].resolved_via invalid: ${String(ee['resolved_via'])}`);
+        if (ee['provider'] === undefined) push(`edge[${i}].provider is required`);
+        else if (!PROVIDERS.has(ee['provider'] as string))
+            push(`edge[${i}].provider invalid: ${String(ee['provider'])}`);
         // 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'])}`);