@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/code_graph/foreign.ts

@@ -0,0 +1,194 @@
+/**
+ * Read a consumer's own code-graph file, in the shape another tool wrote it.
+ *
+ * The defect this closes: `detect.ts` already ACCEPTS a `links`-shaped
+ * graph.json — `looksLikeGraph` passes anything with `nodes[]` and
+ * `edges`-or-`links[]` carrying `source`/`target` — and then `query.ts`
+ * `loadGraph` throws on it, because `validateGraph` demands `edges`,
+ * `schema_version`, `source_checksum` and a per-edge `resolved_via` and
+ * `provider`. So a consumer who ships a graph got told it was detected and
+ * then watched every verb crash on it. Detected-but-unloadable is the worst
+ * of both answers.
+ *
+ * What this module does NOT do is make those edges trustworthy. A foreign
+ * relation vocabulary is another tool's, and mapping it is an interpretation:
+ * their `calls` may be our `calls` or may be their build graph's dependency
+ * arrow. So every adapted edge is tagged `resolved_via: 'foreign'`, which
+ * joins the GUESS set — the same set `name-lookup` and `dynamic` are in — and
+ * the gate verbs refuse a graph made only of guesses rather than answering
+ * from one.
+ *
+ * A relation this module cannot map is COUNTED and DROPPED, never guessed
+ * into the nearest native relation. A wrong edge that reads as a real one is
+ * worse than a missing edge that reads as a number.
+ */
+
+import { createHash } from 'node:crypto';
+
+import type { CodeGraph, CodeEdge, CodeNode, EdgeConfidence, Relation } from './types.js';
+import { SCHEMA_VERSION } from './types.js';
+
+/** What a foreign load produced, including what it could not use. */
+export interface ForeignLoadResult {
+    graph: CodeGraph;
+    /** Edges dropped because their relation has no native counterpart. */
+    unmapped_relations: Record<string, number>;
+    /** Edges dropped because an endpoint was missing or not a string. */
+    malformed_edges: number;
+}
+
+/**
+ * Foreign relation vocabulary → ours.
+ *
+ * Deliberately small and literal. Every entry is a word whose meaning is the
+ * same in both vocabularies; a word that is merely SIMILAR is left out, so it
+ * lands in `unmapped_relations` and is reported rather than mapped on a hunch.
+ * This is a list of OUR relation names and their obvious synonyms, not a table
+ * of any particular tool's schema.
+ */
+const RELATION_MAP: Readonly<Record<string, Relation>> = {
+    calls: 'calls',
+    call: 'calls',
+    invokes: 'calls',
+    imports: 'imports',
+    import: 'imports',
+    requires: 'imports',
+    uses: 'uses',
+    use: 'uses',
+    references: 'uses',
+    inherits: 'inherits',
+    extends: 'inherits',
+    implements: 'inherits',
+    member: 'member',
+    contains: 'member',
+    tests: 'tests',
+    test: 'tests',
+};
+
+const KINDS = new Set([
+    'file',
+    'class',
+    'interface',
+    'trait',
+    'function',
+    'method',
+    'constant',
+    'type',
+    'enum',
+    'skipped',
+]);
+
+function isObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Does this document look like a foreign graph rather than one of ours?
+ *
+ * `links` in place of `edges` is the clearest tell and is the shape
+ * `detect.ts` already accepts. A document carrying `edges` but no
+ * `schema_version` is foreign too — ours always writes one.
+ */
+export function looksForeign(doc: unknown): boolean {
+    if (!isObject(doc)) return false;
+    if (!Array.isArray(doc['nodes'])) return false;
+    if (Array.isArray(doc['links'])) return true;
+    return Array.isArray(doc['edges']) && typeof doc['schema_version'] !== 'number';
+}
+
+/**
+ * Adapt a foreign graph document into the native shape.
+ *
+ * `schema_version` and `source_checksum` are SYNTHESISED: the first is ours
+ * by definition once the document is in our shape, and the second is a digest
+ * of the document itself, so a changed foreign file produces a changed
+ * checksum and the cache layer behaves as it does for a native graph. Neither
+ * is read off the foreign file — a number another tool wrote under the same
+ * key would mean something else.
+ */
+export function adaptForeignGraph(doc: unknown): ForeignLoadResult | null {
+    if (!isObject(doc)) return null;
+    const rawNodes = doc['nodes'];
+    const rawEdges = doc['links'] ?? doc['edges'];
+    if (!Array.isArray(rawNodes) || !Array.isArray(rawEdges)) return null;
+
+    const nodes: CodeNode[] = [];
+    const ids = new Set<string>();
+    for (const n of rawNodes) {
+        if (!isObject(n)) continue;
+        const id = n['id'];
+        if (typeof id !== 'string' || id === '') continue;
+        const kind = typeof n['kind'] === 'string' && KINDS.has(n['kind']) ? n['kind'] : 'skipped';
+        const sourceFile =
+            typeof n['source_file'] === 'string'
+                ? n['source_file']
+                : typeof n['file'] === 'string'
+                  ? n['file']
+                  : '';
+        nodes.push({
+            id,
+            label: typeof n['label'] === 'string' ? n['label'] : id,
+            kind,
+            source_file: sourceFile,
+            // A foreign node rarely carries a span. An empty one is honest —
+            // it says "no location recorded", where a fabricated [1,1] would
+            // point a reader at the top of a file for no reason.
+            source_location: Array.isArray(n['source_location']) ? n['source_location'] : [],
+        } as CodeNode);
+        ids.add(id);
+    }
+
+    const edges: CodeEdge[] = [];
+    const unmapped: Record<string, number> = {};
+    let malformed = 0;
+    for (const e of rawEdges) {
+        if (!isObject(e)) {
+            malformed += 1;
+            continue;
+        }
+        const source = e['source'];
+        const target = e['target'];
+        if (typeof source !== 'string' || typeof target !== 'string' || !ids.has(source)) {
+            malformed += 1;
+            continue;
+        }
+        const rawRelation = typeof e['relation'] === 'string' ? e['relation'] : '';
+        const relation = RELATION_MAP[rawRelation.toLowerCase()];
+        if (relation === undefined) {
+            const key = rawRelation === '' ? '(none)' : rawRelation;
+            unmapped[key] = (unmapped[key] ?? 0) + 1;
+            continue;
+        }
+        edges.push({
+            source,
+            target,
+            relation,
+            // Not EXTRACTED: this package did not extract it and cannot say
+            // how the tool that did arrived at it.
+            confidence: 'AMBIGUOUS' as EdgeConfidence,
+            resolved_via: 'foreign',
+            provider: 'foreign',
+        } as CodeEdge);
+    }
+
+    const counts: Record<string, number> = { EXTRACTED: 0, INFERRED: 0, AMBIGUOUS: edges.length };
+    const graph = {
+        schema_version: SCHEMA_VERSION,
+        source_checksum: createHash('sha256')
+            .update(JSON.stringify(doc), 'utf-8')
+            .digest('hex'),
+        languages: [],
+        grammar_abi: 0,
+        edge_confidence_counts: counts,
+        suppressed_edge_counts: { dynamic_no_candidate: 0 },
+        nodes,
+        edges,
+    } as unknown as CodeGraph;
+
+    return { graph, unmapped_relations: unmapped, malformed_edges: malformed };
+}
+
+/** True when every edge in `g` came from a foreign file. */
+export function isAllForeign(g: CodeGraph): boolean {
+    return g.edges.length > 0 && g.edges.every((e) => e.resolved_via === 'foreign');
+}

