@event4u/agent-config 14.21.0 → 14.22.0

package/src/scripts/check_rule_layer_partition.ts

@@ -8,7 +8,7 @@
  * ADR-236 decided that a rule is delivered from exactly one layer: package-only
  * rules stay in the project tree, everything else arrives from the host's global
  * directory and is withheld from the project tree. Measured in a freshly
- * generated worktree with `partitionActive: true`, it holds for one host in five:
+ * generated worktree with a verified host layer, it holds for one host in five:
  *
  * ```
  *   .claude/rules      13 files, 13 package-only,   0 global-only
@@ -51,7 +51,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
-import { isExclusivelyPackageOnly, resolvePartitionVerdict } from '../install/partitionEligibility.js';
+import { isExclusivelyPackageOnly } from '../install/partitionEligibility.js';
 import { PROJECT_RULE_DIRS, globalRuleLayerNames, globalRuleLayerPath } from '../install/globalRuleLayers.js';
 import { GateLedger, UnaccountedTargetsError } from './_lib/gate_ledger.js';
 import { reportScanned } from './_lib/scan_scope.js';
@@ -333,7 +333,7 @@ function selfTest(): number {
 /**
  * `--prune`: delete exactly the files this gate reports as duplicated.
  *
- * ## Why a gate ships a repair at all
+ * **Why a gate ships a repair at all.**
  *
  * The documented repair is `task generate-tools`, and on this repository's own main
  * checkout that command is **structurally inert**: `agents/.agent-tools.yml` is
@@ -381,17 +381,39 @@ function prune(audit: PartitionAudit, root: string): number {
 }
 
 /**
- * Does a duplication in this projection mode mean an emitter FAILED, or that the
- * partition deliberately did not run?
+ * Does THIS directory's duplication mean an emitter failed, or that the
+ * per-directory fail-safe legitimately kept the full projection?
  *
- * Split out of `main` so both directions are testable without a lockfile on disk:
- * the un-injected path can only assert whatever the machine happens to be, and this
- * one bit differs between a maintainer checkout mid-release and a partitioned one —
- * the same environment-dependence `ruleLayerPartition.ts` records for its own
- * `active` override.
+ * **The discriminator, corrected 2026-09-07 after a neutral review.**
+ *
+ * It used to be the repo-wide host-layer verdict — first a `PartitionMode`
+ * string, then the `verified` boolean the 2026-09-07 change reduced it to. Both
+ * were wrong in BOTH directions once the withhold stopped reading
+ * `installed.lock`:
+ *
+ *   - FALSE NEGATIVE: an install one release behind makes `verified === false`
+ *     for the whole release window, so a genuine emitter failure — the defect
+ *     this gate exists to catch — printed and returned 0.
+ *   - FALSE POSITIVE: a verified layer that legitimately lacks ONE rule makes
+ *     `partitionRulesForDir` keep all ~104 by design (rules are all-or-nothing,
+ *     `ruleLayerPartition.ts`), and the gate exited 1 on a correct tree.
+ *     `rule_partition_per_host.test.ts` pins that state as legal.
+ *
+ * The right signal was already computed and never asked: `soleCarrier` — the
+ * global-scope rules this directory projects that its host layer does NOT hold.
+ * Non-empty means the fail-safe fired for a reason a reader can check; empty
+ * means the layer carries every withheld name and the emitter simply did not
+ * withhold. Per directory, from data on hand, and independent of any lockfile —
+ * so the verdict no longer differs between a maintainer machine mid-release and
+ * a CI checkout.
+ *
+ * Also note what a stale layer can NOT do under per-name withholding: if the
+ * layer holds the name, the project copy is withheld whatever its CONTENT. So
+ * staleness never produces a duplicate, and the old message's second
+ * justification was keyed on the wrong fact.
  */
-export function partitionEnforces(mode: string): boolean {
-    return mode === 'dual-layer/partitioned';
+export function partitionEnforces(dir: Pick<DirAudit, 'soleCarrier'>): boolean {
+    return dir.soleCarrier.length === 0;
 }
 
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
@@ -485,34 +507,32 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     // partition gate and `check_bridge_derivation` deadlock, each red in the state
     // the other requires.
     //
-    // The block is structural rather than incidental: during ANY release the
-    // building version is ahead of the installed one, so `resolvePartitionVerdict`
-    // returns `standalone/full` on every maintainer machine for the whole release
-    // window. A gate that cannot be green while a release is in progress is not
-    // measuring the release.
+    // Split PER DIRECTORY, not on a repo-wide verdict — see `partitionEnforces` for
+    // why the verdict was wrong in both directions. A directory that is the sole
+    // carrier of at least one global-scope rule kept the full projection by design;
+    // one that carries none is an emitter that did not withhold.
     //
-    // Teeth are unchanged where the partition IS active: there a duplicate means an
-    // emitter failed to withhold what the partition selected, which is the defect
-    // this gate exists to catch. In CI both layers are absent, `offenders` is empty,
-    // and this branch is never reached — so nothing here relaxes the CI reading.
-    const verdict = resolvePartitionVerdict(root);
-    if (!partitionEnforces(verdict.mode)) {
-        for (const d of offenders) {
-            process.stdout.write(
-                `⚠️  ${d.dir}: ${String(d.duplicated.length)} rule(s) also present in ` +
-                    `${d.globalLayer ?? '(unknown)'}\n`,
-            );
-        }
+    // In CI both layers are absent, `offenders` is empty, and neither branch is
+    // reached — so nothing here changes the CI reading.
+    const failing = offenders.filter((d) => partitionEnforces(d));
+    for (const d of offenders.filter((d) => !partitionEnforces(d))) {
+        process.stdout.write(
+            `⚠️  ${d.dir}: ${String(d.duplicated.length)} rule(s) also present in ` +
+                `${d.globalLayer ?? '(unknown)'} — kept by design: this directory is the sole ` +
+                `carrier of ${String(d.soleCarrier.length)} global-scope rule(s) ` +
+                `(e.g. ${d.soleCarrier.slice(0, 3).join(', ')}), and the rule partition is ` +
+                `all-or-nothing per directory.\n`,
+        );
+    }
+    if (failing.length === 0) {
         process.stdout.write(
-            `⚠️  check_rule_layer_partition: partition INACTIVE (${verdict.reason}), so the ` +
-                `generators emit the full projection by design and this overlap is the fail-safe ` +
-                `working. Reported, not enforced — run \`agent-config install\` to activate the ` +
-                `partition here, then this gate has teeth again.\n`,
+            `✅  check_rule_layer_partition: every duplication is the per-directory fail-safe ` +
+                `working — no directory duplicates a rule its host layer fully carries.\n`,
         );
         return 0;
     }
 
