@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/code_graph/detect.ts

@@ -17,7 +17,9 @@ import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { load_agent_settings } from '../_lib/agent_settings.js';
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { EXT_LANG } from './types.js';
 import { validateGraph } from './validate.js';
 
 export type SourceKind = 'consumer' | 'scip' | 'native';
@@ -33,6 +35,44 @@ export interface SourceVerdict {
 
 const CONSUMER_CANDIDATES = ['graph.json', 'code-graph.json', '.code-graph/graph.json'];
 
+/**
+ * Extra graph paths the CONSUMER declares, from `code_graph.consumer_index_paths`.
+ *
+ * The default list above stays generic on purpose — three filenames, none of
+ * them any particular tool's. A tool that writes its index somewhere else is
+ * reachable by the consumer naming the path, never by this package shipping a
+ * table of vendor locations: such a table is wrong the day a tool moves its
+ * file and wrong forever about one nobody thought of, and
+ * `check_no_external_sources` would fail the build for carrying it.
+ *
+ * Absolute paths and anything escaping the project root are dropped. A setting
+ * that could point the walk at `/etc` would be a path-traversal surface in a
+ * read a consumer did not ask for.
+ */
+export function consumerCandidates(root: string): string[] {
+    let declared: unknown;
+    try {
+        const settings = load_agent_settings({ cwd: root }) ?? {};
+        const section = (settings as Record<string, unknown>)['code_graph'];
+        declared =
+            section !== null && typeof section === 'object' && !Array.isArray(section)
+                ? (section as Record<string, unknown>)['consumer_index_paths']
+                : undefined;
+    } catch {
+        declared = undefined;
+    }
+    const extra = Array.isArray(declared)
+        ? declared.filter(
+              (p): p is string =>
+                  typeof p === 'string' &&
+                  p !== '' &&
+                  !path.isAbsolute(p) &&
+                  !path.normalize(p).startsWith('..'),
+          )
+        : [];
+    return [...CONSUMER_CANDIDATES, ...extra.filter((p) => !CONSUMER_CANDIDATES.includes(p))];
+}
+
 function gitLastCommitEpoch(root: string): number | null {
     try {
         const out = execFileSync('git', ['-C', root, 'log', '-1', '--format=%ct'], {
@@ -100,7 +140,7 @@ export function detectSources(root: string, nativeCache: string): SourceVerdict[
     const abs = path.resolve(root);
     const out: SourceVerdict[] = [];
 
-    for (const rel of CONSUMER_CANDIDATES) {
+    for (const rel of consumerCandidates(abs)) {
         const p = path.join(abs, rel);
         if (fs.existsSync(p)) {
             const { ok, sha } = looksLikeGraph(p);
@@ -189,7 +229,12 @@ export function computeVerdict(root: string, nativeCache: string): VerdictJSON {
 export const NATIVE_CACHE_REL = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
 
 /**
- * The three-state staleness token every consumer of the graph reports.
+ * The four-state staleness token every consumer of the graph reports.
+ *
+ * `edited` is the fourth and newest (`road-to-a-graph-that-feeds-the-gate` 2.3).
+ * Without it an uncommitted change to an indexed file read as `fresh` — the one
+ * state that says "nothing stands between this answer and the tree" — which is
+ * the reading most likely to be wrong while someone is editing.
  *
  * Lives HERE rather than in the PreToolUse hook that first needed it
  * (`hooks/code_graph_context_hook.ts`, step 1.2). Phase 3's verbs must each
@@ -198,7 +243,73 @@ export const NATIVE_CACHE_REL = path.join('agents', 'runtime', 'state', 'code-gr
  * the engine, never the other way round. The hook re-exports this so its own
  * consumers are unaffected.
  */
-export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
+export type GraphState = 'absent' | 'fresh' | 'edited' | `behind:${number}`;
+
+/**
+ * The working tree carries an uncommitted change to a file the extractor would
+ * index.
+ *
+ * WHY POINT-IN-TIME PORCELAIN AND NOT THE ARTIFACT'S MTIME. An mtime comparison
+ * looks cheaper and is wrong in the one direction that matters: restoring a
+ * stashed or checked-out file rewrites its mtime, so a tree put back exactly as
+ * the graph saw it would read stale forever and never return to `fresh`. The
+ * porcelain result describes a CONTENT difference, so a revert is visible as a
+ * revert.
+ *
+ * "Indexed paths" is read as *paths of the kind the extractor indexes* —
+ * `EXT_LANG`'s extensions — not as the node set of a loaded graph. Loading the
+ * graph to answer a freshness question would mean opening the index on every
+ * PreToolUse call this now runs on, which is the latency the Risk Register
+ * names; the extension filter answers the same question with no read. It can
+ * over-report (a `.ts` file the build excluded) and cannot under-report, and
+ * over-reporting `edited` only ever makes an answer look worth less than it is.
+ *
+ * Untracked files count. A source file that exists only in the working tree is
+ * precisely something the index cannot know about.
+ *
+ * `--untracked-files=all` IS LOAD-BEARING, and the default was wrong. Plain
+ * porcelain COLLAPSES an untracked directory to one entry — `?? src/` — which
+ * carries no extension, so the filter below skipped it and an entire new source
+ * tree read as `fresh`. A completion review reproduced exactly that, and it is
+ * the one direction the paragraph above promises cannot happen. The cost is
+ * enumerating untracked files rather than untracked directories; `.gitignore`
+ * still applies, so a vendored tree stays out of it.
+ */
+function hasUncommittedIndexedEdit(root: string): boolean {
+    let out: string;
+    try {
+        out = execFileSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=all'], {
+            env: hardenedSpawnEnv(),
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            // Both bounds are the review's: Node's 1 MB default would throw
+            // ENOBUFS on a large working tree, the catch below would return
+            // false, and the state would read `fresh` — a second silent
+            // under-report on a probe that runs at PreToolUse and at every stop.
+            // The timeout bounds the other failure: this probe sits in front of
+            // a tool call, so a hung git must not hold one up.
+            maxBuffer: 32 * 1024 * 1024,
+            timeout: 5_000,
+        });
+    } catch {
+        // Not a repository, or the probe failed: nothing is known, and an
+        // unknown is reported as the state the caller already had.
+        return false;
+    }
+    for (const raw of out.split('\n')) {
+        if (raw.length < 4) continue;
+        // `XY <path>`; a rename or copy is `XY <old> -> <new>`, and the NEW path
+        // is the one on disk. Quotes appear under core.quotepath for non-ASCII.
+        let p = raw.slice(3);
+        const arrow = p.indexOf(' -> ');
+        if (arrow !== -1) p = p.slice(arrow + 4);
+        p = p.trim().replace(/^"|"$/g, '');
+        const dot = p.lastIndexOf('.');
+        if (dot === -1) continue;
+        if (p.slice(dot).toLowerCase() in EXT_LANG) return true;
+    }
+    return false;
+}
 
 /**
  * Resolve the graph's state for `root`.
@@ -206,7 +317,10 @@ export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
  * `absent` means no source at all — the silent case. A picked source whose
  * staleness is UNKNOWN reads as `fresh`, mirroring {@link computeVerdict}'s own
  * `picked.stale ? STALE : FRESH`: unknown is not treated as stale, because
- * inventing a commit count would be worse than reporting none.
+ * inventing a commit count would be worse than reporting none. A source level
+ * with HEAD then reads `edited` instead of `fresh` while the working tree
+ * carries an uncommitted change to an indexable file — see
+ * {@link hasUncommittedIndexedEdit} for why that probe is porcelain, not mtime.
  *
  * `nativeCache` overrides where the native graph is looked for. It exists
  * because a verb invoked with an explicit `--graph <path>` would otherwise
@@ -218,7 +332,13 @@ export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
 export function graphState(root: string, nativeCache?: string): GraphState {
     const picked = pickSource(detectSources(root, nativeCache ?? path.join(root, NATIVE_CACHE_REL)));
     if (!picked) return 'absent';
-    if (picked.stale !== true) return 'fresh';
-    const behind = picked.commits_behind;
-    return `behind:${typeof behind === 'number' ? behind : 0}`;
+    if (picked.stale === true) {
+        const behind = picked.commits_behind;
+        return `behind:${typeof behind === 'number' ? behind : 0}`;
+    }
+    // The commit count comes FIRST and wins: `behind:N` already says the index
+    // predates committed work, and reporting `edited` instead would hide the
+    // larger gap behind the smaller one. Only a graph level with HEAD has an
+    // uncommitted edit as its whole remaining distance.
+    return hasUncommittedIndexedEdit(root) ? 'edited' : 'fresh';
 }

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',