package/src/scripts/code_graph/query.ts

@@ -16,8 +16,9 @@ import {
     loadSerializedFromTwin,
     openGraphIndex,
 } from './sqlite_store.js';
-import type { CodeEdge, CodeGraph, CodeNode } from './types.js';
+import type { CodeEdge, CodeGraph, CodeNode, Relation } from './types.js';
 import { validateGraph } from './validate.js';
+import { adaptForeignGraph, looksForeign } from './foreign.js';
 
 const APPROX_CHARS_PER_TOKEN = 4;
 
@@ -145,10 +146,27 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     const fromTwin = loadSerializedFromTwin(graphPath);
     const raw = fromTwin ?? fs.readFileSync(graphPath, 'utf-8');
     const parsed = JSON.parse(raw) as unknown;
-    const v = validateGraph(parsed);
+    // A consumer's own graph file, written by another tool, is DETECTED by
+    // `detect.ts` and used to throw here — detected-but-unloadable, the worst
+    // of both answers. Adapt it instead: its edges carry `resolved_via:
+    // 'foreign'`, which is in the guess set, so the gate verbs refuse it by
+    // name rather than answering from it.
+    let foreignAdapted = false;
+    let candidate = parsed;
+    if (looksForeign(parsed)) {
+        const adapted = adaptForeignGraph(parsed);
+        if (adapted !== null) {
+            candidate = adapted.graph;
+            foreignAdapted = true;
+        }
+    }
+    const v = validateGraph(candidate);
     if (!v.ok) throw new Error(`invalid graph at ${graphPath}: ${v.errors.slice(0, 3).join('; ')}`);