-    for (const d of offenders) {
+    for (const d of failing) {
         process.stderr.write(
             `${report ? '⚠️ ' : '❌ '} ${d.dir}: ${String(d.duplicated.length)} rule(s) also present in ` +
                 `${d.globalLayer ?? '(unknown)'} — e.g. ${d.duplicated.slice(0, 5).join(', ')}\n`,

package/src/scripts/check_single_delivery.ts

@@ -34,15 +34,31 @@
  * fix, which teaches readers to ignore it — the exact failure this estate has
  * recorded twice already.
  *
- * The reason used to be that `road-to-single-delivery` Phase 2 was HALTED on
- * blocker `partition-current-layer-undecidable`. That is no longer true and the
- * sentence is corrected rather than left standing: the blocker reads
- * `**Status:** resolved`, its roadmap is archived, and the partition shipped
- * under ADR-236 Phase 2. What replaced the halt is a per-machine activation —
- * the partition withholds artefacts only where the host layer is verified
- * against `installed.lock`, so a machine whose install predates the fingerprint
- * keeps the full projection BY DESIGN and the overlap this gate reports there is
- * the fail-safe working, not a regression.
+ * The reason has been corrected twice rather than left standing. It was first
+ * that `road-to-single-delivery` Phase 2 was HALTED on blocker
+ * `partition-current-layer-undecidable` — no longer true; that blocker reads
+ * `**Status:** resolved` and the partition shipped under ADR-236 Phase 2. It was
+ * then a per-machine activation: the partition withheld only where the host layer
+ * verified against `installed.lock`, so an install one release behind kept the
+ * FULL projection by design and the overlap here was the fail-safe working.
+ *
+ * That second reason is void as of the ADR-236 amendment of 2026-09-07. The
+ * withhold no longer reads `installed.lock` at all — it reads each host
+ * directory's own contents, per NAME. An overlap this gate reports is therefore
+ * one of exactly two things now, and neither is a repo-wide fail-safe:
+ *
+ *   - an artefact the host layer genuinely does NOT hold, kept on its own merits
+ *     (the per-name fail-safe, and the right answer);
+ *   - an emitter that failed to withhold what the evidence said to withhold
+ *     (a defect).
+ *
+ * It still reports rather than enforcing, for the unchanged reason above. The
+ * second reason an earlier draft of this note gave — that the `commands` row's
+ * cluster-DIRECTORY key could read a correct tree as a collision — was true when
+ * written and was fixed in the same change: that row keys on the posix subpath
+ * now (see TYPES). Left recorded rather than deleted, because the argument is
+ * what justified `--enforce` staying opt-in and a reader should see that it no
+ * longer applies.
  *
  * WHERE THIS CHECK IS MEANINGFUL — read this before quoting one of its numbers
  * (road-to-session-closeout 3.3). It is a DEVELOPER-MACHINE check. It reads two
@@ -100,13 +116,23 @@ const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
  * (`commands/<cluster>/<sub>.md`), so this gate's `commands` row compares cluster
  * DIRECTORY names — a coarser key than the thing the host registers.
  *
- * That gap is recorded rather than closed, and the reason is a measurement: since
- * `commandsWithheld` gates the colon-form generator, a machine with a verified
- * host layer projects ZERO commands, so there is no project-side name for the
- * coarse key to be wrong about. On a machine WITHOUT one, the project layer is
- * the only layer and there is nothing to compare. The key is therefore imprecise
- * exactly where it has no work to do. Closing it would mean reading each command
- * file's own slug — real work for a row whose overlap is 0 in both topologies.
+ * That gap USED to be recorded rather than closed, on a measurement: while the
+ * colon-form generator was gated by one repo-wide verdict, a machine with a
+ * verified host layer projected ZERO commands and a machine without one had
+ * nothing to compare — so the coarse key was imprecise exactly where it had no
+ * work to do.
+ *
+ * **The ADR-236 amendment of 2026-09-07 falsified that, and it was OBSERVED, not
+ * predicted.** Withholding per name leaves the project layer holding exactly the
+ * commands the host lacks, and those can share a cluster with commands the host
+ * has: measured the same day, `.claude/commands/analyze/` held `repo.md` and
+ * `roadmap-repos.md` while `~/.claude/commands/analyze/` held `inbox.md` and
+ * seven others. Zero duplication, and the directory key reported a collision.
+ *
+ * So the `commands` row now keys on the POSIX SUBPATH (`<cluster>/<sub>.md`),
+ * which is the host's own unit. `readLayer` takes a `recursive` flag for it;
+ * `shape` stays a top-level reading so the shape-mismatch line keeps comparing
+ * the same thing it always did.
  *
  * `personas` and `user-types` were added 2026-08-21 (closure correction). See
  * `unknownProjectFamilies` for what now prevents the next omission.
@@ -182,7 +208,7 @@ interface LayerReading {
     shape: LayerShape;
 }
 
-function readLayer(dir: string): LayerReading | null {
+function readLayer(dir: string, recursive = false): LayerReading | null {
     let entries: fs.Dirent[];
     try {
         if (!fs.statSync(dir).isDirectory()) return null;
@@ -191,7 +217,11 @@ function readLayer(dir: string): LayerReading | null {
         return null;
     }
     const shape: LayerShape = { symlinks: 0, dirs: 0, files: 0 };
-    for (const e of entries) {
+    // README.md is excluded from BOTH the names and the shape. Counting it in the
+    // shape while filtering it from the names printed a self-contradicting line
+    // (`personas global 31 · shape (l0/d2/f30)` — 32 entries, 31 names), caught by
+    // a second neutral review.
+    for (const e of entries.filter((x) => x.name !== 'README.md')) {
         // isSymbolicLink() is checked FIRST and deliberately: readdir with
         // withFileTypes does not follow links, but a reader who tested isDirectory
         // first would classify a symlink-to-directory as a directory and lose the
@@ -200,7 +230,41 @@ function readLayer(dir: string): LayerReading | null {
         else if (e.isDirectory()) shape.dirs += 1;
         else shape.files += 1;
     }
-    return { names: entries.map((e) => e.name).sort(), shape };
+    if (!recursive) {
+        // README.md excluded for EVERY family, not only commands. It was excluded
+        // on the recursive path from the start and nowhere else, so a README in
+        // both layers would have counted as one duplicated artefact for rules,
+        // skills, personas, user-types and agents and not for commands — a latent
+        // asymmetry a neutral review caught on 2026-09-07. It names no artefact in
+        // any family.
+        return { names: entries.map((e) => e.name).filter((n) => n !== 'README.md').sort(), shape };
+    }
+    return { names: _mdSubpaths(dir).sort(), shape };
+}
+
+/**
+ * Every `*.md` under `dir`, as a posix path relative to it.
+ *
+ * The identity key for the `commands` row — see the note on TYPES. `README.md` is
+ * excluded because both layers carry one and it names no command.
+ */
+function _mdSubpaths(dir: string): string[] {
+    const out: string[] = [];
+    const walk = (abs: string, rel: string): void => {
+        let kids: fs.Dirent[];
+        try {
+            kids = fs.readdirSync(abs, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const k of kids) {
+            const childRel = rel === '' ? k.name : `${rel}/${k.name}`;
+            if (k.isDirectory()) walk(path.join(abs, k.name), childRel);
+            else if (k.name.endsWith('.md') && k.name !== 'README.md') out.push(childRel);
+        }
+    };
+    walk(dir, '');
+    return out;
 }
 
 /**
@@ -230,8 +294,9 @@ export function declaresPaths(file: string): 'yes' | 'no' | 'unreadable' {
 export function readType(type: ArtefactType, globalRoot: string, projectRoot: string): TypeReading {
     const gDir = path.join(globalRoot, type);
     const pDir = path.join(projectRoot, type);
-    const gLayer = readLayer(gDir);
-    const pLayer = readLayer(pDir);
+    const recursive = type === 'commands';
+    const gLayer = readLayer(gDir, recursive);
+    const pLayer = readLayer(pDir, recursive);
     const globalNames = gLayer?.names ?? null;
     const projectNames = pLayer?.names ?? null;
     const globalShape = gLayer?.shape ?? null;
@@ -500,11 +565,12 @@ export function main(argv?: readonly string[]): number {
             process.stdout.write(
                 'usage: check_single_delivery [--global DIR] [--project DIR] [--enforce] [--quiet]\n' +
                     '\n' +
-                    'Reports by default and exits 0: the partition SHIPPED (ADR-236, Phase 2)\n' +
-                    'but activates per machine — only where a verified host layer exists, so a\n' +
-                    'checkout without one keeps the full projection BY DESIGN and reports overlap.\n' +
-                    '--enforce exits 1 on any overlap; registering it would fail every machine\n' +
-                    'that has not re-run `agent-config install`, which is why it stays opt-in.\n',
+                    'Reports by default and exits 0: since the ADR-236 amendment of\n' +
+                    '2026-09-07 the project layer withholds per ARTEFACT NAME on each host\n' +
+                    "directory's own contents, so an artefact the host layer does not hold is\n" +
+                    'kept BY DESIGN and reads as overlap here. --enforce exits 1 on any\n' +
+                    'overlap. It stays opt-in because a machine whose global layer is stale\n' +
+                    'cannot fix the overlap by regenerating — only by `agent-config install`.\n',
             );
             return 0;
         } else if (a !== undefined) {
@@ -626,11 +692,11 @@ export function main(argv?: readonly string[]): number {
     }
     process.stdout.write(
         `⚠️  check_single_delivery: ${detail}. Reported, not enforced — ` +
-            'the partition shipped (ADR-236 Phase 2) but activates per machine: it withholds ' +
-            'artefacts only where the host layer is verified against `installed.lock`, so a ' +
-            'machine whose install predates the fingerprint keeps the full projection BY DESIGN ' +
-            'and this overlap is the fail-safe working. Run `agent-config install` to enable it ' +
-            'here; use --enforce where every machine is known to be verified.\n',
+            'since the ADR-236 amendment of 2026-09-07 the project layer withholds per ' +
+            "ARTEFACT NAME on each host directory's own contents, never on a version in " +
+            '`installed.lock`. So an artefact the host layer does not hold is kept BY DESIGN ' +
+            'and appears here; a stale global layer is fixed by `agent-config install`. Use ' +
+            '--enforce where every layer is known current.\n',
     );
     return 0;
 }

package/src/scripts/check_update_banner.ts

@@ -157,10 +157,23 @@ async function main(argv: readonly string[] = process.argv.slice(2)): Promise<nu
     return 0;
 }
 
+// `build:delegate-aux` bundles this file with `--splitting`, which can move the
+// module body into a shared chunk: `import.meta.url` then names the CHUNK, the
+// URL comparison below never matches, and the entry silently no-ops. Inside that
+// bundle the invoked file name is the reliable signal (same pattern as
+// src/scripts/_cli/cmd_migrate.ts). Defined by that build only.
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__) {
+        // A miss falls THROUGH to the URL comparison below, which is the
+        // symlinked-invocation case that fallback exists for.
+        if (path.basename(process.argv[1], '.js') === 'check_update_banner') {
+            return true;
+        }
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/code_graph/build.ts

@@ -16,6 +16,17 @@ import * as path from 'node:path';
 
 import { write_atomic } from '../_lib/fs_atomic.js';
 import { extractFile, type FileExtract, type RawEdge } from './extract.js';
+import {
+    ALIAS_VIA,
+    aliasRulesFrom,
+    EMPTY_RESOLUTION_CONFIG,
+    parseJsonc,
+    PSR4_VIA,
+    psr4RulesFrom,
+    type ResolutionConfig,
+    resolveAlias,
+    resolvePsr4,
+} from './resolution_tiers.js';
 import { emitSqliteTwin } from './sqlite_store.js';
 import {
     type CodeEdge,
@@ -24,6 +35,7 @@ import {
     EXPECTED_GRAMMAR_ABI,
     EXT_LANG,
     type Lang,
+    type ResolvedVia,
     SCHEMA_VERSION,
 } from './types.js';
 
@@ -145,7 +157,9 @@ function satisfies(kind: string | undefined, want: Capability): boolean {
  */
 interface FileScope {
     locals: Map<string, string[]>;
-    imports: Map<string, { target: string; exact: boolean }>;
+    /** `via` records WHICH tier produced the binding, so an edge built from it
+     * reports the mechanism instead of assuming `import-specifier`. */
+    imports: Map<string, { target: string; exact: boolean; via: ResolvedVia }>;
 }
 
 const REL_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
@@ -199,11 +213,40 @@ function push(map: Map<string, string[]>, k: string, v: string): void {
     } else map.set(k, [v]);
 }
 
+/**
+ * Read the project's declared resolution tiers from `root` (2.3).
+ *
+ * IO lives here rather than in `buildGraph`, which stays pure so identical
+ * source plus identical config yields identical bytes. A missing or
+ * unparseable config is not an error — it degrades to no tiers, which is the
+ * behaviour every build had before this existed.
+ *
+ * `tsconfig.json` is read as JSONC: it is JSONC by convention and this
+ * repository's own carries `//` comments, so `JSON.parse` on it throws.
+ */
+export function readResolutionConfig(root: string): ResolutionConfig {
+    const read = (name: string): unknown | null => {
+        try {
+            return parseJsonc(fs.readFileSync(path.join(root, name), 'utf-8'));
+        } catch {
+            return null;
+        }
+    };
+    return {
+        aliases: aliasRulesFrom(read('tsconfig.json')),
+        psr4: psr4RulesFrom(read('composer.json')),
+    };
+}
+
 /**
  * Pure, deterministic graph build over an in-memory file set. Exposed for
  * tests (no IO). `buildFromRepo` is the IO wrapper.
  */
-export function buildGraph(files: readonly SourceFile[], extracts: readonly FileExtract[]): CodeGraph {
+export function buildGraph(
+    files: readonly SourceFile[],
+    extracts: readonly FileExtract[],
+    resolution: ResolutionConfig = EMPTY_RESOLUTION_CONFIG,
+): CodeGraph {
     const nodes = extracts.flatMap((e) => e.nodes);
     const nodeIds = new Set(nodes.map((n) => n.id));
 
@@ -277,7 +320,7 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
     for (const ex of extracts) {
         const locals = new Map<string, string[]>();
         for (const n of ex.nodes) if (n.kind !== 'file') push(locals, n.label, n.id);
-        const imports = new Map<string, { target: string; exact: boolean }>();
+        const imports = new Map<string, { target: string; exact: boolean; via: ResolvedVia }>();
         for (const r of ex.rawEdges) {
             if (r.relation !== 'imports') continue;
             const local = r.localName ?? r.targetName;
@@ -285,29 +328,58 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
             const spec = r.moduleSpecifier;
             if (spec === undefined) {
                 // PHP `use A\B\C` — a fully-qualified NAME, not a module path.
-                // Resolved by base name without checking the namespace, so the
-                // binding is a lookup, not a syntactic fact: `exact: false`.
+                //
+                // TIER 1 (2.3): composer PSR-4 maps the NAMESPACE to a
+                // directory, so the class file is named outright. That is a
+                // declared mapping, hence `exact: true` — and it is the only
+                // rung that can tell two same-named classes in different
+                // namespaces apart.
+                const fq = r.fqName ?? r.targetName;
+                const psr4File = resolvePsr4(fq, resolution, fileIds);
+                if (psr4File !== null) {
+                    const member = `${psr4File}#${r.targetName}`;
+                    imports.set(local, {
+                        target: nodeKind.has(member) ? member : psr4File,
+                        exact: true,
+                        via: PSR4_VIA,
+                    });
+                    continue;
+                }
+                // TIER 2: base name, namespace discarded. A lookup, not a
+                // syntactic fact: `exact: false`.
                 const hit =
                     sym.classByName.get(k(ex.lang, r.targetName)) ??
                     (sym.byName.get(k(ex.lang, r.targetName)) ?? []).find((id) => id.includes('#') && !id.includes('::'));
-                if (hit) imports.set(local, { target: hit, exact: false });
+                if (hit) imports.set(local, { target: hit, exact: false, via: 'name-lookup' });
                 continue;
             }
-            const file = resolveSpecifier(ex.file, spec, fileIds);
+            // TIER 0: a relative specifier — the file says where it points.
+            // TIER 1 (2.3): tsconfig `paths`. `@shared/x` IS `src/shared/x`
+            // because the project declares it, so this is a fact and not a
+            // guess. Without it the specifier is non-relative, `resolveSpecifier`
+            // returns null, and the import binds to `external:@shared/x` — a
+            // real module, correctly named, and the wrong one.
+            const relFile = resolveSpecifier(ex.file, spec, fileIds);
+            const aliasFile = relFile === null ? resolveAlias(spec, resolution, fileIds) : null;
+            const file = relFile ?? aliasFile;
             if (file === null) {
                 // Bare (`node:path`, `zod`) or relative-but-out-of-root. Either
                 // way the module is real and NAMED, and it is not this
                 // repository's same-named symbol. `import * as path from
                 // 'node:path'` ends here, which is the whole of 1.1.
                 const named = r.importKind === 'named';
-                imports.set(local, { target: named ? `external:${spec}#${r.targetName}` : `external:${spec}`, exact: true });
+                imports.set(local, {
+                    target: named ? `external:${spec}#${r.targetName}` : `external:${spec}`,
+                    exact: true,
+                    via: 'import-specifier',
+                });
                 continue;
             }
             // A namespace or default import binds the MODULE, never a
             // same-named export inside it.
             const member = `${file}#${r.targetName}`;
             const target = r.importKind === 'named' && nodeKind.has(member) ? member : file;
-            imports.set(local, { target, exact: true });
+            imports.set(local, { target, exact: true, via: aliasFile === null ? 'import-specifier' : ALIAS_VIA });
         }
         scopes.set(ex.file, { locals, imports });
     }
@@ -327,13 +399,23 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         want: Capability,
         lang: Lang,
         scopeOnly = false,
-    ): { target: string; confidence: EdgeConfidence } | null => {
+    ): { target: string; confidence: EdgeConfidence; via: ResolvedVia } | null => {
         const scope = scopes.get(file) ?? emptyScope;
+        // The ladder's rungs ARE the mechanism taxonomy, so `via` is read off
+        // the branch that succeeded rather than inferred afterwards.
         for (const id of scope.locals.get(name) ?? [])
-            if (satisfies(nodeKind.get(id), want)) return { target: id, confidence: 'EXTRACTED' };
+            if (satisfies(nodeKind.get(id), want))
+                return { target: id, confidence: 'EXTRACTED', via: 'same-file' };
         const bound = scope.imports.get(name);
         if (bound && satisfies(nodeKind.get(bound.target), want))
-            return { target: bound.target, confidence: bound.exact ? 'EXTRACTED' : 'INFERRED' };
+            return {
+                target: bound.target,
+                confidence: bound.exact ? 'EXTRACTED' : 'INFERRED',
+                // The binding knows how it was made — a tsconfig alias and a
+                // PSR-4 namespace are not import specifiers and must not be
+                // reported as ones.
+                via: bound.via,
+            };
         if (scopeOnly) return null;
         const wide =
             want === 'constructible'
@@ -344,10 +426,19 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         // Reached only by matching a name across the whole repository, with no
         // binding in this file to justify it. That is not a syntactic fact and
         // no longer claims to be one.
-        if (wide) return { target: wide, confidence: 'INFERRED' };
+        if (wide) return { target: wide, confidence: 'INFERRED', via: 'name-lookup' };
         return null;
     };
 
+/**
+ * The mechanism for an edge whose target did not resolve.
+ *
+ * A `symbol:` pseudo-target is the residue of a name lookup that found
+ * nothing, so `name-lookup` is what actually happened. `confidence` already
+ * carries whether it resolved; this field carries what was tried.
+ */
+    const UNRESOLVED_VIA: ResolvedVia = 'name-lookup';
+
     // Deduped the same way emitted edges are, so the count is comparable to
     // `edges.length` rather than being a raw call-site tally that reads as a
     // larger loss than the graph actually took.
@@ -372,6 +463,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 target: hit?.target ?? `symbol:${inh.parentName}`,
                 relation: 'inherits',
                 confidence: hit?.confidence ?? 'EXTRACTED',
+                resolved_via: hit?.via ?? UNRESOLVED_VIA,
+                provider: 'native',
             });
         }
         for (const r of ex.rawEdges) resolveRawEdge(r, ex);
@@ -386,6 +479,11 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 target: nodeIds.has(target) ? target : `symbol:${r.targetName}`,
                 relation: 'member',
                 confidence: 'EXTRACTED',
+                // A member id is DERIVED from its own source node's id, so the
+                // declaration is in the same file by construction — no lookup
+                // of any kind happens here.
+                resolved_via: nodeIds.has(target) ? 'same-file' : UNRESOLVED_VIA,
+                provider: 'native',
             });
             return;
         }
@@ -400,6 +498,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 target: bound?.target ?? `symbol:${r.targetName}`,
                 relation: 'imports',
                 confidence: bound ? (bound.exact ? 'EXTRACTED' : 'INFERRED') : 'EXTRACTED',
+                resolved_via: bound ? bound.via : UNRESOLVED_VIA,
+                provider: 'native',
             });
             return;
         }
