@event4u/agent-config 14.21.0 → 14.22.0

package/src/scripts/code_graph/resolution_tiers.ts

@@ -0,0 +1,238 @@
+/**
+ * Resolution tiers that run BEFORE the repo-wide name lookup
+ * (road-to-a-graph-that-is-shipped 2.3).
+ *
+ * The extractor's ladder ends in a same-name table across the whole
+ * repository. That rung is a guess and is labelled one — `INFERRED`, via
+ * `name-lookup`. Two configuration files in a normal project state the answer
+ * outright, and reading them turns a guess into a fact:
+ *
+ * · `tsconfig.json` `compilerOptions.paths` — `@shared/x` IS `src/shared/x`,
+ *   because the project says so. Without this tier the specifier is non-relative,
+ *   so `resolveSpecifier` returns null and the import binds to `external:@shared/x`
+ *   — a real module, correctly named, and the wrong one.
+ * · `composer.json` `autoload.psr-4` — `App\Services\Mailer` IS
+ *   `app/Services/Mailer.php`. Without this tier a PHP `use` is matched by BASE
+ *   NAME with the namespace discarded, so two classes called `Mailer` in
+ *   different namespaces are indistinguishable.
+ *
+ * Both are DECLARED mappings, so an edge resolved through one is EXTRACTED, not
+ * INFERRED: the project's own config is as much a syntactic fact as an import
+ * specifier is.
+ *
+ * Deterministic and IO-free at resolution time — the configs are read once by
+ * the caller and passed in, so `buildGraph` stays pure and identical source
+ * plus identical config yields identical bytes.
+ */
+import type { ResolvedVia } from './types.js';
+
+/** Extensions a TS/JS alias target may carry, in resolution order. */
+const ALIAS_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'] as const;
+
+export interface AliasRule {
+    /** The pattern's literal prefix, e.g. `@shared/` for `@shared/*`. */
+    prefix: string;
+    /** Whether the pattern ended in `*` (a prefix rule) or was exact. */
+    wildcard: boolean;
+    /** Repo-relative substitution targets, already joined with `baseUrl`. */
+    targets: string[];
+}
+
+export interface Psr4Rule {
+    /** Namespace prefix WITH its trailing separator, e.g. `App\\`. */
+    prefix: string;
+    /** Repo-relative directories, with a trailing slash. */
+    dirs: string[];
+}
+
+export interface ResolutionConfig {
+    aliases: AliasRule[];
+    psr4: Psr4Rule[];
+}
+
+export const EMPTY_RESOLUTION_CONFIG: ResolutionConfig = { aliases: [], psr4: [] };
+
+/**
+ * Parse JSON that may carry comments and trailing commas.
+ *
+ * `tsconfig.json` is JSONC by convention and this repository's own uses `//`
+ * comments, so `JSON.parse` on it throws. Returning null rather than throwing
+ * is deliberate: an unparseable config must degrade to "no tiers", never break
+ * a build. Strings are walked rather than regex-stripped so a `//` inside a
+ * path value survives.
+ */
+export function parseJsonc(text: string): unknown | null {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i] as string;
+        if (inString) {
+            out += ch;
+            if (escaped) escaped = false;
+            else if (ch === '\\') escaped = true;
+            else if (ch === '"') inString = false;
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n') i += 1;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    // Trailing commas before a closing brace/bracket.
+    out = out.replace(/,(\s*[}\]])/g, '$1');
+    try {
+        return JSON.parse(out) as unknown;
+    } catch {
+        return null;
+    }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Normalise a repo-relative path fragment: no leading `./`, no trailing `/`. */
+function normalizeFragment(p: string): string {
+    return p.replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+/**
+ * Build the alias tier from a parsed `tsconfig.json`.
+ *
+ * `baseUrl` is resolved relative to the tsconfig's own directory, which for a
+ * root tsconfig is the repo root — so `baseUrl: "./src"` plus `"@shared/*":
+ * ["shared/*"]` yields the repo-relative prefix `src/shared/`.
+ */
+export function aliasRulesFrom(tsconfig: unknown): AliasRule[] {
+    if (!isRecord(tsconfig)) return [];
+    const co = tsconfig['compilerOptions'];
+    if (!isRecord(co)) return [];
+    const paths = co['paths'];
+    if (!isRecord(paths)) return [];
+    const baseUrl = typeof co['baseUrl'] === 'string' ? normalizeFragment(co['baseUrl']) : '';
+    const rules: AliasRule[] = [];
+    for (const [pattern, valueRaw] of Object.entries(paths)) {
+        if (!Array.isArray(valueRaw)) continue;
+        const wildcard = pattern.endsWith('*');
+        const prefix = wildcard ? pattern.slice(0, -1) : pattern;
+        const targets: string[] = [];
+        for (const v of valueRaw) {
+            if (typeof v !== 'string') continue;
+            const tgt = wildcard ? (v.endsWith('*') ? v.slice(0, -1) : v) : v;
+            const joined = baseUrl ? `${baseUrl}/${normalizeFragment(tgt)}` : normalizeFragment(tgt);
+            targets.push(joined.replace(/\/+$/, ''));
+        }
+        if (targets.length) rules.push({ prefix, wildcard, targets });
+    }
+    // Longest prefix first: `@shared/deep/` must beat `@shared/` when both are
+    // declared, which is TypeScript's own rule and not a preference.
+    rules.sort((a, b) => b.prefix.length - a.prefix.length);
+    return rules;
+}
+
+/** Build the PSR-4 tier from a parsed `composer.json`. */
+export function psr4RulesFrom(composer: unknown): Psr4Rule[] {
+    if (!isRecord(composer)) return [];
+    const rules: Psr4Rule[] = [];
+    for (const key of ['autoload', 'autoload-dev']) {
+        const block = composer[key];
+        if (!isRecord(block)) continue;
+        const psr4 = block['psr-4'];
+        if (!isRecord(psr4)) continue;
+        for (const [ns, valueRaw] of Object.entries(psr4)) {
+            const dirsRaw = Array.isArray(valueRaw) ? valueRaw : [valueRaw];
+            const dirs = dirsRaw
+                .filter((d): d is string => typeof d === 'string')
+                .map((d) => {
+                    const n = normalizeFragment(d);
+                    return n === '' ? '' : `${n}/`;
+                });
+            if (dirs.length) rules.push({ prefix: ns, dirs });
+        }
+    }
+    // Longest namespace first — PSR-4's own most-specific-wins rule.
+    rules.sort((a, b) => b.prefix.length - a.prefix.length);
+    return rules;
+}
+
+function firstExisting(candidate: string, fileIds: ReadonlySet<string>): string | null {
+    if (fileIds.has(candidate)) return candidate;
+    // TS source imports `@shared/mailer.js` and the file on disk is
+    // `mailer.ts`, so the RUNTIME extension is stripped before the candidate
+    // list is tried — the same normalisation `resolveSpecifier` does for a
+    // relative specifier. Without it every alias in an ESM-style codebase
+    // misses, which is most of them.
+    const stem = candidate.replace(/\.(js|jsx|mjs|cjs)$/, '');
+    for (const e of ALIAS_EXTS) if (fileIds.has(stem + e)) return stem + e;
+    for (const e of ALIAS_EXTS) if (fileIds.has(`${candidate}/index${e}`)) return `${candidate}/index${e}`;
+    return null;
+}
+
+/**
+ * Resolve a non-relative TS/JS specifier through the alias tier.
+ *
+ * Returns null when no rule matches or the mapped file is not in the graph —
+ * an alias pointing outside the built root is not a hit, and claiming it as one
+ * would be worse than the `external:` binding it replaces.
+ */
+export function resolveAlias(spec: string, config: ResolutionConfig, fileIds: ReadonlySet<string>): string | null {
+    for (const rule of config.aliases) {
+        if (rule.wildcard) {
+            if (!spec.startsWith(rule.prefix)) continue;
+            const rest = spec.slice(rule.prefix.length);
+            for (const t of rule.targets) {
+                const hit = firstExisting(rest ? `${t}/${rest}` : t, fileIds);
+                if (hit) return hit;
+            }
+        } else {
+            if (spec !== rule.prefix) continue;
+            for (const t of rule.targets) {
+                const hit = firstExisting(t, fileIds);
+                if (hit) return hit;
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Resolve a fully-qualified PHP class name through the PSR-4 tier.
+ *
+ * `App\Services\Mailer` under `{"App\\": "app/"}` becomes
+ * `app/Services/Mailer.php`. A leading backslash is tolerated because `use
+ * \App\X` is legal and means the same thing.
+ */
+export function resolvePsr4(fqcn: string, config: ResolutionConfig, fileIds: ReadonlySet<string>): string | null {
+    const name = fqcn.replace(/^\\+/, '');
+    for (const rule of config.psr4) {
+        if (!name.startsWith(rule.prefix)) continue;
+        const rest = name.slice(rule.prefix.length).replace(/\\/g, '/');
+        if (!rest) continue;
+        for (const d of rule.dirs) {
+            const candidate = `${d}${rest}.php`;
+            if (fileIds.has(candidate)) return candidate;
+        }
+    }
+    return null;
+}
+
+/** The `resolved_via` value each tier stamps on the edges it produces. */
+export const ALIAS_VIA: ResolvedVia = 'path-alias';
+export const PSR4_VIA: ResolvedVia = 'psr4';

package/src/scripts/code_graph/sqlite_store.ts

@@ -32,8 +32,32 @@ 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.
+ */
+export const GRAPH_STORE_VERSION = 3;
+
+/**
+ * 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 +94,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 +130,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 +194,203 @@ 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'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;
+                },
+                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

@@ -17,6 +17,55 @@ export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
 /** Relations the extractor emits. */
 export type Relation = 'calls' | 'imports' | 'uses' | 'inherits' | 'member';
 
+/**
+ * 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';
+
 export interface CodeNode {
     /** Path-qualified from day one: `<relpath>#<symbol>` (collision-free). */
     id: string;
@@ -45,6 +94,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 +162,14 @@ export interface CodeGraph {
 }
 
 /**
+ * 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 +178,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 = 3;
 
 /** 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

@@ -6,6 +6,19 @@ import type { CodeGraph } from './types.js';
 
 const RELATIONS = new Set(['calls', 'imports', 'uses', 'inherits', 'member']);
 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 +70,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'])}`);