-    const graph = parsed as CodeGraph;
-    if (fromTwin === null) {
+    const graph = candidate as CodeGraph;
+    // The twin is a cache of a file's bytes keyed on its own checksum. An
+    // adapted graph's bytes are not the file's, so emitting one would cache a
+    // derivation under the source's identity.
+    if (fromTwin === null && !foreignAdapted) {
         emitSqliteTwin(graph, raw, graphPath);
     }
     const byId = new Map(graph.nodes.map((n) => [n.id, n]));
@@ -203,6 +221,47 @@ function resolveSeedsTiered(g: LoadedGraph, seed: string, limit = 5): SeedResolu
     return { ids: ranked.slice(0, limit).map((r) => r.id), weak: true };
 }
 
+/**
+ * The EXACT half of the ladder above — id, then label — with no BM25 tier.
+ *
+ * `graph_node` is a node tool: every field it returns (location, degree, the
+ * edge lists) is a statement about ONE node, so answering about a best-guess
+ * node is worse than refusing. D4 of `road-to-a-graph-that-feeds-the-gate` makes
+ * that explicit for this tool — free-text retrieval is the row the graph lost,
+ * so a node answer never rests on a score.
+ *
+ * Still the same ladder and not a second resolver: this calls
+ * {@link resolveSeedsTiered} and reads its `weak` flag, so a change to the
+ * exact tiers reaches both callers.
+ *
+ * `ambiguous` carries the candidates when a LABEL resolves to several nodes.
+ * Picking the first would be the silent guess this function exists to avoid; the
+ * caller re-asks with one of the ids.
+ */
+export function resolveExactNode(
+    g: LoadedGraph,
+    seed: string,
+): { id: string | null; ambiguous: string[]; more: boolean } {
+    // The ladder's default limit is 5, and inheriting it made the refusal LIE:
+    // a label on twelve nodes refused with "is a label on 5 nodes" and listed
+    // five of them with nothing saying the list was cut. A completion review
+    // reproduced it. Ask for one more than we will show, so truncation is
+    // detectable rather than invisible.
+    const r = resolveSeedsTiered(g, seed, AMBIGUITY_SHOWN + 1);
+    if (r.weak || r.ids.length === 0) return { id: null, ambiguous: [], more: false };
+    if (r.ids.length > 1) {
+        return {
+            id: null,
+            ambiguous: r.ids.slice(0, AMBIGUITY_SHOWN),
+            more: r.ids.length > AMBIGUITY_SHOWN,
+        };
+    }
+    return { id: r.ids[0] as string, ambiguous: [], more: false };
+}
+
+/** How many candidate ids an ambiguity refusal lists before it says "and more". */
+const AMBIGUITY_SHOWN = 25;
+
 /** Resolve a free-text seed to node ids: exact id → exact label → BM25. */
 export function resolveSeeds(g: LoadedGraph, seed: string, limit = 5): string[] {
     return resolveSeedsTiered(g, seed, limit).ids;
@@ -421,3 +480,157 @@ export function mergeRecommendedReads(results: readonly QueryResult[]): Recommen
     for (const r of results) for (const rr of r.recommended_reads) merged.set(readKey(rr), rr);
     return [...merged.values()];
 }
