@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/ci_settle.ts

@@ -18,10 +18,20 @@
  * every agent's head: `not settled` and `settled` are different from `could not
  * read`, and only the first two may end a wait.
  *
- * Exit codes: 0 = settled, every check succeeded (or was skipped) ·
+ * A verdict also has to be ABOUT SOMETHING, which is the second half of the
+ * same rule and was missing until 2026-09-08: the rollup answers about the head
+ * the PR *record* carries, and that head stops tracking the branch when the PR
+ * is merged or when the record lags a push. Both then look like a healthy
+ * green. {@link classifyTarget} refuses those, before the wait and again at
+ * verdict time. Measured cost of not having it: a `SETTLED GREEN — 40 check(s)`
+ * for a head with literally zero check runs.
+ *
+ * Exit codes: 0 = settled green, and the head it is about is named ·
  *             1 = settled, at least one check failed ·
- *             2 = did not settle within the budget, or the API could not be
- *                 read — NEVER a verdict, and the reason is printed.
+ *             2 = did not settle within the budget, the API could not be read,
+ *                 or the target is not a PR a verdict can be about (merged,
+ *                 closed, or head-diverged) — NEVER a verdict, and the reason
+ *                 is printed.
  *
  * Usage: ./scripts-run src/scripts/ci_settle <pr> [--timeout-min N] [--interval-sec N]
  *
@@ -57,6 +67,121 @@ export type PollState =
     | { kind: 'pending'; total: number; done: number }
     | { kind: 'settled'; failing: string[]; total: number };
 
+/**
+ * What `git ls-remote` said about the PR branch's tip.
+ *
+ * `absent` and `unreadable` are different answers and must not collapse: a
+ * cross-repo fork PR legitimately has no ref under this `origin`, while a
+ * transport failure means nobody knows. Collapsing them either disables the
+ * divergence check for forks silently, or blocks every fork PR forever.
+ */
+export type RemoteTip =
+    | { kind: 'found'; sha: string }
+    | { kind: 'absent' }
+    | { kind: 'unreadable'; reason: string };
+
+/**
+ * Whether the PR this wait is about still decides anything.
+ *
+ * `refuse` is NOT a verdict — it exits 2 like every other non-verdict, because
+ * the wait produced no readable statement about the head that matters.
+ */
+export type TargetState =
+    | { kind: 'open'; head: string; ref: string; divergenceChecked: boolean }
+    | { kind: 'unreadable'; reason: string }
+    | { kind: 'refuse'; reason: string };
+
+/**
+ * Decide whether a green from {@link classifyPoll} may be reported at all.
+ *
+ * WHY THIS EXISTS, measured 2026-09-08 on PR #1949 and paid for twice in one
+ * session. `gh pr view --json statusCheckRollup` answers about the head the PR
+ * *record* carries, and that head stops tracking the branch in two situations
+ * this script previously could not tell apart from a healthy wait:
+ *
+ * 1. **The PR is already merged or closed.** A push to its branch fires no
+ *    `pull_request` event, so no checks are created for the new commits and the
+ *    rollup keeps returning the merge-time head's checks. The script reported
+ *    `SETTLED GREEN — 40 check(s)` for a head that had stopped mattering, and
+ *    the only thing that exposed it was a hand-written
+ *    `/commits/<sha>/check-runs` query answering `0`. Reported at face value
+ *    that green authorises a merge of content nobody checked.
+ * 2. **The PR record lags the branch ref.** Same shape, different cause
+ *    (recorded on PR #710): `git ls-remote` shows the new SHA while the record
+ *    keeps the old one, and merging then lands the PR WITHOUT the newer
+ *    commits — silently, which is what makes it worse than a red.
+ *
+ * Both are answered by the same two facts, which is why one function decides
+ * them: the PR's `state`, and whether its head equals the branch tip. Pure, so
+ * the failure is testable without a network — feed it a merged PR and it must
+ * answer `refuse`, never `open`.
+ */
+export function classifyTarget(
+    stdout: string,
+    stderr: string,
+    status: number | null,
+    tip: RemoteTip,
+): TargetState {
+    const combined = `${stdout}\n${stderr}`.toLowerCase();
+    for (const marker of _UNREADABLE_MARKERS) {
+        if (combined.includes(marker.toLowerCase())) {
+            return { kind: 'unreadable', reason: marker };
+        }
+    }
+    if (status !== 0) {
+        return { kind: 'unreadable', reason: `gh exited ${String(status)}` };
+    }
+    let state: string;
+    let head: string;
+    let ref: string;
+    try {
+        const parsed = JSON.parse(stdout) as {
+            state?: unknown;
+            headRefOid?: unknown;
+            headRefName?: unknown;
+        };
+        if (
+            typeof parsed.state !== 'string' ||
+            typeof parsed.headRefOid !== 'string' ||
+            typeof parsed.headRefName !== 'string'
+        ) {
+            return { kind: 'unreadable', reason: 'no state / headRefOid / headRefName in response' };
+        }
+        state = parsed.state.toUpperCase();
+        head = parsed.headRefOid;
+        ref = parsed.headRefName;
+    } catch {
+        return { kind: 'unreadable', reason: 'unparseable JSON' };
+    }
+    if (state !== 'OPEN') {
+        return {
+            kind: 'refuse',
+            reason:
+                `the PR is ${state}, not OPEN. Its rollup describes head ${head.slice(0, 9)} as of ` +
+                'that transition; pushes after it create no checks, so a green here would be about ' +
+                'a head that no longer decides anything',
+        };
+    }
+    if (tip.kind === 'unreadable') {
+        return { kind: 'unreadable', reason: `branch tip: ${tip.reason}` };
+    }
+    if (tip.kind === 'absent') {
+        // A fork PR's ref is not under this origin. Say the check did not apply
+        // rather than pretending it passed.
+        return { kind: 'open', head, ref, divergenceChecked: false };
+    }
+    if (tip.sha !== head) {
+        return {
+            kind: 'refuse',
+            reason:
+                `the PR record is at head ${head.slice(0, 9)} but origin/${ref} is at ` +
+                `${tip.sha.slice(0, 9)}. Merging in this state lands the PR WITHOUT the newer ` +
+                'commits (recorded on PR #710), and any verdict here is about the wrong head',
+        };
+    }
+    return { kind: 'open', head, ref, divergenceChecked: true };
+}
+
 /** Markers that mean the API did not answer — not that nothing is pending. */
 const _UNREADABLE_MARKERS = [
     'error connecting to',
@@ -126,6 +251,41 @@ function poll(pr: string): PollState {
     return classifyPoll(r.stdout ?? '', r.stderr ?? '', r.status);
 }
 
+/**
+ * Read the branch tip from the remote, not from a local ref.
+ *
+ * A local `origin/<ref>` is only as fresh as the last fetch, and the divergence
+ * this guards against is created by somebody else's push — so a stale local ref
+ * would report agreement exactly when it matters most.
+ */
+function readTip(ref: string): RemoteTip {
+    const r = spawnSync('git', ['ls-remote', 'origin', `refs/heads/${ref}`], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+    });
+    if (r.status !== 0) {
+        const why = (r.stderr ?? '').trim().split('\n')[0] ?? `git exited ${String(r.status)}`;
+        return { kind: 'unreadable', reason: why };
+    }
+    const line = (r.stdout ?? '').trim();
+    if (line === '') return { kind: 'absent' };
+    const sha = line.split(/\s+/)[0] ?? '';
+    return sha === '' ? { kind: 'unreadable', reason: 'empty sha in ls-remote output' } : { kind: 'found', sha };
+}
+
+function readTarget(pr: string): TargetState {
+    const r = spawnSync('gh', ['pr', 'view', pr, '--json', 'state,headRefOid,headRefName'], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+    });
+    // The ref name comes from the same read, so the tip lookup needs it first;
+    // classifyTarget is called twice rather than plumbing a callback through a
+    // pure function.
+    const shape = classifyTarget(r.stdout ?? '', r.stderr ?? '', r.status, { kind: 'absent' });
+    if (shape.kind !== 'open') return shape;
+    return classifyTarget(r.stdout ?? '', r.stderr ?? '', r.status, readTip(shape.ref));
+}
+
 function sleepSync(seconds: number): void {
     // Deliberately synchronous: this is a CLI whose whole job is to block.
     spawnSync(process.execPath, ['-e', `setTimeout(()=>{}, ${String(seconds * 1000)})`], {
@@ -164,18 +324,58 @@ export function main(argv: readonly string[]): number {
     }
     const intervalSec = num('--interval-sec', 60);
 
+    // Up front, because waiting nine minutes to learn the PR was merged before
+    // the wait began is the expensive way to find out.
+    const before = readTarget(pr);
+    if (before.kind === 'refuse') {
+        process.stdout.write(`ci_settle: REFUSING TO WAIT — ${before.reason}. No verdict is claimed.\n`);
+        return 2;
+    }
+    if (before.kind === 'unreadable') {
+        process.stdout.write(
+            `ci_settle: could not read the PR's target state (${before.reason}) — NOT a verdict, waiting anyway; ` +
+                'the pre-verdict re-check below still applies.\n',
+        );
+    } else if (!before.divergenceChecked) {
+        process.stdout.write(
+            `ci_settle: origin carries no refs/heads/${before.ref} (a fork PR) — the head-divergence check does not apply here.\n`,
+        );
+    }
+
     const deadline = Date.now() + timeoutMin * 60_000;
     let unreadableStreak = 0;
 
     for (;;) {
         const state = poll(pr);
         if (state.kind === 'settled') {
+            // The rollup is about the record's head. Re-read that head at
+            // VERDICT time, not only at start: a push or a merge during the
+            // wait makes the rollup describe something the caller is not about
+            // to act on, and this is the last moment a wrong verdict is still
+            // preventable.
+            const at = readTarget(pr);
+            if (at.kind === 'refuse') {
+                process.stdout.write(
+                    `ci_settle: WITHHOLDING A VERDICT — ${at.reason}. The checks that settled are not about ` +
+                        'the head that matters now.\n',
+                );
+                return 2;
+            }
+            if (at.kind === 'unreadable') {
+                process.stdout.write(
+                    `ci_settle: WITHHOLDING A VERDICT — could not confirm the target head (${at.reason}). ` +
+                        'A verdict needs to name the head it is about.\n',
+                );
+                return 2;
+            }
             if (state.failing.length === 0) {
-                process.stdout.write(`ci_settle: SETTLED GREEN — ${String(state.total)} check(s)\n`);
+                process.stdout.write(
+                    `ci_settle: SETTLED GREEN — ${String(state.total)} check(s) on ${at.head.slice(0, 9)}\n`,
+                );
                 return 0;
             }
             process.stdout.write(
-                `ci_settle: SETTLED RED — ${String(state.failing.length)} of ${String(state.total)} failing:\n` +
+                `ci_settle: SETTLED RED — ${String(state.failing.length)} of ${String(state.total)} failing on ${at.head.slice(0, 9)}:\n` +
                     state.failing.map((f) => `  ${f}\n`).join(''),
             );
             return 1;

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,
@@ -23,7 +34,9 @@ import {
     type EdgeConfidence,
     EXPECTED_GRAMMAR_ABI,
     EXT_LANG,
+    isStatedResolution,
     type Lang,
+    type ResolvedVia,
     SCHEMA_VERSION,
 } from './types.js';
 
@@ -145,7 +158,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 +214,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 +321,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 +329,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 +400,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 +427,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 +464,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 +480,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 +499,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 +517,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 +536,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 +563,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 +603,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.
@@ -494,6 +613,52 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         });
     }
 
