@event4u/agent-config 17.2.1 → 17.3.0

package/src/scripts/code_graph/refresh_lock.ts

@@ -0,0 +1,193 @@
+/**
+ * Single-flight lock for `code-graph refresh --single-flight` and `map`.
+ *
+ * Every producer goes through {@link acquire}: the git-hook refresh block in
+ * `install-hooks.sh` and the `code-graph-refresh` session concern both run
+ * `refresh --single-flight`, so there is one locking protocol, not two.
+ * `mkdir` is the primitive because it is atomic on every POSIX filesystem.
+ *
+ * Ownership is recorded in a SIBLING file, never inside the directory, so the
+ * directory is empty and a single `rmdir`-style removal clears it.
+ *
+ * A lock is reclaimed only on positive evidence that its owner is gone (see
+ * {@link isStale}); an owner-less lock — a torn owner write — counts as stale
+ * only past {@link STALE_LOCK_MS}. A release removes the lock only while the
+ * owner record still carries the releaser's nonce, so a holder that was
+ * reclaimed cannot delete its successor's lock on the way out.
+ */
+import { randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export const LOCK_REL = path.join('agents', 'runtime', 'state', 'code-graph-refresh.lock');
+/** Written by `code-graph auto-refresh on`; the session concern acts only while it exists. */
+export const AUTO_REFRESH_REL = path.join('agents', 'runtime', 'state', 'code-graph-auto-refresh.json');
+export const STALE_LOCK_MS = 5 * 60 * 1000;
+/**
+ * How long an owner on ANOTHER host (a container sharing the checkout) is
+ * believed: this host cannot probe its PID, so age is the only signal. An
+ * availability compromise, not proof — it reads the owner's own wall clock, so
+ * clock skew between hosts shifts it. A same-host owner whose PID is alive is
+ * never reclaimed on age (ratification, 2026-10-24, two of two seats): a paused,
+ * debugged or overloaded refresh is still a refresh.
+ */
+export const MAX_LOCK_AGE_MS = 30 * 60 * 1000;
+
+interface Owner {
+    pid: number;
+    started_at: number;
+    nonce: string;
+    /** Absent in records written before the host was stored; such an owner is judged by age alone. */
+    host?: string;
+}
+
+const ownerPath = (lock: string): string => `${lock}.owner.json`;
+
+export interface RefreshRecord {
+    at: string;
+    /** `session-start` (the concern) or `refresh` (the CLI run it starts, or a manual one). */
+    by: 'session-start' | 'refresh';
+    outcome: string;
+    detail?: string | undefined;
+}
+
+/** One file per side, so the session concern writes without reading or merging anything. */
+export const refreshRecordPath = (root: string, by: RefreshRecord['by']): string =>
+    path.join(root, path.dirname(LOCK_REL), `code-graph-refresh.${by}.json`);
+
+/** The last outcome of one side, so a refresh that never happens is visible. Best-effort. */
+export function recordRefresh(root: string, rec: Omit<RefreshRecord, 'at'>): void {
+    try {
+        fs.writeFileSync(refreshRecordPath(root, rec.by), JSON.stringify({ at: new Date().toISOString(), ...rec }));
+    } catch {
+        /* never fails a refresh */
+    }
+}
+
+export function readRefreshRecords(root: string): Partial<Record<RefreshRecord['by'], RefreshRecord>> {
+    const out: Partial<Record<RefreshRecord['by'], RefreshRecord>> = {};
+    for (const by of ['session-start', 'refresh'] as const) {
+        try {
+            out[by] = JSON.parse(fs.readFileSync(refreshRecordPath(root, by), 'utf-8')) as RefreshRecord;
+        } catch {
+            /* never recorded */
+        }
+    }
+    return out;
+}
+
+function pidAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        // EPERM means the process exists but belongs to someone else.
+        return (e as NodeJS.ErrnoException).code === 'EPERM';
+    }
+}
+
+const errno = (e: unknown): string | undefined => (e as NodeJS.ErrnoException).code;
+
+/** The owner record; `'none'` when there is no file or no valid record; `'unreadable'` on any other error. */
+function readOwner(lock: string): Owner | 'none' | 'unreadable' {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(ownerPath(lock), 'utf-8');
+    } catch (e) {
+        return errno(e) === 'ENOENT' ? 'none' : 'unreadable';
+    }
+    try {
+        const o = JSON.parse(raw) as Partial<Owner>;
+        if (typeof o.pid === 'number' && typeof o.started_at === 'number' && typeof o.nonce === 'string') return o as Owner;
+    } catch {
+        /* a torn write; fall through to the age rule */
+    }
+    return 'none';
+}
+
+/**
+ * True only on positive evidence: the owner's process is gone, the lock has
+ * vanished, or an owner-less lock is provably older than the threshold. A lock
+ * or owner record that cannot be inspected is treated as live.
+ */
+export function isStale(lock: string, now: number = Date.now()): boolean {
+    const owner = readOwner(lock);
+    if (owner === 'unreadable') return false;
+    if (owner !== 'none') {
+        // Only an owner that NAMES this host is judged by its PID. Another host's
+        // PID means nothing here, and a record without a host cannot be placed,
+        // so both are judged by age alone (see MAX_LOCK_AGE_MS).
+        if (owner.host !== os.hostname()) return now - owner.started_at > MAX_LOCK_AGE_MS;
+        return !pidAlive(owner.pid);
+    }
+    try {
+        return now - fs.statSync(lock).mtimeMs > STALE_LOCK_MS;
+    } catch (e) {
+        return errno(e) === 'ENOENT';
+    }
+}
+
+function take(lock: string): () => void {
+    const nonce = randomBytes(16).toString('hex');
+    fs.writeFileSync(ownerPath(lock), JSON.stringify({ pid: process.pid, started_at: Date.now(), nonce, host: os.hostname() }));
+    return () => {
+        const owner = readOwner(lock);
+        if (typeof owner === 'string' || owner.nonce !== nonce) return;
+        fs.rmSync(ownerPath(lock), { force: true });
+        fs.rmSync(lock, { recursive: true, force: true });
+    };
+}
+
+export const reclaimMutexPath = (lock: string): string => `${lock}.reclaim`;
+
+/** True when this process holds the lock (the CLI took it before calling in). */
+export function heldByThisProcess(root: string): boolean {
+    const owner = readOwner(path.join(root, LOCK_REL));
+    return typeof owner !== 'string' && owner.pid === process.pid;
+}
+
+/**
+ * Take the lock, or return null when another refresh holds it.
+ *
+ * A stale lock is removed only while holding a second mkdir mutex, and only
+ * after staleness is checked AGAIN under it. A reclaimer that judged the lock
+ * stale and was then overtaken finds the successor's live lock on that second
+ * check and declines, so it can never delete a lock created after it looked.
+ * A reclaim mutex left by a crash inside that short section is never removed
+ * automatically: no check before a removal can prove which mutex instance it
+ * removes, and removing a successor's would let two reclaimers in (ratification,
+ * 2026-10-24). Stale locks then stay held — lost freshness, never lost exclusion
+ * — and `code-graph auto-refresh status` names the leftover for a human to remove.
+ * `afterStaleCheck` exists for the interleaving test only.
+ */
+export function acquire(root: string, afterStaleCheck?: () => void): (() => void) | null {
+    const lock = path.join(root, LOCK_REL);
+    fs.mkdirSync(path.dirname(lock), { recursive: true });
+    try {
+        fs.mkdirSync(lock);
+        return take(lock);
+    } catch (e) {
+        if (errno(e) !== 'EEXIST' || !isStale(lock)) return null;
+    }
+    afterStaleCheck?.();
+    const mutex = reclaimMutexPath(lock);
+    try {
+        fs.mkdirSync(mutex);
+    } catch {
+        return null;
+    }
+    try {
+        if (!isStale(lock)) return null;
+        fs.rmSync(ownerPath(lock), { force: true });
+        fs.rmSync(lock, { recursive: true, force: true });
+        try {
+            fs.mkdirSync(lock);
+        } catch {
+            return null;
+        }
+        return take(lock);
+    } finally {
+        fs.rmSync(mutex, { recursive: true, force: true });
+    }
+}

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 = 5;
 
 /**
  * Edge count at or above which the indexed read path replaces the blob path.
@@ -101,7 +104,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
@@ -140,8 +143,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 +156,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');
@@ -271,6 +275,7 @@ interface EdgeRow {
     ambiguity_reason: string | null;
     resolved_via: string | null;
     provider: string | null;
+    provider_id: string | null;
 }
 
 function toNode(r: NodeRow): CodeNode {
@@ -303,6 +308,7 @@ 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;
 }
 

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';
 
 /** 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,12 +88,20 @@ 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'
     | 'test-import'
@@ -131,33 +141,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 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 +205,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 +257,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 +292,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 +334,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 +361,7 @@ export const EXT_LANG: Readonly<Record<string, Lang>> = {
     '.py': 'python',
     '.go': 'go',
     '.java': 'java',
+    '.cs': 'csharp',
     '.vue': 'typescript',
 };
 
@@ -340,6 +373,7 @@ 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',
 };
 
 /** 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'])}`);

package/src/scripts/condense.ts

@@ -2150,19 +2150,19 @@ export const PLUGIN_POINTER_SLUG = 'install-agent-config';
 export const PLUGIN_POINTER_SKILL_BODY = `---
 name: install-agent-config
 description: >-
-  Install or upgrade the event4u agent-config suite. This marketplace plugin
-  is a bootstrap shim — it ships hooks plus this pointer only; ALL skills,
-  rules, and commands are installed via \`npx -y @event4u/agent-config init\`.
-  Use when the user asks to install, set up, or upgrade agent-config, or
+  Governance rules, skills and commands for AI coding agents in Claude Code, Cursor, GitHub Copilot and Gemini CLI —
+  install or upgrade the full event4u agent-config suite. No plugin that ships this pointer is the full suite (the Claude
+  Code one adds hooks, the Copilot one a read-only MCP server); ALL content installs via \`npx -y @event4u/agent-config init\`.
+  Use when the user asks to install, set up, or upgrade agent-config, wants coding-agent rules or skills, or
   wonders why this plugin contains no other skills.
 ---
 
 # Install agent-config
 
-This plugin is a **bootstrap shim** kept so the marketplace listing stays
-discoverable. Its hooks run only alongside a global npm install of the package (never a project-local one) —
-on a plugin-only install no hook runs, so the \`fail_closed\` guards (\`block-no-verify\`, \`block-kernel-rule-writes\`,
-\`block-plumbing-writes\`) are **off**; the session start says so once. Content ships as a file projection.
+The plugin that delivered this skill is a **discovery entry**, not the suite. The Claude Code plugin adds hooks that
+run only alongside a global npm install of the package (never a project-local one) — on a plugin-only install no hook
+runs, so the \`fail_closed\` guards (\`block-no-verify\`, \`block-kernel-rule-writes\`, \`block-plumbing-writes\`) are
+**off**; the session start says so once. The Copilot plugin adds a read-only MCP server and no hooks.
 
 ## Install (canonical, one command)
 
@@ -2172,7 +2172,7 @@ npx -y @event4u/agent-config init
 
 The installer writes the full content projection, registers the dispatcher
 hooks as a managed block in \`~/.claude/settings.json\` (byte-identical to
-this plugin's hooks, so nothing double-fires), and keeps everything
+the Claude Code plugin's hooks, so nothing double-fires), and keeps everything
 upgradeable via \`agent-config upgrade\`.
 
 ## Already installed both?

package/src/scripts/generate_settings_reference.ts

@@ -33,7 +33,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { toJsonSchema7 } from '../shared/zodJsonSchema.js';
 
 import { settingsSchema } from '../server/schemas/settings.js';
 import {
@@ -97,11 +97,7 @@ export function renderProse(value: string | undefined): string {
 }
 
 export function buildRows(contractMarkdown: string): ReferenceRow[] {
-    const jsonSchema = zodToJsonSchema(settingsSchema, {
-        name: 'AgentSettings',
-        $refStrategy: 'none',
-        target: 'jsonSchema7',
-    }) as Parameters<typeof flattenSurface>[0];
+    const jsonSchema = toJsonSchema7(settingsSchema, 'AgentSettings') as Parameters<typeof flattenSurface>[0];
     // The version is a required parameter of the shared flattener and is
     // discarded here on purpose — see the module header.
     const surface = flattenSurface(jsonSchema, 'unversioned');

package/src/scripts/hook_chunks.mjs

@@ -45,6 +45,10 @@ export const HOOK_CHUNKS = Object.freeze([
         entry: 'src/scripts/hooks/instructions_observer_hook.ts',
         outfile: 'dist/hooks/instructions_observer.chunk.cjs',
     }),
+    Object.freeze({
+        entry: 'src/scripts/hooks/code_graph_refresh_hook.ts',
+        outfile: 'dist/hooks/code_graph_refresh.chunk.cjs',
+    }),
 ]);
 
 /**