+
+// ---------------------------------------------------------------------------
+// `node` — one node, its location, its edges, its degree (3.1)
+// ---------------------------------------------------------------------------
+
+/** One edge as the node view renders it: who, how, which way, how far. */
+export interface NodeEdgeLine {
+    /** The node at the OTHER end — the caller for an in-edge, the callee for an out-edge. */
+    id: string;
+    label: string;
+    relation: Relation;
+    confidence: string;
+    hops: number;
+}
+
+export interface NodeResult {
+    source: string;
+    /** The resolved id, or `''` when nothing resolved and `refusal` is set. */
+    id: string;
+    label: string;
+    kind: string;
+    /** File + 1-based inclusive line range, or `null` for a placeholder node. */
+    location: RecommendedRead | null;
+    /** DIRECT edge counts, always 1-hop — a degree is not a property of a walk. */
+    in_degree: number;
+    out_degree: number;
+    in: NodeEdgeLine[];
+    out: NodeEdgeLine[];
+    truncated: boolean;
+    /** Set when the seed did not resolve exactly; every other field is empty. */
+    refusal?: string;
+}
+
+export interface NodeOptions {
+    direction?: 'in' | 'out' | 'both';
+    /** 1-3. Anything outside the range is clamped rather than refused. */
+    depth?: number;
+    /** Restrict to one relation of the closed vocabulary. */
+    relation?: Relation;
+}
+
+/** Hard cap per direction, so one hub node cannot return an unbounded payload. */
+const NODE_EDGE_CAP = 200;
+
+/**
+ * Walk one direction from `start`, recording each edge once, breadth-first.
+ *
+ * `seen` is keyed on the NODE, so a cycle terminates; the edge list can still
+ * carry two lines into the same node by different relations, which is a real
+ * distinction a caller asked for when it passed no `relation`.
+ */
+function walkDirection(
+    g: LoadedGraph,
+    start: string,
+    dir: 'in' | 'out',
+    depth: number,
+    relation: Relation | undefined,
+): { lines: NodeEdgeLine[]; truncated: boolean } {
+    const lines: NodeEdgeLine[] = [];
+    const seen = new Set<string>([start]);
+    let frontier = [start];
+    let truncated = false;
+    for (let hop = 1; hop <= depth && frontier.length > 0; hop += 1) {
+        const next: string[] = [];
+        for (const cur of frontier) {
+            for (const e of (dir === 'out' ? g.out : g.in).get(cur) ?? []) {
+                if (relation !== undefined && e.relation !== relation) continue;
+                const other = dir === 'out' ? e.target : e.source;
+                if (lines.length >= NODE_EDGE_CAP) {
+                    truncated = true;
+                    break;
+                }
+                lines.push({
+                    id: sanitizeLabel(other),
+                    label: label(g, other),
+                    relation: e.relation,
+                    confidence: e.confidence,
+                    hops: hop,
+                });
+                if (!seen.has(other)) {
+                    seen.add(other);
+                    next.push(other);
+                }
+            }
+            if (truncated) break;
+        }
+        if (truncated) break;
+        frontier = next;
+    }
+    return { lines, truncated };
+}
+
+/**
+ * `node <seed>` — what one node IS, rather than what a walk from it reaches.
+ *
+ * The five readers before it all answer a question about a neighbourhood
+ * (`query`, `explain`, `affected`, `path`) or about a set (`dead`, `untested`).
+ * None answers "where does this live, who reaches it, what does it reach, how
+ * connected is it" — which is the question an agent asks first and had to
+ * assemble from two calls and a file read.
+ *
+ * Nothing new is walked: the edge maps are the ones `affected` already uses, so
+ * this adds a view, not an index.
+ */
+export function node(g: LoadedGraph, seed: string, opts: NodeOptions = {}): NodeResult {
+    const empty = {
+        source: g.source,
+        id: '',
+        label: '',
+        kind: '',
+        location: null,
+        in_degree: 0,
+        out_degree: 0,
+        in: [] as NodeEdgeLine[],
+        out: [] as NodeEdgeLine[],
+        truncated: false,
+    };
+    const { id, ambiguous, more } = resolveExactNode(g, seed);
+    if (id === null) {
+        return {
+            ...empty,
+            refusal:
+                ambiguous.length > 0
+                    ? `'${sanitizeLabel(seed)}' is a label on ${more ? 'more than ' : ''}` +
+                      `${String(ambiguous.length)} nodes — re-ask with one id: ` +
+                      `${ambiguous.map((a) => sanitizeLabel(a)).join(', ')}` +
+                      (more ? ' (list truncated)' : '')
+                    : `'${sanitizeLabel(seed)}' matches no node id and no node label. This tool ` +
+                      'resolves exactly (id, then label) and does not score free text — use ' +
+                      '`query` if a best-guess match is what you want.',
+        };
+    }
+    const n = g.byId.get(id);
+    const direction = opts.direction ?? 'both';
+    const depth = Math.min(3, Math.max(1, Math.trunc(opts.depth ?? 1)));
+    const inWalk =
+        direction === 'out' ? { lines: [], truncated: false } : walkDirection(g, id, 'in', depth, opts.relation);
+    const outWalk =
+        direction === 'in' ? { lines: [], truncated: false } : walkDirection(g, id, 'out', depth, opts.relation);
+    const degreeOf = (edges: readonly CodeEdge[] | undefined): number =>
+        opts.relation === undefined ? (edges?.length ?? 0) : (edges ?? []).filter((e) => e.relation === opts.relation).length;
+    return {
+        source: g.source,
+        id: sanitizeLabel(id),
+        label: label(g, id),
+        kind: n?.kind ?? '',
+        location: recommendedReadFor(g, id),
+        in_degree: degreeOf(g.in.get(id)),
+        out_degree: degreeOf(g.out.get(id)),
+        in: inWalk.lines,
+        out: outWalk.lines,
+        truncated: inWalk.truncated || outWalk.truncated,
+    };
+}

