@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/code_graph/repo_identity.ts

@@ -0,0 +1,169 @@
+/**
+ * A repository's identity on this machine (ADR-299, council decision O2).
+ *
+ * `repoId` is 12 hex of an HMAC-SHA256, keyed by a random key created once
+ * under the user-global `runtime/projects/`, over the canonical origin URL —
+ * userinfo, tokens, query and fragment removed, host lower-cased, default port
+ * dropped, ssh / scp / https forms and a trailing `.git` collapsed. Without a
+ * remote the main checkout's realpath stands in. Keyed rather than a plain hash
+ * because a hosting URL is dictionary-guessable and may carry a token.
+ *
+ * A linked worktree keeps its parent's `repoId` and gets an `instance`, so its
+ * writable caches never collide with the main checkout's while estate queries
+ * still count one project. Two separate clones of one origin share `repoId` too,
+ * so `checkout` — keyed over the main checkout's realpath — is what keeps their
+ * writable homes apart.
+ *
+ * File-based like `_lib/git_common_dir.ts`: an inherited `GIT_DIR` would
+ * redirect a `git config` subprocess to the wrong repository.
+ */
+import { createHmac, randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { git_common_dir } from '../_lib/git_common_dir.js';
+import { type EnvMap, event4u_root } from '../_lib/user_global_paths.js';
+
+export interface RepoIdentity {
+    repoId: string;
+    /** Set for a linked worktree only. */
+    instance: string | null;
+    /** 8 hex over the main checkout's realpath: distinct per clone, shared by its worktrees. */
+    checkout: string;
+    source: 'origin' | 'realpath';
+}
+
+const DEFAULT_PORTS: Record<string, string> = { 'ssh:': '22', 'git+ssh:': '22', 'https:': '443', 'http:': '80', 'git:': '9418' };
+
+export function projectsDir(env?: EnvMap | null): string {
+    return path.join(event4u_root(env), 'runtime', 'projects');
+}
+
+/** `dir` overrides the projects directory, for a caller (advisories) that carries its own. */
+export function machineKeyPath(env?: EnvMap | null, dir: string = projectsDir(env)): string {
+    return path.join(dir, 'machine.key');
+}
+
+/**
+ * The machine key, created on first use. Published with a hard link so a
+ * concurrent first use either wins or reads the winner's complete key — never
+ * an empty file. A key that exists but is malformed throws: replacing it would
+ * silently re-key every repository on the machine.
+ */
+export function machineKey(env?: EnvMap | null, dir?: string): Buffer {
+    const p = machineKeyPath(env, dir);
+    const read = (): Buffer => {
+        const hex = fs.readFileSync(p, 'utf-8').trim();
+        if (!/^[0-9a-f]{64}$/.test(hex)) throw new Error(`malformed machine key: ${p}`);
+        return Buffer.from(hex, 'hex');
+    };
+    if (fs.existsSync(p)) return read();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}-${randomBytes(4).toString('hex')}.tmp`;
+    fs.writeFileSync(tmp, `${randomBytes(32).toString('hex')}\n`, { mode: 0o600 });
+    try {
+        fs.linkSync(tmp, p);
+    } catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
+    } finally {
+        fs.rmSync(tmp, { force: true });
+    }
+    return read();
+}
+
+function trimPath(p: string): string {
+    return p
+        .replace(/\/{2,}/g, '/')
+        .replace(/^\/+|\/+$/g, '')
+        .replace(/\.git$/i, '')
+        .replace(/\/+$/, '');
+}
+
+/**
+ * The credential-free form two spellings of one remote share. A relative local
+ * path resolves against `base`, the repository root, because the process cwd
+ * is wherever the CLI happened to be started.
+ */
+export function canonicalOrigin(raw: string, base?: string): string {
+    const url = raw.trim();
+    const scp = /^(?:[^@/]+@)?([^:/]+):(?!\/\/)(.+)$/.exec(url);
+    if (!url.includes('://') && scp && !/^[a-zA-Z]:[\\/]/.test(url)) {
+        return `${(scp[1] as string).toLowerCase()}/${trimPath(scp[2] as string)}`;
+    }
+    try {
+        const u = new URL(url);
+        if (u.protocol === 'file:') return `file:${trimPath(decodeURIComponent(u.pathname))}`;
+        const port = u.port && u.port !== DEFAULT_PORTS[u.protocol] ? `:${u.port}` : '';
+        return `${u.hostname.toLowerCase()}${port}/${trimPath(decodeURIComponent(u.pathname))}`;
+    } catch {
+        return `file:${trimPath(base === undefined ? path.resolve(url) : path.resolve(base, url))}`;
+    }
+}
+
+/** The `origin` URL, else the first remote's, read from the common git config. */
+export function remoteUrl(root: string): string | null {
+    const common = git_common_dir(root);
+    if (common === null) return null;
+    let text: string;
+    try {
+        text = fs.readFileSync(path.join(common, 'config'), 'utf-8');
+    } catch {
+        return null;
+    }
+    const urls = new Map<string, string>();
+    let remote: string | null = null;
+    for (const line of text.split(/\r?\n/)) {
+        const section = /^\s*\[\s*remote\s+"([^"]+)"\s*\]/.exec(line);
+        if (section) {
+            remote = section[1] as string;
+            continue;
+        }
+        if (/^\s*\[/.test(line)) {
+            remote = null;
+            continue;
+        }
+        const kv = /^\s*url\s*=\s*(.+?)\s*$/.exec(line);
+        if (remote !== null && kv && !urls.has(remote)) urls.set(remote, (kv[1] as string).replace(/^"|"$/g, ''));
+    }
+    return urls.get('origin') ?? urls.values().next().value ?? null;
+}
+
+function realpathOr(p: string): string {
+    try {
+        return fs.realpathSync(p);
+    } catch {
+        return path.resolve(p);
+    }
+}
+
+function hmac(key: Buffer, value: string): string {
+    return createHmac('sha256', key).update(value).digest('hex');
+}
+
+export function repoIdentity(root: string, env?: EnvMap | null, dir?: string): RepoIdentity {
+    const key = machineKey(env, dir);
+    const real = realpathOr(root);
+    const common = git_common_dir(real);
+    let linked = false;
+    try {
+        linked = !fs.statSync(path.join(real, '.git')).isDirectory();
+    } catch {
+        linked = false;
+    }
+    const origin = remoteUrl(real);
+    const main = common !== null && path.basename(common) === '.git' ? path.dirname(common) : real;
+    let source: RepoIdentity['source'] = 'origin';
+    let canonical: string;
+    if (origin !== null) {
+        canonical = `origin:${canonicalOrigin(origin, main)}`;
+    } else {
+        source = 'realpath';
+        canonical = `path:${main}`;
+    }
+    return {
+        repoId: hmac(key, canonical).slice(0, 12),
+        instance: linked ? hmac(key, `instance:${real}`).slice(0, 8) : null,
+        checkout: hmac(key, `checkout:${main}`).slice(0, 8),
+        source,
+    };
+}

package/src/scripts/code_graph/resolution_tiers.ts

@@ -108,9 +108,10 @@ 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 `/`. */
+/** Normalise a repo-relative path fragment: no leading `./`, no trailing `/`, and `.` is the root (`''`). */
 function normalizeFragment(p: string): string {
-    return p.replace(/^\.\//, '').replace(/\/+$/, '');
+    const s = p.replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+    return s === '.' ? '' : s;
 }
 
 /**
@@ -119,14 +120,19 @@ function normalizeFragment(p: string): string {
  * `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/`.
+ *
+ * A `baseUrl` also resolves every other non-relative specifier against
+ * itself, which TypeScript does after the `paths` entries: `baseUrl: "."`
+ * makes `components/cart` the file `components/cart.tsx`. That fallback is the
+ * last rule, an empty wildcard prefix, so a `paths` entry always wins.
  */
 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 paths = isRecord(co['paths']) ? co['paths'] : {};
+    const hasBaseUrl = typeof co['baseUrl'] === 'string';
+    const baseUrl = hasBaseUrl ? normalizeFragment(co['baseUrl'] as string) : '';
     const rules: AliasRule[] = [];
     for (const [pattern, valueRaw] of Object.entries(paths)) {
         if (!Array.isArray(valueRaw)) continue;
@@ -136,7 +142,8 @@ export function aliasRulesFrom(tsconfig: unknown): AliasRule[] {
         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);
+            const frag = normalizeFragment(tgt);
+            const joined = baseUrl && frag ? `${baseUrl}/${frag}` : baseUrl || frag;
             targets.push(joined.replace(/\/+$/, ''));
         }
         if (targets.length) rules.push({ prefix, wildcard, targets });
@@ -144,6 +151,7 @@ export function aliasRulesFrom(tsconfig: unknown): AliasRule[] {
     // 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);
+    if (hasBaseUrl) rules.push({ prefix: '', wildcard: true, targets: [baseUrl] });
     return rules;
 }
 
@@ -196,9 +204,13 @@ export function resolveAlias(spec: string, config: ResolutionConfig, fileIds: Re
     for (const rule of config.aliases) {
         if (rule.wildcard) {
             if (!spec.startsWith(rule.prefix)) continue;
+            // The baseUrl fallback never claims a relative or absolute specifier.
+            if (rule.prefix === '' && /^[./]/.test(spec)) continue;
             const rest = spec.slice(rule.prefix.length);
             for (const t of rule.targets) {
-                const hit = firstExisting(rest ? `${t}/${rest}` : t, fileIds);
+                const candidate = rest && t ? `${t}/${rest}` : rest || t;
+                if (!candidate) continue;
+                const hit = firstExisting(candidate, fileIds);
                 if (hit) return hit;
             }
         } else {

package/src/scripts/code_graph/scip_reader.ts

@@ -14,7 +14,7 @@
  * still reads. A malformed buffer throws; the caller treats that as "no SCIP".
  */
 import type { CodeEdge, CodeNode } from './types.js';
-import { GUESS_RESOLVED_VIA } from './types.js';
+import { isStatedResolution } from './types.js';
 
 export interface ScipOccurrence {
     /** 0-based start line. */
@@ -192,7 +192,7 @@ export function supersededByScip(scip: readonly CodeEdge[], nodes: readonly Code
         named.set(e.source, set);
     }
     return (e: CodeEdge): boolean => {
-        if (!GUESS_RESOLVED_VIA.has(e.resolved_via)) return false;
+        if (isStatedResolution(e.resolved_via)) return false;
         const set = named.get(e.source);
         if (!set) return false;
         const target = label.get(e.target) ?? e.target.replace(/^symbol:/, '');

package/src/scripts/code_graph/sqlite_store.ts

@@ -52,8 +52,11 @@ import type { CodeEdge, CodeGraph, CodeNode } from './types.js';
  * 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.
+ *
+ * 4 → 5 (`road-to-graph-providers-for-every-stack` 2.1): `edges` gained
+ * `provider_id`, the convention provider that drew a convention edge.
  */
-export const GRAPH_STORE_VERSION = 4;
+export const GRAPH_STORE_VERSION = 6;
 
 /**
  * Edge count at or above which the indexed read path replaces the blob path.
@@ -78,11 +81,10 @@ export function sqliteTwinPath(jsonPath: string): string {
  * 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.
+ * structure the rollback triggers measure). The JSON is the only full copy;
+ * the twin is a disposable, rebuildable projection of it.
  */
-export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: string): boolean {
+export function emitSqliteTwin(graph: CodeGraph, jsonPath: string): boolean {
     if (!isSqliteAvailableSync()) return false;
     const twin = sqliteTwinPath(jsonPath);
     const tmp = `${twin}.tmp-${process.pid}`;
@@ -101,7 +103,7 @@ 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, ambiguity_reason TEXT, resolved_via TEXT, provider 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, provider_id TEXT);' +
                     'CREATE INDEX edges_source ON edges(source);' +
                     'CREATE INDEX edges_target ON edges(target);' +
                     // Seed resolution and the changed-file seed set are the two
@@ -117,7 +119,6 @@ export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: s
             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.
@@ -140,8 +141,8 @@ export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: s
                 );
             }
             const insEdge = db.prepare(
-                'INSERT INTO edges (source, target, relation, confidence, candidates, ambiguity_reason, resolved_via, provider) ' +
-                    'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+                'INSERT INTO edges (source, target, relation, confidence, candidates, ambiguity_reason, resolved_via, provider, provider_id) ' +
+                    'VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
             );
             for (const e of graph.edges) {
                 insEdge.run(
@@ -153,6 +154,7 @@ export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: s
                     e.ambiguity_reason ?? null,
                     e.resolved_via,
                     e.provider,
+                    e.provider_id ?? null,
                 );
             }
             db.exec('COMMIT');
@@ -172,39 +174,38 @@ export function emitSqliteTwin(graph: CodeGraph, serialized: string, jsonPath: s
 }
 
 /**
- * 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).
+ * Whether the twin beside `jsonPath` mirrors it: present, the current store
+ * version, and recorded against the JSON's present size and mtime. A corrupt
+ * twin is a non-event — it is dropped so the next load re-emits it.
+ *
+ * The twin used to carry the whole serialized graph a second time and this
+ * returned it; that blob was the same bytes as the JSON and doubled the twin
+ * (road-to-a-graph-that-follows-you D2). The JSON is the only full copy now.
  */
-export function loadSerializedFromTwin(jsonPath: string): string | null {
-    if (!isSqliteAvailableSync()) return null;
+export function twinIsCurrent(jsonPath: string): boolean {
+    if (!isSqliteAvailableSync()) return false;
     const twin = sqliteTwinPath(jsonPath);
-    if (!fs.existsSync(twin)) return null;
+    if (!fs.existsSync(twin)) return false;
     let stat: fs.Stats;
     try {
         stat = fs.statSync(jsonPath);
     } catch {
-        return null; // canonical JSON gone — the twin has no truth to mirror
+        return false; // 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;
+            if (readUserVersion(db) !== GRAPH_STORE_VERSION) return false;
             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;
+            return meta.get('json_size') === String(stat.size) && meta.get('json_mtime_ms') === String(stat.mtimeMs);
         } 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;
+        return false;
     }
 }
 
@@ -214,9 +215,9 @@ export function loadSerializedFromTwin(jsonPath: string): string | null {
  *
  * 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.
+ * bought nothing — the loader handed back the entire serialization, and the
+ * caller then parsed it and built 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
@@ -271,6 +272,7 @@ interface EdgeRow {
     ambiguity_reason: string | null;
     resolved_via: string | null;
     provider: string | null;
+    provider_id: string | null;
 }
 
 function toNode(r: NodeRow): CodeNode {
@@ -303,13 +305,14 @@ function toEdge(r: EdgeRow): CodeEdge {
     if (r.ambiguity_reason === 'receiver-unknown' || r.ambiguity_reason === 'hierarchy-unresolved') {
         e.ambiguity_reason = r.ambiguity_reason;
     }
+    if (r.provider_id) e.provider_id = r.provider_id;
     return e;
 }
 
 /**
  * Open the twin for INDEXED reads, or null when it cannot serve them.
  *
- * Null on exactly the conditions `loadSerializedFromTwin` already refuses on —
+ * Null on exactly the conditions `twinIsCurrent` 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.

package/src/scripts/code_graph/types.ts

@@ -9,7 +9,7 @@
  */
 
 /** Launch set — the stacks this suite's consumers actually run. */
-export type Lang = 'php' | 'typescript' | 'javascript' | 'python' | 'go' | 'java';
+export type Lang = 'php' | 'typescript' | 'javascript' | 'python' | 'go' | 'java' | 'csharp' | 'ruby';
 
 /** Same scale as `discovery_graph.ts::EdgeConfidence` (reused, not forked). */
 export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
@@ -29,11 +29,12 @@ export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
  * grammar can see whether a file is a test.
  */
 /**
- * The last seven are the framework links the Laravel overlay reads by rule
- * (`laravel_overlay.ts`): a route to its handler, a method to the view it
- * renders, a view to the view it includes, code to the translation or config
- * file it reads, a migration to its table, a model to its table, a model to
- * the model an Eloquent relation names.
+ * `routes-to` … `injects` are the convention links a registered provider reads
+ * by rule (`providers/`, ADR-298): a route to its handler, code to the template
+ * it renders, a template to the template it includes, code to the translation
+ * or config file it reads, a migration to its table, a model to its table, a
+ * model to the model a relation names, a class to the service a container
+ * injects into it. The vocabulary is fixed and names no framework.
  */
 export type Relation =
     | 'calls'
@@ -49,6 +50,7 @@ export type Relation =
     | 'migrates'
     | 'persists'
     | 'relates'
+    | 'injects'
     /** A Markdown document links to, or names, the file (`docs_layer.ts`). */
     | 'documents';
 
@@ -86,14 +88,24 @@ export type ResolvedVia =
     | 'path-alias'
     | 'psr4'
     | 'route-table'
-    /** A Blade directive, a `view()` / `__()` / `config()` call, or a Markdown link naming a file. */
+    /** A template directive, a render / translation / config call naming a file, or a Markdown link. */
     | 'directive-scan'
-    /** A `Schema::create|table` call, or a model whose table one of them creates. */
+    /** A schema or migration call creating a table, or a model mapped to such a table. */
     | 'schema-call'
-    /** `$this->hasMany(Other::class)` and its siblings inside a model. */
-    | 'eloquent-relation'
+    /** An ORM relation declared inside a model, naming the related model. */
+    | 'orm-relation'
+    /** A dependency-injection declaration naming the injected class. */
+    | 'di-binding'
+    /** A string literal equal to exactly one file's path (the default pass). */
+    | 'literal-path'
+    /** A dotted name equal to exactly one template's path (the default pass). */
+    | 'literal-dotted'
+    /** A page module whose path is its route (the default pass). */
+    | 'fs-route'
     /** Stated by a compiler-grade SCIP index the project ships (`scip_reader.ts`). */
     | 'compiler-index'
+    /** C#: the one type of that name in the namespaces the file can see (its own, their parents, its `using`s). */
+    | 'namespace-scope'
     | 'test-import'
     | 'name-lookup'
     | 'dynamic'
@@ -131,33 +143,40 @@ export type EdgeProvider =
     | 'scip';
 
 /**
- * The two mechanisms that are GUESSES rather than statements.
+ * Every mechanism, classified as a statement (the source names the target) or
+ * a guess. Trust is this ALLOWLIST (ADR-298): it replaced a denylist of guesses,
+ * under which a new mechanism was trusted merely because nobody had listed it —
+ * wrong once several providers emit edges. A string that is no member at all
+ * (an older or foreign graph) is a guess. The type below fails to compile when a
+ * `ResolvedVia` member is in neither list.
  *
- * `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.
- *
- * The accepted-edge filter is a DENYLIST, so a new value is accepted by
- * default — which is exactly backwards for `foreign`. It must be listed here
- * or a consumer's graph would silently answer the gate verbs as if this
- * package had resolved its edges. (Kept out of the literal: esbuild carries a
- * comment inside an expression into the hook bundle.)
+ * The guesses: `name-lookup` is the repo-wide same-name table (or a lookup that
+ * found nothing); `dynamic` is a receiver the extractor cannot type; `foreign`
+ * was read from another tool's graph and only mapped. The BUILD pass needs the
+ * split as much as the query tier: 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, and a `tests`
+ * edge derived from it made a wrong target trustworthy to every consumer.
  */
-export const GUESS_RESOLVED_VIA: ReadonlySet<ResolvedVia> = new Set<ResolvedVia>(['name-lookup', 'dynamic', 'foreign']);
+// One space-separated string per list: this module ships in the hook bundle,
+// where an array literal costs a line per entry. `Words` splits it in the type.
+const STATED_WORDS =
+    'same-file import-specifier path-alias psr4 route-table directive-scan schema-call orm-relation di-binding compiler-index namespace-scope test-import literal-path literal-dotted fs-route' as const;
+const GUESS_WORDS = 'name-lookup dynamic foreign' as const;
+type Words<S extends string> = S extends `${infer H} ${infer T}` ? H | Words<T> : S;
+/** Mechanisms in neither list; must be `never` (a test asserts it). */
+export type UnclassifiedResolvedVia = Exclude<ResolvedVia, Words<typeof STATED_WORDS> | Words<typeof GUESS_WORDS>>;
+/** Words that are no mechanism at all; must be `never` too. */
+export type UnknownTrustWord = Exclude<Words<typeof STATED_WORDS> | Words<typeof GUESS_WORDS>, ResolvedVia>;
+/** Fails to compile while either list is incomplete or carries a stray word. */
+export type TrustListsComplete = [UnclassifiedResolvedVia | UnknownTrustWord] extends [never] ? true : never;
+export const TRUST_LISTS_COMPLETE: TrustListsComplete = true;
+export const STATED_RESOLVED_VIA: ReadonlySet<string> = new Set(STATED_WORDS.split(' '));
+export const GUESS_RESOLVED_VIA: ReadonlySet<ResolvedVia> = new Set(GUESS_WORDS.split(' ') as ResolvedVia[]);
 
-/** Does this edge's target rest on a stated fact rather than a guess? */
+/** Does this edge's target rest on a stated fact? Anything not listed as stated is a guess. */
 export function isStatedResolution(resolved_via: ResolvedVia): boolean {
-    return !GUESS_RESOLVED_VIA.has(resolved_via);
+    return STATED_RESOLVED_VIA.has(resolved_via);
 }
 
 export interface CodeNode {
@@ -188,9 +207,9 @@ export interface CodeNode {
         | 'type'
         | 'enum'
         | 'skipped'
-        /** A declared route, `<VERB> <path>` (Laravel overlay). */
+        /** A declared route or dispatched entry, `<VERB> <path>` (a convention provider). */
         | 'route'
-        /** A database table a migration creates (Laravel overlay). */
+        /** A database table a migration or schema creates (a convention provider). */
         | 'table';
     source_file: string;
     /** 1-based [startLine, startCol, endLine, endCol]; [] for synthetic nodes. */
@@ -240,6 +259,14 @@ export interface CodeEdge {
      * target.
      */
     ambiguity_reason?: 'receiver-unknown' | 'hierarchy-unresolved';
+    /** The convention provider that drew this edge (ADR-298); absent on every other edge. */
+    provider_id?: string;
+}
+
+/** A convention provider active in this build, with the package roots it applied to. */
+export interface ActiveProviderRecord {
+    id: string;
+    roots: string[];
 }
 
 export interface CodeGraph {
@@ -267,13 +294,15 @@ export interface CodeGraph {
     suppressed_edge_counts: {
         dynamic_no_candidate: number;
         /**
-         * A fluent call on Laravel's route builder (`->middleware()`,
-         * `->prefix()`) that name lookup had bound to an unrelated in-repo
-         * method of the same name. Present only when it is non-zero, so a
-         * graph without routes keeps its bytes.
+         * Base edges a convention provider proved false and removed, per
+         * provider id — e.g. a fluent route-builder call that name lookup had
+         * bound to an unrelated in-repo method of the same name. Present only
+         * when some count is non-zero.
          */
-        route_builder_call?: number;
+        contested_by_provider?: Record<string, number>;
     };
+    /** Convention providers active in this build; present only when one was. */
+    providers?: ActiveProviderRecord[];
     nodes: CodeNode[];
     edges: CodeEdge[];
 }
@@ -307,8 +336,13 @@ export interface CodeGraph {
  * Bumped 4 → 5 by `road-to-a-map-that-draws-itself` 1.3: same-file
  * same-name declarations now carry `@2`, `@3` suffixes, so a cache written
  * at v4 holds ids a v5 build would not produce.
+ *
+ * Bumped 5 → 6 by `road-to-graph-providers-for-every-stack` 2.1: framework
+ * names left the schema (`orm-relation`, `contested_by_provider`), provider
+ * edges carry `provider_id`, the graph records its active providers, and the
+ * vocabulary gained `injects` / `di-binding`.
  */
-export const SCHEMA_VERSION = 5;
+export const SCHEMA_VERSION = 6;
 
 /** Deterministic per-file byte cap — files above this become a SKIPPED node. */
 export const MAX_FILE_BYTES = 1_000_000;
@@ -329,6 +363,8 @@ export const EXT_LANG: Readonly<Record<string, Lang>> = {
     '.py': 'python',
     '.go': 'go',
     '.java': 'java',
+    '.cs': 'csharp',
+    '.rb': 'ruby',
     '.vue': 'typescript',
 };
 
@@ -340,6 +376,8 @@ export const GRAMMAR_WASM: Readonly<Record<Lang, string>> = {
     python: 'tree-sitter-python.wasm',
     go: 'tree-sitter-go.wasm',
     java: 'tree-sitter-java.wasm',
+    csharp: 'tree-sitter-c_sharp.wasm',
+    ruby: 'tree-sitter-ruby.wasm',
 };
 
 /** The single ABI version the pinned grammar set is built against. */

package/src/scripts/code_graph/validate.ts

@@ -2,7 +2,7 @@
  * 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';
+import { type CodeGraph, GUESS_RESOLVED_VIA, STATED_RESOLVED_VIA } from './types.js';
 
 /** One space-separated string per vocabulary: this module ships in the hook bundle, paid on every dispatch. */
 const words = (s: string): ReadonlySet<string> => new Set(s.split(' '));
@@ -10,15 +10,11 @@ const words = (s: string): ReadonlySet<string> => new Set(s.split(' '));
 /** 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 = words(
-    'calls imports uses inherits member tests routes-to renders includes reads migrates persists relates documents',
+    'calls imports uses inherits member tests routes-to renders includes reads migrates persists relates injects documents',
 );
 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). */
-// `foreign`: adapted from a consumer's own graph file; see `foreign.ts`.
-const RESOLVED_VIA = words(
-    'same-file import-specifier path-alias psr4 route-table directive-scan schema-call eloquent-relation compiler-index test-import name-lookup dynamic foreign',
-);
+/** Every `ResolvedVia` member: the trust lists in types.ts, so the two cannot drift. */
+const RESOLVED_VIA: ReadonlySet<string> = new Set([...STATED_RESOLVED_VIA, ...GUESS_RESOLVED_VIA]);
 const PROVIDERS = new Set(['native', 'foreign', 'scip']);
 const KINDS = words('file class interface trait function method constant type enum skipped route table');
 
@@ -74,6 +70,8 @@ export function validateGraph(g: unknown): ValidateResult {
         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'])}`);
+        if (ee['provider_id'] !== undefined && typeof ee['provider_id'] !== 'string')
+            push(`edge[${i}].provider_id must be a string`);
         // 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'])}`);