@@ -416,6 +516,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 target: hit?.target ?? `symbol:${r.targetName}`,
                 relation: 'uses',
                 confidence: hit?.confidence ?? 'EXTRACTED',
+                resolved_via: hit?.via ?? UNRESOLVED_VIA,
+                provider: 'native',
             });
             return;
         }
@@ -433,13 +535,25 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 // EXTRACTED is a claim about a SPECIFIC in-repo node reached by
                 // name alone.
                 confidence: hit?.confidence ?? 'EXTRACTED',
+                resolved_via: hit?.via ?? UNRESOLVED_VIA,
+                provider: 'native',
             });
             return;
         }
         if (r.callStyle === 'this' || r.callStyle === 'self' || r.callStyle === 'static' || r.callStyle === 'parent') {
             const hit = r.enclosingClassId ? resolveHierMethod(r.enclosingClassId, r.targetName) : null;
             if (hit) {
-                emit({ source: r.sourceId, target: hit, relation: 'calls', confidence: 'INFERRED' });
+                emit({
+                    source: r.sourceId,
+                    target: hit,
+                    relation: 'calls',
+                    confidence: 'INFERRED',
+                    // Walked the class hierarchy, which is same-file only when
+                    // the declaring class is; the honest mechanism for a
+                    // hierarchy walk is the repo-wide method table.
+                    resolved_via: 'name-lookup',
+                    provider: 'native',
+                });
             } else {
                 // enclosing class extends an out-of-repo base → honest AMBIGUOUS
                 const cands = methodCandidates(r.targetName, ex.lang);
@@ -448,6 +562,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                     target: ambiguousTarget(cands, r.targetName),
                     relation: 'calls',
                     confidence: 'AMBIGUOUS',
+                    resolved_via: 'dynamic',
+                    provider: 'native',
                     // The enclosing class extends a base outside this
                     // repository, so the method is not findable HERE — a
                     // different cause from a call whose receiver is unknown,
@@ -486,6 +602,8 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
             target: ambiguousTarget(cands, r.targetName),
             relation: 'calls',
             confidence: 'AMBIGUOUS',
+            resolved_via: 'dynamic',
+            provider: 'native',
             // Receiver type unknown: `$obj->m()` or an unresolved `C::m()`.
             // Resolving this needs type inference the extractor does not do,
             // which is exactly what 1.2 has to decide about rather than assume.
@@ -583,6 +701,11 @@ export function serializeGraph(g: CodeGraph): string {
             target: e.target,
             relation: e.relation,
             confidence: e.confidence,
+            // Unconditional, unlike the two optional fields below: these are
+            // required on every edge, so emitting them conditionally would make
+            // an absent field mean "not set" instead of being impossible.
+            resolved_via: e.resolved_via,
+            provider: e.provider,
         };
         // Ordered before `candidates` deliberately: the reason is the coarser
         // axis and a reader scanning the serialized graph sees WHY before HOW
@@ -684,7 +807,7 @@ export async function buildFromRepo(
         nextSidecar.files[f.path] = { hash, extract };
     }
 
-    const graph = buildGraph(files, extracts);
+    const graph = buildGraph(files, extracts, readResolutionConfig(root));
     const json = serializeGraph(graph);
     if (cachePath) {
         write_atomic(cachePath, json);