package/src/scripts/code_graph/types.ts

@@ -66,7 +66,16 @@ export type ResolvedVia =
     | 'route-table'
     | 'test-import'
     | 'name-lookup'
-    | 'dynamic';
+    | 'dynamic'
+    /**
+     * Read from a consumer's own graph file, written by another tool.
+     *
+     * Not a mechanism THIS package used — a statement that it used none. The
+     * relation came from someone else's vocabulary and was mapped, which is
+     * an interpretation, so the value belongs in the guess set below and the
+     * gate verbs refuse a graph made only of these.
+     */
+    | 'foreign';
 
 /**
  * WHICH engine produced the edge.
@@ -77,7 +86,17 @@ export type ResolvedVia =
  * apart. Kill register K2 forbids an external provider entering `src/`, so this
  * stays a single-member union until a decision changes that.
  */
-export type EdgeProvider = 'native';
+export type EdgeProvider =
+    | 'native'
+    /**
+     * The edge was read from a graph file this package did not build.
+     *
+     * This is a DATA tag on an edge, not an engine in `src/`: no foreign
+     * extractor is vendored, imported or executed anywhere, and K2 is about
+     * the latter. The field exists precisely so a mixed graph can be told
+     * apart, and a consumer-shipped graph is the first case where it is.
+     */
+    | 'foreign';
 
 /**
  * The two mechanisms that are GUESSES rather than statements.
@@ -99,6 +118,11 @@ export type EdgeProvider = 'native';
 export const GUESS_RESOLVED_VIA: ReadonlySet<ResolvedVia> = new Set<ResolvedVia>([
     'name-lookup',
     'dynamic',
+    // The accepted-edge filter is a DENYLIST, so a new value is accepted by
+    // default — which is exactly backwards for this one. `foreign` must be
+    // listed here or a consumer's graph would silently answer the gate verbs
+    // as if this package had resolved its edges.
+    'foreign',
 ]);
 
 /** Does this edge's target rest on a stated fact rather than a guess? */