+    // DERIVED `tests` edges (3.2).
+    //
+    // A test file that imports an in-repo symbol from a NON-test file is
+    // asserted to test it. Derived here rather than extracted because the
+    // predicate is a property of the two PATHS, which no grammar can see, and
+    // because `buildGraph` already holds every `imports` edge plus the node
+    // table needed to reject cross-test and out-of-repo targets.
+    //
+    // Three exclusions, each of which would otherwise manufacture a false
+    // `tests` edge:
+    //   · target outside the repository (`external:*` / `symbol:*`) — there is
+    //     no subject to test;
+    //   · target in another TEST file — a shared test helper is not a subject;
+    //   · target is the subject FILE node rather than a symbol in it, which is
+    //     kept: a test that imports a module tests that module, and the file
+    //     node is the only handle a caller has for a module with no exported
+    //     symbol the extractor named;
+    //   · THE SOURCE IMPORT IS ITSELF A GUESS. Added after an independent review
+    //     demonstrated the laundering: a PHP `use Two\Mailer` with no
+    //     `composer.json` binds by BASE NAME, so the `imports` edge is
+    //     `name-lookup` and can point at `One\Mailer` — and a `tests` edge
+    //     derived from it, stamped `test-import`, made that wrong target
+    //     TRUSTWORTHY to every consumer of the accepted-edge filter. Measured
+    //     consequences on a two-namespace fixture: `tests-for One\Mailer`
+    //     named a test that does not test it, `tests-for Two\Mailer` reported
+    //     none, `untested` inverted the pair, and `dead` called the tested class
+    //     dead. A derived edge may never be more trustworthy than the edge it
+    //     was derived from.
+    const nodeSourceFile = new Map(nodes.map((n) => [n.id, n.source_file]));
+    for (const e of [...edges]) {
+        if (e.relation !== 'imports') continue;
+        if (!isStatedResolution(e.resolved_via)) continue;
+        const from = nodeSourceFile.get(e.source);
+        if (from === undefined || !isTestFile(from)) continue;
+        const to = nodeSourceFile.get(e.target);
+        if (to === undefined || isTestFile(to)) continue;
+        emit({
+            source: e.source,
+            target: e.target,
+            relation: 'tests',
+            confidence: 'INFERRED',
+            resolved_via: 'test-import',
+            provider: 'native',
+        });
+    }
+
     // deterministic ordering
     nodes.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
     edges.sort((a, b) => {
@@ -559,6 +724,38 @@ function ambiguousTarget(candidates: readonly string[], targetName: string): str
     return `symbol:${targetName}`;
 }
 
+/**
+ * Is `relPath` a test file?
+ *
+ * A deterministic PATH predicate — no content read, no heuristic on the file's
+ * body. It is the input to the derived `tests` relation (3.2), so it has to be
+ * conservative in one direction only: a subject wrongly classified as a test
+ * silently loses its `tests` edges, while a test wrongly classified as a
+ * subject would make a test file look like a tested surface. Both are wrong;
+ * the second is worse, because `untested` would then report a real subject as
+ * covered.
+ *
+ * The four conventions are the ones this launch set actually uses, and each is
+ * anchored rather than substring-matched so a directory called
+ * `src/latest/thing.ts` is not a test:
+ *
+ *   · a `tests/` or `test/` path segment (this repository's own layout);
+ *   · a `__tests__/` segment (the JS convention);
+ *   · a `.test.` / `.spec.` filename infix (Vitest / Jest / Pest-JS);
+ *   · a `Test.php` / `test.php` filename suffix, or a `_test.php` infix
+ *     (PHPUnit's `*Test.php` and Go-style `_test` both appear in PHP trees).
+ */
+export function isTestFile(relPath: string): boolean {
+    const p = relPath.split(path.sep).join('/');
+    const segments = p.split('/');
+    if (segments.some((seg) => seg === 'tests' || seg === 'test' || seg === '__tests__')) return true;
+    const base = segments[segments.length - 1] ?? '';
+    if (/\.(test|spec)\./i.test(base)) return true;
+    if (/(^|[._-])test\.php$/i.test(base)) return true;
+    if (/Test\.php$/.test(base)) return true;
+    return false;
+}
+
 export function serializeGraph(g: CodeGraph): string {
     const key_order: (keyof CodeGraph)[] = [
         'schema_version',
@@ -583,6 +780,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 +886,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);