@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -237,6 +237,9 @@
         "properties": {
           "area": {
             "type": "string"
+          },
+          "project": {
+            "type": "string"
           }
         },
         "additionalProperties": false
@@ -247,7 +250,7 @@
     },
     {
       "name": "graph_dead",
-      "description": "Symbols with no accepted reference that no declared entry point names. REFUSES (status `refused`) while a source is unreadable: with no exportedness recorded, an exported-but-unimported symbol is indistinguishable from a dead one. Never a deletion recommendation.",
+      "description": "Symbols no accepted reference and no declared entry point names. REFUSES (status `refused`) while a source is unreadable: without recorded exportedness an exported-but-unimported symbol looks dead. Never a deletion recommendation.",
       "side_effect": "ro",
       "implemented_on": [
         "stdio"
@@ -257,12 +260,46 @@
         "properties": {
           "entry_points": {
             "type": "string",
-            "description": "Path under this root to a newline-separated id/label list; `#` comments ok."
+            "description": "Path under this root: newline-separated ids or labels, `#` comments ok."
           },
           "accept_missing_exports": {
             "type": "boolean",
             "default": false,
             "description": "Answer anyway, accepting the gap. Never a default."
+          },
+          "project": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
+    },
+    {
+      "name": "graph_estate",
+      "description": "Estate index across registered projects: package users, where a name is used, advisory reach. Other graph tools take `project`.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "query"
+        ],
+        "properties": {
+          "query": {
+            "type": "string",
+            "enum": [
+              "where-used",
+              "projects-using",
+              "advisory-impact"
+            ]
+          },
+          "name": {
+            "type": "string"
           }
         },
         "additionalProperties": false
@@ -273,7 +310,7 @@
     },
     {
       "name": "graph_impact",
-      "description": "What a diff can break: callers, dependents and test files reaching the changed symbols. Walks only stated-fact edges, never a same-name guess, and reports the guesses refused. Runs `git diff` for the rev.",
+      "description": "What a diff can break: callers, dependents and test files reaching the changed symbols, over stated-fact edges only (refused guesses reported). Runs `git diff` for the rev.",
       "side_effect": "shell",
       "implemented_on": [
         "stdio"
@@ -298,6 +335,9 @@
             "type": "boolean",
             "default": false,
             "description": "Instead return changed symbols no test imports."
+          },
+          "project": {
+            "type": "string"
           }
         },
         "additionalProperties": false
@@ -315,7 +355,11 @@
       ],
       "input_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "project": {
+            "type": "string"
+          }
+        },
         "additionalProperties": false
       },
       "annotations": {
@@ -324,7 +368,7 @@
     },
     {
       "name": "graph_node",
-      "description": "One symbol in full: where it is declared, what reaches it, what it reaches, and how connected it is. Resolves EXACTLY (node id, then label) and refuses anything it cannot — it never scores free text, so an answer is always about the node you named.",
+      "description": "One symbol in full: where it is declared, what reaches it, what it reaches, how connected it is. Resolves EXACTLY (node id, then label) and refuses anything else — never scores free text.",
       "side_effect": "ro",
       "implemented_on": [
         "stdio"
@@ -347,7 +391,7 @@
               "both"
             ],
             "default": "both",
-            "description": "Which edges to walk. `in` = who reaches it, `out` = what it reaches."
+            "description": "`in` = who reaches it, `out` = what it reaches."
           },
           "depth": {
             "type": "integer",
@@ -375,7 +419,10 @@
               "injects",
               "documents"
             ],
-            "description": "Restrict to one relation. Omit for all of them."
+            "description": "One relation only; omit for all."
+          },
+          "project": {
+            "type": "string"
           }
         },
         "additionalProperties": false