package/src/scripts/code_graph/validate.ts

@@ -19,8 +19,10 @@ const RESOLVED_VIA = new Set([
     'test-import',
     'name-lookup',
     'dynamic',
+    // Adapted from a consumer's own graph file; see `foreign.ts`.
+    'foreign',
 ]);
-const PROVIDERS = new Set(['native']);
+const PROVIDERS = new Set(['native', 'foreign']);
 const KINDS = new Set([
     'file',
     'class',

package/src/scripts/code_graph/verbs.ts

@@ -52,6 +52,38 @@ export function isAcceptedEdge(e: CodeEdge): boolean {
     return isStatedResolution(e.resolved_via);
 }
 
+/** Why a gate verb refused. A closed set so a caller can branch on it. */
+export type RefusalReason = 'foreign-edges-not-accepted' | 'entry-points-unavailable';
+
+/**
+ * A graph whose every edge came from a file this package did not build.
+ *
+ * Those edges are tagged `foreign` and sit in the guess set, so a gate verb
+ * walking one would accept nothing and report an empty answer — and an empty
+ * answer from a gate reads as "nothing to worry about", which is the wrong
+ * reading and the dangerous one. The verbs refuse instead, by name, so the
+ * consumer learns that their graph is readable but not gate-grade rather than
+ * being told their diff impacts nothing.
+ *
+ * A MIXED graph is not refused: it carries edges this package did resolve, and
+ * the guess filter already excludes the foreign ones from the walk.
+ */
+export function foreignRefusal(g: LoadedGraph): string | null {
+    // `graph` is null on the index-backed read path, which answers per-node
+    // from the twin and never materialises the edge list. Nothing to classify
+    // there, and an index-backed graph is one this package built.
+    const edges: readonly CodeEdge[] = g.graph?.edges ?? [];
+    if (edges.length === 0) return null;
+    if (!edges.every((e) => e.resolved_via === 'foreign')) return null;
+    return (
+        'every edge in this graph was read from a file this package did not build, so all of them ' +
+        'are guesses and none is gate-grade. A gate verb would accept no edge and report an empty ' +
+        'answer, which reads as "nothing found" rather than "nothing trusted". Build a native graph ' +
+        '(`agent-config graph build`) to use this verb, or use `query` and `explain`, which answer ' +
+        'from foreign edges and say so.'
+    );
+}
+
 /**
  * Relations that constitute a REFERENCE to the target, as opposed to
  * containment of it.
@@ -132,6 +164,10 @@ export interface ReachedNode {
 }
 
 export interface ImpactResult extends VerbReport {
+    /** Non-null when the verb REFUSED to answer. Every list is then empty. */
+    refusal: string | null;
+    /** Machine-readable reason, when `refusal` is set. */
+    refusal_reason: RefusalReason | null;
     /** Node ids the diff touched that the graph knows. */
     seeds: string[];
     /**
@@ -219,6 +255,26 @@ export function impact(
     depth = 2,
     isTest: (relPath: string) => boolean = () => false,
 ): ImpactResult {
+    const foreign = foreignRefusal(g);
+    if (foreign !== null) {
+        return {
+            source: g.source,
+            state,
+            accepted_via: '(none)',
+            rejected_via: '(none)',
+            refusal: foreign,
+            refusal_reason: 'foreign-edges-not-accepted',
+            seeds: [],
+            unresolved_files: [],
+            not_indexed_files: [],
+            dependents: [],
+            reached: [],
+            test_files: [],
+            producing_edges: [],
+            lines: [],
+            recommended_reads: [],
+        };
+    }
     const { seeds, unresolved, not_indexed } = seedsForFiles(g, files);
     const accepted: CodeEdge[] = [];
     const rejected: CodeEdge[] = [];
@@ -258,6 +314,8 @@ export function impact(
         state,
         accepted_via: viaHistogram(accepted),
         rejected_via: viaHistogram(rejected),
+        refusal: null,
+        refusal_reason: null,
         seeds,
         unresolved_files: unresolved,
         not_indexed_files: not_indexed,
@@ -334,6 +392,10 @@ export function testsFor(g: LoadedGraph, symbol: string, state: GraphState): Tes
 }
 
 export interface UntestedResult extends VerbReport {
+    /** Non-null when the verb REFUSED to answer. Every list is then empty. */
+    refusal: string | null;
+    /** Machine-readable reason, when `refusal` is set. */
+    refusal_reason: RefusalReason | null;
     seeds: string[];
     unresolved_files: string[];
     not_indexed_files: string[];
@@ -351,6 +413,24 @@ export interface UntestedResult extends VerbReport {
  * count and make the ratio meaningless.
  */
 export function untested(g: LoadedGraph, files: readonly string[], state: GraphState): UntestedResult {
+    const foreign = foreignRefusal(g);
+    if (foreign !== null) {
+        return {
+            source: g.source,
+            state,
+            accepted_via: '(none)',
+            rejected_via: '(none)',
+            refusal: foreign,
+            refusal_reason: 'foreign-edges-not-accepted',
+            seeds: [],
+            unresolved_files: [],
+            not_indexed_files: [],
+            untested: [],
+            tested: [],
+            lines: [],
+            recommended_reads: [],
+        };
+    }
     const { seeds, unresolved, not_indexed } = seedsForFiles(g, files);
     const accepted: CodeEdge[] = [];
     const rejected: CodeEdge[] = [];
@@ -375,6 +455,8 @@ export function untested(g: LoadedGraph, files: readonly string[], state: GraphS
         state,
         accepted_via: viaHistogram(accepted),
         rejected_via: viaHistogram(rejected),
+        refusal: null,
+        refusal_reason: null,
         seeds,
         unresolved_files: unresolved,
         not_indexed_files: not_indexed,
@@ -403,6 +485,8 @@ export interface DeadResult extends VerbReport {
     sources: EntryPointSource[];
     /** Non-null when the verb REFUSED to answer. The list is then empty. */
     refusal: string | null;
+    /** Machine-readable reason, when `refusal` is set. */
+    refusal_reason: RefusalReason | null;
     dead: string[];
     /** Entry points excluded from `dead` — the audit trail for the exclusion. */
     excluded: string[];
@@ -448,6 +532,23 @@ export function dead(
         state,
         sources: [...sources],
     };
+    // Checked BEFORE the entry-point sources: on an all-foreign graph every
+    // in-edge is a guess, so every symbol would report dead — the confident
+    // false "dead" this verb's own header calls worse than no verb at all.
+    const foreign = foreignRefusal(g);
+    if (foreign !== null) {
+        return {
+            ...base,
+            accepted_via: '(none)',
+            rejected_via: '(none)',
+            refusal: foreign,
+            refusal_reason: 'foreign-edges-not-accepted',
+            dead: [],
+            excluded: [],
+            lines: [],
+            recommended_reads: [],
+        };
+    }
     if (unavailable.length > 0 && opts.acceptMissingExports !== true) {
         return {
             ...base,
@@ -460,6 +561,7 @@ export function dead(
                 'A symbol they would have declared an entry point is indistinguishable from a dead one, ' +
                 'so no list is produced. Supply the missing source with --entry-points <file>, or state ' +
                 'that you accept the gap with --accept-missing-exports.',
+            refusal_reason: 'entry-points-unavailable',
             dead: [],
             excluded: [],
             lines: [],
@@ -496,6 +598,7 @@ export function dead(
         accepted_via: viaHistogram(accepted),
         rejected_via: viaHistogram(rejected),
         refusal: null,
+        refusal_reason: null,
         dead: list,
         excluded: excluded.sort(),
         lines: list,