@@ -386,7 +433,7 @@
     },
     {
       "name": "graph_path",
-      "description": "The shortest relation chain between two symbols, direction preserved. Answers \"how does A reach B\" without reading the files between. `(no path found)` when unconnected is an answer.",
+      "description": "The shortest relation chain between two symbols, direction kept: how A reaches B without reading the files between. `(no path found)` is an answer.",
       "side_effect": "ro",
       "implemented_on": [
         "stdio"
@@ -409,8 +456,10 @@
           "budget": {
             "type": "integer",
             "minimum": 1,
-            "default": 1500,
-            "description": "Token budget for lines."
+            "default": 1500
+          },
+          "project": {
+            "type": "string"
           }
         },
         "additionalProperties": false
@@ -421,7 +470,7 @@
     },
     {
       "name": "graph_query",
-      "description": "A symbol's direct outgoing relations — calls, imports, uses, inherits — each line carrying its confidence and resolution mechanism. For \"what does this touch\" before reading a file.",
+      "description": "A symbol's direct outgoing relations (calls, imports, uses, inherits), each with its confidence and resolution mechanism: \"what does this touch\" before reading a file.",
       "side_effect": "ro",
       "implemented_on": [
         "stdio"
@@ -439,8 +488,10 @@
           "budget": {
             "type": "integer",
             "minimum": 1,
-            "default": 1500,
-            "description": "Token budget for lines."
+            "default": 1500
+          },
+          "project": {
+            "type": "string"
           }
         },
         "additionalProperties": false
@@ -451,7 +502,7 @@
     },
     {
       "name": "graph_tests_for",
-      "description": "Which test files exercise a symbol, derived from a test file importing it or its module. Empty means no test imports it — a finding, not an error.",
+      "description": "Test files that exercise a symbol: a test file imports it or its module. Empty means none does — a finding, not an error.",
       "side_effect": "ro",
       "implemented_on": [
         "stdio"
@@ -464,7 +515,10 @@
         "properties": {
           "symbol": {
             "type": "string",
-            "description": "Node id `<relpath>#<sym>`, label, or free text."
+            "description": "Node id, label, or free text."
+          },
+          "project": {
+            "type": "string"
           }
         },
         "additionalProperties": false

package/src/scripts/mcp_server/graph_tools.ts

@@ -42,7 +42,14 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { changedFiles } from '../code_graph/cli.js';
-import { detectSources, graphState, NATIVE_CACHE_REL, pickSource } from '../code_graph/detect.js';
+import { detectSources, graphState, pickSource } from '../code_graph/detect.js';
+import { graphHome } from '../code_graph/graph_home.js';
+import { advisoryImpact, whereUsed } from '../code_graph/estate_cli.js';
+import { openEstate } from '../code_graph/estate_index.js';
+import { touchHome } from '../code_graph/graph_budget.js';
+import { resolveProjectRef } from '../code_graph/project_ref.js';
+import { repoIdentity } from '../code_graph/repo_identity.js';
+import { readRegistry, repoIdOf } from '../_lib/project_registry.js';
 import { resolvePath } from './path_util.js';
 import { isTestFile } from '../code_graph/build.js';
 import {
@@ -65,8 +72,49 @@ import {
 import { areaReport, graphGeneration, readMap } from '../code_graph/map.js';
 import type { BuiltinTool } from './tools.js';
 
-/** The `no graph here` answer, in one place so all five agree on its shape. */
+/**
+ * Registered projects whose graph exists, for a root that has none (5.2). Read
+ * from the local registry only; the graph files themselves are not opened.
+ *
+ * Any MCP caller can reach this answer, so it never names another repository's
+ * path: only another checkout of the server root's own repository is listed
+ * with its root, and other projects appear — by id and name — only while the
+ * owner has switched the estate index on (O1).
+ */
+function projectsWithGraph(root: string): Array<{ id: string; name: string; root?: string }> {
+    const reg = readRegistry();
+    const self = repoIdentity(root).repoId;
+    let real: string;
+    try {
+        real = fs.realpathSync(root);
+    } catch {
+        real = path.resolve(root);
+    }
+    const out: Array<{ id: string; name: string; root?: string }> = [];
+    for (const [id, e] of Object.entries(reg.projects)) {
+        const same = repoIdOf(id) === self;
+        if (!same && !reg.index) continue;
+        if (e.root === real || !fs.existsSync(e.root) || !fs.existsSync(graphHome(e.root).cachePath)) continue;
+        out.push(same ? { id, name: path.basename(e.root), root: e.root } : { id, name: path.basename(e.root) });
+        if (out.length === 20) break;
+    }
+    return out;
+}
+
+/** The `no graph here` answer, in one place so all the tools agree on its shape. */
 function noGraph(root: string): Record<string, unknown> {
+    const registered = projectsWithGraph(root);
+    if (registered.length) {
+        return {
+            status: 'unavailable',
+            staleness: 'absent',
+            error:
+                'no code-graph source under this root — pass `project` to ask a registered project below, ' +
+                'or run `agent-config code-graph build` here',
+            root,
+            registered_projects: registered,
+        };
+    }
     return {
         status: 'unavailable',
         staleness: 'absent',
@@ -88,9 +136,10 @@ function withGraph<T extends Record<string, unknown>>(
     root: string,
     fn: (g: LoadedGraph) => T,
 ): Record<string, unknown> {
-    const picked = pickSource(detectSources(root, path.join(root, NATIVE_CACHE_REL)));
+    const picked = pickSource(detectSources(root, graphHome(root).cachePath));
     if (!picked || picked.kind === 'scip') return noGraph(root);
-    const g = loadGraph(picked.path, `${picked.kind}:${path.relative(root, picked.path)}`);
+    touchHome(root);
+    const g = loadGraph(picked.path, `${picked.kind}:${shown(root, picked.path)}`);
     try {
         const out = fn(g);
         // `status` is DERIVED from the answer, never prefixed onto it. An
@@ -107,6 +156,12 @@ function withGraph<T extends Record<string, unknown>>(
     }
 }
 
+/** Relative inside the root, absolute for a graph home outside it (ADR-299). */
+function shown(root: string, p: string): string {
+    const rel = path.relative(root, p);
+    return rel.startsWith('..') || path.isAbsolute(rel) ? p : rel;
+}
+
 function str(args: Record<string, unknown>, key: string): string {
     const v = args[key];
     return typeof v === 'string' ? v.trim() : '';
@@ -143,14 +198,49 @@ function num(args: Record<string, unknown>, key: string, dflt: number): number {
     return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : dflt;
 }
 
-export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
+/**
+ * Every graph tool takes an optional `project` (5.1): a registered repo id,
+ * name or path, resolved through the registry and its graph home. Without it
+ * the tool answers about the server root, exactly as before.
+ */
+function withProjectParam(tools: Record<string, BuiltinTool>): Record<string, BuiltinTool> {
+    const out: Record<string, BuiltinTool> = {};
+    for (const [name, t] of Object.entries(tools)) {
+        // The estate tool answers across every project already.
+        if (name === 'graph_estate') {
+            out[name] = t;
+            continue;
+        }
+        const schema = t.input_schema as { properties?: Record<string, unknown> };
+        out[name] = {
+            ...t,
+            input_schema: {
+                ...t.input_schema,
+                properties: {
+                    ...(schema.properties ?? {}),
+                    project: { type: 'string' },
+                },
+            },
+            handler: async (args, root) => {
+                const ref = str(args, 'project');
+                if (ref === '') return t.handler(args, root);
+                const r = resolveProjectRef(ref);
+                if ('error' in r) return { status: 'error', error: r.error, candidates: r.candidates };
+                return t.handler(args, r.root);
+            },
+        };
+    }
+    return out;
+}
+
+export const GRAPH_TOOLS: Record<string, BuiltinTool> = withProjectParam({
     graph_impact: {
         name: 'graph_impact',
         side_effect: 'shell',
         description:
             'What a diff can break: callers, dependents and test files reaching the ' +
-            'changed symbols. Walks only stated-fact edges, never a same-name guess, ' +
-            'and reports the guesses refused. Runs `git diff` for the rev.',
+            'changed symbols, over stated-fact edges only (refused guesses reported). ' +
+            'Runs `git diff` for the rev.',
         input_schema: {
             type: 'object',
             required: ['diff'],
@@ -170,7 +260,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             if (rev === '') return { status: 'error', error: 'diff must be a non-empty git rev' };
             const files = changedFiles(root, rev);
             if (files === null) return { status: 'error', error: `cannot resolve rev '${rev}' in ${root}` };
-            const state = graphState(root);
+            const state = graphState(root, graphHome(root).cachePath);
             return withGraph(root, (g) =>
                 args['untested_only'] === true
                     ? { ...untested(g, files, state), changed_files: files.length }
@@ -183,20 +273,20 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_tests_for',
         side_effect: 'ro',
         description:
-            'Which test files exercise a symbol, derived from a test file importing ' +
-            'it or its module. Empty means no test imports it — a finding, not an error.',
+            'Test files that exercise a symbol: a test file imports it or its module. ' +
+            'Empty means none does — a finding, not an error.',
         input_schema: {
             type: 'object',
             required: ['symbol'],
             properties: {
-                symbol: { type: 'string', description: 'Node id `<relpath>#<sym>`, label, or free text.' },
+                symbol: { type: 'string', description: 'Node id, label, or free text.' },
             },
             additionalProperties: false,
         },
         handler: async (args, root) => {
             const symbol = str(args, 'symbol');
             if (symbol === '') return { status: 'error', error: 'symbol must be a non-empty string' };
-            const state = graphState(root);
+            const state = graphState(root, graphHome(root).cachePath);
             return withGraph(root, (g) => ({ ...testsFor(g, symbol, state) }));
         },
     },
@@ -205,16 +295,15 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_dead',
         side_effect: 'ro',
         description:
-            'Symbols with no accepted reference that no declared entry point names. ' +
-            'REFUSES (status `refused`) while a source is unreadable: with no ' +
-            'exportedness recorded, an exported-but-unimported symbol is ' +
-            'indistinguishable from a dead one. Never a deletion recommendation.',
+            'Symbols no accepted reference and no declared entry point names. REFUSES ' +
+            '(status `refused`) while a source is unreadable: without recorded exportedness ' +
+            'an exported-but-unimported symbol looks dead. Never a deletion recommendation.',
         input_schema: {
             type: 'object',
             properties: {
                 entry_points: {
                     type: 'string',
-                    description: 'Path under this root to a newline-separated id/label list; `#` comments ok.',
+                    description: 'Path under this root: newline-separated ids or labels, `#` comments ok.',
                 },
                 accept_missing_exports: {
                     type: 'boolean',
@@ -225,7 +314,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             additionalProperties: false,
         },
         handler: async (args, root) => {
-            const state = graphState(root);
+            const state = graphState(root, graphHome(root).cachePath);
             const listArg = str(args, 'entry_points');
             let sources = repoEntryPoints(root);
             if (listArg !== '') {
@@ -281,22 +370,21 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_query',
         side_effect: 'ro',
         description:
-            "A symbol's direct outgoing relations — calls, imports, uses, inherits — " +
-            'each line carrying its confidence and resolution mechanism. For "what ' +
-            'does this touch" before reading a file.',
+            "A symbol's direct outgoing relations (calls, imports, uses, inherits), each " +
+            'with its confidence and resolution mechanism: "what does this touch" before reading a file.',
         input_schema: {
             type: 'object',
             required: ['symbol'],
             properties: {
                 symbol: { type: 'string', description: 'Node id, label, or free text.' },
-                budget: { type: 'integer', minimum: 1, default: 1500, description: 'Token budget for lines.' },
+                budget: { type: 'integer', minimum: 1, default: 1500 },
             },
             additionalProperties: false,
         },
         handler: async (args, root) => {
             const symbol = str(args, 'symbol');
             if (symbol === '') return { status: 'error', error: 'symbol must be a non-empty string' };
-            const staleness = graphState(root);
+            const staleness = graphState(root, graphHome(root).cachePath);
             return withGraph(root, (g) => ({
                 staleness,
                 ...graphQueryVerb(g, symbol, num(args, 'budget', 1500)),
@@ -308,10 +396,9 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_node',
         side_effect: 'ro',
         description:
-            'One symbol in full: where it is declared, what reaches it, what it ' +
-            'reaches, and how connected it is. Resolves EXACTLY (node id, then ' +
-            'label) and refuses anything it cannot — it never scores free text, ' +
-            'so an answer is always about the node you named.',
+            'One symbol in full: where it is declared, what reaches it, what it reaches, ' +
+            'how connected it is. Resolves EXACTLY (node id, then label) and refuses ' +
+            'anything else — never scores free text.',
         input_schema: {
             type: 'object',
             required: ['id'],
@@ -321,13 +408,13 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
                     type: 'string',
                     enum: ['in', 'out', 'both'],
                     default: 'both',
-                    description: 'Which edges to walk. `in` = who reaches it, `out` = what it reaches.',
+                    description: '`in` = who reaches it, `out` = what it reaches.',
                 },
                 depth: { type: 'integer', minimum: 1, maximum: 3, default: 1, description: 'Hop limit.' },
                 relation: {
                     type: 'string',
                     enum: RELATIONS,
-                    description: 'Restrict to one relation. Omit for all of them.',
+                    description: 'One relation only; omit for all.',
                 },
             },
             additionalProperties: false,
@@ -335,7 +422,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         handler: async (args, root) => {
             const id = str(args, 'id');
             if (id === '') return { status: 'error', error: 'id must be a non-empty string' };
-            const staleness = graphState(root);
+            const staleness = graphState(root, graphHome(root).cachePath);
             const opts: NodeOptions = {};
             const dir = str(args, 'direction');
             if (dir === 'in' || dir === 'out' || dir === 'both') opts.direction = dir;
@@ -353,16 +440,15 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         name: 'graph_path',
         side_effect: 'ro',
         description:
-            'The shortest relation chain between two symbols, direction preserved. ' +
-            'Answers "how does A reach B" without reading the files between. ' +
-            '`(no path found)` when unconnected is an answer.',
+            'The shortest relation chain between two symbols, direction kept: how A reaches ' +
+            'B without reading the files between. `(no path found)` is an answer.',
         input_schema: {
             type: 'object',
             required: ['from', 'to'],
             properties: {
                 from: { type: 'string', description: 'Start node id, label, or free text.' },
                 to: { type: 'string', description: 'Goal node id, label, or free text.' },
-                budget: { type: 'integer', minimum: 1, default: 1500, description: 'Token budget for lines.' },
+                budget: { type: 'integer', minimum: 1, default: 1500 },
             },
             additionalProperties: false,
         },
@@ -370,7 +456,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             const from = str(args, 'from');
             const to = str(args, 'to');
             if (from === '' || to === '') return { status: 'error', error: 'from and to must be non-empty strings' };
-            const staleness = graphState(root);
+            const staleness = graphState(root, graphHome(root).cachePath);
             return withGraph(root, (g) => ({
                 staleness,
                 ...graphPathVerb(g, from, to, num(args, 'budget', 1500)),
@@ -383,7 +469,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
         description: 'Is there a code map (agents/map/)? Its freshness, counts and MAP.md path.',
         input_schema: { type: 'object', properties: {}, additionalProperties: false },
         handler: async (_args, root) => {
-            const staleness = graphState(root);
+            const staleness = graphState(root, graphHome(root).cachePath);
             const map = readMap(root);
             if (!map) {
                 return {
@@ -394,6 +480,8 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
                 };
             }
             const m = map.model;
+            const home = graphHome(root);
+            const mapRel = home.kind === 'project' ? 'agents/map' : home.mapDir;
             return {
                 status: 'ok',
                 staleness,
@@ -401,7 +489,7 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
                 drawn_at_commit: map.meta.commit,
                 graph_state_when_drawn: map.meta.state,
                 // Same generation → the map shows exactly the graph the queries read.
-                map_matches_graph: map.meta.graph_generation !== undefined && map.meta.graph_generation === graphGeneration(path.join(root, NATIVE_CACHE_REL)),
+                map_matches_graph: map.meta.graph_generation !== undefined && map.meta.graph_generation === graphGeneration(home.cachePath),
                 files: m.files.length,
                 areas: m.areas.length,
                 trusted_links: m.analyses.trustedEdges,
@@ -409,8 +497,8 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
                 request_paths: m.analyses.requestPathsTotal,
                 providers: (m.providers ?? []).map((p) => `${p.id} (${p.status})`),
                 largest_areas: m.areas.slice(0, 5).map((a) => `${a.id} ${a.name} (${a.files.length})`),
-                map_md: 'agents/map/MAP.md',
-                index_html: 'agents/map/index.html',
+                map_md: `${mapRel}/MAP.md`,
+                index_html: `${mapRel}/index.html`,
             };
         },
     },
@@ -431,9 +519,41 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             if (q === '') return { status: 'error', error: 'area must be a non-empty string' };
             const map = readMap(root);
             if (!map) return { status: 'unavailable', error: 'no map — run `agent-config code-graph map`' };
-            const r = areaReport(map.model, q);
+            const home = graphHome(root);
+            const r = areaReport(map.model, q, home.kind === 'project' ? undefined : home.mapDir);
             if ('refusal' in r) return { status: 'refused', refusal: r.refusal, candidates: r.candidates };
             return { status: 'ok', drawn_at_commit: map.meta.commit, ...r };
         },
     },
-};
+    graph_estate: {
+        name: 'graph_estate',
+        side_effect: 'ro',
+        description:
+            'Estate index across registered projects: package users, where a name is used, advisory ' +
+            'reach. Other graph tools take `project`.',
+        input_schema: {
+            type: 'object',
+            required: ['query'],
+            properties: {
+                query: { type: 'string', enum: ['where-used', 'projects-using', 'advisory-impact'] },
+                name: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        handler: async (args) => {
+            const q = str(args, 'query');
+            const name = str(args, 'name');
+            if (q !== 'advisory-impact' && name === '') return { status: 'error', error: `${q || 'query'} needs a name` };
+            const db = openEstate();
+            if (!db) return { status: 'unavailable', error: 'no estate index — `agent-config code-graph projects index on`, then refresh each project' };
+            try {
+                if (q === 'projects-using') return { status: 'ok', projects: db.projectsUsing(name) };
+                if (q === 'where-used') return { status: 'ok', ...whereUsed(db, name) };
+                if (q === 'advisory-impact') return { status: 'ok', impact: advisoryImpact(db, name === '' ? null : name) };
+                return { status: 'error', error: `unknown query: ${q}` };
+            } finally {
+                db.close();
+            }
+        },
+    },
+});

package/src/scripts/network_sources.ts

@@ -24,6 +24,7 @@ import { isIP } from 'node:net';
 import * as path from 'node:path';
 
 import { encrypt } from './_lib/link_crypto.js';
+import { sourceId } from './_lib/source_id.js';
 import { sanitize_text } from './_lib/retrieval_sanitize.js';
 import { SourceError, resolveSource, type SourceRef } from './source_adapters.js';
 
@@ -207,26 +208,43 @@ export function quotedAnchor(text: string, needle: string): { line: number; quot
     return { line: i + 1, quote: words.slice(start, start + MAX_QUOTE_WORDS).join(' ') };
 }
 
-/** Codes source identities S1, S2, …; the identities leave only as ENC1 tokens in the round's intake.md. */
+/**
+ * Codes source identities; the identities leave only as ENC1 tokens in the round's intake.md.
+ * With an id key the codes are stable `src_…` ids (`_lib/source_id.ts`), equal across rounds;
+ * without one they are `S1, S2, …`, meaningful inside this round only.
+ */
 export class SourceCodebook {
     private readonly ids: string[] = [];
+    private readonly codes: string[] = [];
     private readonly tokens: string[] = [];
+    private readonly idKey: string | null;
 
-    constructor(private readonly key: string) {}
+    constructor(
+        private readonly key: string,
+        opts: { idKey?: string | null } = {},
+    ) {
+        this.idKey = opts.idKey ? opts.idKey : null;
+    }
 
     code(identity: string): string {
-        let i = this.ids.indexOf(identity);
+        const stable = this.idKey === null ? null : sourceId(identity, this.idKey);
+        let i = stable === null ? this.ids.indexOf(identity) : this.codes.indexOf(stable);
         if (i === -1) {
             this.ids.push(identity);
+            this.codes.push(stable ?? `S${String(this.ids.length)}`);
             this.tokens.push(encrypt(identity, this.key));
             i = this.ids.length - 1;
         }
-        return `S${String(i + 1)}`;
+        return this.codes[i] as string;
     }
 
     intakeMarkdown(): string {
-        const rows = this.tokens.map((token, i) => `- S${String(i + 1)}: ${token}`);
-        return ['# Sources', '', 'Identities are encrypted (`link_crypto`); tracked output names only the codes.', '', ...rows, ''].join('\n');
+        const rows = this.tokens.map((token, i) => `- ${this.codes[i] as string}: ${token}`);
+        const scope =
+            this.idKey === null
+                ? 'Codes are per-round (S1, S2, …) — no id key was available, so they do not match another round.'
+                : 'Codes are stable source ids (src_…), equal across rounds.';
+        return ['# Sources', '', 'Identities are encrypted (`link_crypto`); tracked output names only the codes.', scope, '', ...rows, ''].join('\n');
     }
 
     writeIntake(roundDir: string): void {