projectkeeper 0.0.0-stage → 1.0.0

package/src/cli.ts

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+/**
+ * pk — ProjectKeeper command line. The same command is also installed under its long name, `projectkeeper`.
+ *
+ *   pk serve [--port N]                 start the workbench at http://127.0.0.1:N
+ *   pk add <name> <location> [...]      add a project (nothing runs until Start on its Takeover page)
+ *   pk scope <projectId>                print the scope list
+ *   pk projects                         list projects
+ *   pk check [table] [--project <dir>] [--sessions <file>]
+ *                                       check a filled ProjectKeeper table (default projectkeeper/project.json here)
+ *                                       against template/projectkeeper.schema.json and the project's own files; prints
+ *                                       every problem and exits 1 when there is any. Needs no workbench.
+ *   pk import [table] [--home <dir>] [--name <name>] [--project <dir>] [--sessions <file>]
+ *                                       check the table the same way and, when it holds, take it into the home: the
+ *                                       project (the folder holding projectkeeper/, or --project) is found or added and
+ *                                       read, and the Keeper's picture of it is replaced by the table's. A table with any
+ *                                       problem is refused and nothing is written. Prints what it wrote.
+ *   pk sessions [--project <dir>] [--home <dir>] [--name <name>] [--out <dir>]
+ *                                       write the session material a table quotes the owner from: every owner message of
+ *                                       the project's agent sessions (default: the current directory), each after the
+ *                                       agent's answer it replies to, as session-material.md and .jsonl. They go into
+ *                                       ProjectKeeper's own folder for the project (<home>/projects/<id>/table), never
+ *                                       into the project; an --out inside it is refused (D107).
+ *   pk check --owner-part <file> --sessions <file>
+ *                                       check the owner part a takeover's first step writes ({ ownerWants, notes })
+ *                                       against the schema and the session material it quotes.
+ *   pk takeover [--project <dir>] [--home <dir>] [--name <name>] [--table-in home|project] --prepare
+ *                                       lay out a takeover by the table in three isolated folders under
+ *                                       <home>/projects/<id>/table/takeover-<time>/: owner/ (the session material),
+ *                                       project-reader/ (a copy of the project), and the main agent's instructions at
+ *                                       the top; prints each step's folder and instructions and the pk import command.
+ *                                       Any agent can run the steps; Claude Code users run them in their own Claude Code.
+ *   pk takeover ... --run codex [--model <m>] [--effort <e>]
+ *                                       also run the three steps headless with Codex CLI (routes 1 and 2 at once, then
+ *                                       the main agent; Codex's default model unless --model, effort high unless
+ *                                       --effort), check the merged table and, when it holds, put it at its destination
+ *                                       and take it in. --table-in home (default, safe for a public project) keeps the
+ *                                       table at <home>/projects/<id>/table/project.json; a private project may use
+ *                                       --table-in project (projectkeeper/project.json in the project). There is no
+ *                                       --run claude: running a Claude subscription from another tool is against
+ *                                       Anthropic's terms.
+ *
+ * An execution agent's own entry (Spec §7.10), all talking to the running workbench:
+ *   pk context [--work <id|name>] [--purpose Start|Work] [--kind K] [--recipient R] [--since T]
+ *   pk get <id>                         whatever an id in a pack names: a pack, an original (a code file: where it is
+ *                                       and the version read), a note, a project rule, or the object itself in full
+ *                                       with its neighbours named by id
+ *   pk options                          areas, work items, lit breakpoints, open send-backs, six things and context choices
+ *   pk ask "<question>"                 ask the Keeper
+ *   pk help                             how to use these
+ * The project is --project <id>, or the one containing --cwd <dir> (default: the current directory).
+ *
+ *   pk mcp [--port N] [--project <id>] [--cwd <dir>]
+ *                                       the same reading commands and the table check as a local MCP server on stdin and
+ *                                       stdout, for clients that take their tools over MCP (D108; src/mcp/server.ts).
+ *                                       The flags are the tools' defaults; a tool call can name its own.
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import process from 'node:process';
+import { App } from './server/app.ts';
+import { HttpApp } from './server/http.ts';
+import { registerRoutes } from './server/api.ts';
+import { vendorDir } from './server/vendor.ts';
+import { WorkspaceFileError } from './store/workspace.ts';
+import { gitNotice, gitVersionOutput } from './util/git-check.ts';
+import { checkOwnerPartFile, checkTableFile, readSessionMaterial, tableCheckReport, type TableProblem } from './table/check.ts';
+import { importTable } from './table/import.ts';
+import { exportProjectSessions } from './table/sessions.ts';
+import { prepareTakeover, runTakeover, type PreparedTakeover, type TableIn } from './table/takeover.ts';
+import { agentEntry, askEntry, Exit, type EntryOutput, type EntryTarget } from './context/agent-entry.ts';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const appRoot = resolve(here, '..');
+
+function arg(flag: string, fallback: string | null = null): string | null {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1]! : fallback;
+}
+
+/** The table file a table command names (default projectkeeper/project.json here), past the flags that take a value. */
+function tableArg(): string {
+  const given = process.argv.slice(3).find((a, i, all) => !a.startsWith('--') && !(i > 0 && ['--project', '--sessions', '--home', '--name'].includes(all[i - 1]!)));
+  return resolve(given ?? join('projectkeeper', 'project.json'));
+}
+
+function printProblems(tableFile: string, problems: readonly TableProblem[]): void {
+  for (const line of tableCheckReport(tableFile, problems)) console.log(line);
+}
+
+/** `pk check`: the table, its project folder and the session material it cites; no workbench, no store. */
+function checkCommand(): number {
+  const projectDir = arg('--project');
+  const sessionsFile = arg('--sessions');
+  // The owner part a takeover's first step writes, held to the session material it is read from (D107).
+  const ownerPart = arg('--owner-part');
+  if (ownerPart) {
+    if (!sessionsFile) { console.error('usage: pk check --owner-part <file> --sessions <session-material.jsonl>'); return 2; }
+    const file = resolve(ownerPart);
+    const problems = checkOwnerPartFile(file, readSessionMaterial(resolve(sessionsFile)));
+    if (!problems.length) { console.log(`${file}: no problems.`); return 0; }
+    console.log(`${file}: ${problems.length} problem${problems.length === 1 ? '' : 's'}.`);
+    for (const p of problems) console.log(`  ${p.at}  ${p.problem}`);
+    return 1;
+  }
+  const tableFile = tableArg();
+  const problems = checkTableFile(tableFile, {
+    projectDir: projectDir ? resolve(projectDir) : undefined,
+    sessions: sessionsFile ? readSessionMaterial(resolve(sessionsFile)) : null,
+  });
+  printProblems(tableFile, problems);
+  return problems.length ? 1 : 0;
+}
+
+/** `pk import`: the same check, then the table taken into the home (src/table/import.ts). */
+async function importCommand(): Promise<number> {
+  const tableFile = tableArg();
+  const projectDir = arg('--project');
+  const sessionsFile = arg('--sessions');
+  const r = await importTable({
+    tableFile, projectDir: projectDir ? resolve(projectDir) : undefined, home: arg('--home') ?? undefined, name: arg('--name') ?? undefined,
+    sessions: sessionsFile ? readSessionMaterial(resolve(sessionsFile)) : null,
+  });
+  if (r.problems.length) { printProblems(tableFile, r.problems); return 1; }
+  const c = r.counts!;
+  const list = (counts: Readonly<Record<string, number>>) => Object.entries(counts).map(([k, n]) => `${n} ${k}`).join(', ') || 'nothing';
+  console.log(`${tableFile}: taken into ${r.added ? 'the new project' : 'project'} ${r.projectName} (${r.projectId}) in ${r.home}.`);
+  console.log(`  Replaced the earlier picture: ${list(c.removed)}`);
+  console.log(`  Sources cited: ${c.sources.cited} (${c.sources.reused} as intake read them, ${c.sources.written} written from the table)`);
+  console.log(`  Reference items: ${list(c.reference)}`);
+  console.log(`  Work items: ${c.threads} (with ${c.facts} fact records), relations written: ${c.relations}, earlier generations: ${c.generations}, process links: ${c.links}`);
+  console.log(`  Code territories: ${c.territories}, notes: ${c.notes}`);
+  console.log(`  Graph: ${c.graph.nodes} nodes, ${c.graph.relations} relations`);
+  for (const w of r.warnings ?? []) console.warn(`  ${w}`);
+  return 0;
+}
+
+/** `pk sessions`: the session material of a project, written outside it (src/table/sessions.ts, D107). */
+async function sessionsCommand(): Promise<number> {
+  const out = arg('--out');
+  let r: Awaited<ReturnType<typeof exportProjectSessions>>;
+  try {
+    r = await exportProjectSessions({ projectDir: resolve(arg('--project') ?? process.cwd()), home: arg('--home') ?? undefined, name: arg('--name') ?? undefined, out: out ?? undefined });
+  } catch (e) { console.error((e as Error).message); return 2; }
+  console.log(`Session material of ${r.added ? 'the new project' : 'project'} ${r.projectName} (${r.projectId}) in ${r.home}:`);
+  console.log(`  ${r.ownerMessages} owner message${r.ownerMessages === 1 ? '' : 's'} from ${r.sessions} session${r.sessions === 1 ? '' : 's'}, ${r.records} records with the agent answers before them`);
+  console.log(`  ${r.markdown}`);
+  console.log(`  ${r.jsonl}   (pk check / pk import --sessions)`);
+  for (const w of r.warnings) console.warn(`  ${w}`);
+  return 0;
+}
+
+const TAKEOVER_USAGE = 'usage: pk takeover [--project <dir>] [--home <dir>] [--name <name>] [--table-in home|project] (--prepare | --run codex [--model <m>] [--effort <e>])';
+
+function printSteps(t: PreparedTakeover): void {
+  console.log(`Takeover of ${t.added ? 'the new project' : 'project'} ${t.projectName} (${t.projectId}), laid out in ${t.workDir}`);
+  console.log(`  Session material: ${t.ownerMessages} owner message${t.ownerMessages === 1 ? '' : 's'} from ${t.sessions} session${t.sessions === 1 ? '' : 's'}`);
+  console.log(`  Project copy: ${t.repos.map((r) => `${r.path} at ${r.commit}`).join(', ')}${t.skipped.length ? `; ${t.skipped.length} entr${t.skipped.length === 1 ? 'y' : 'ies'} left out (ignored by git, node_modules, links)` : ''}`);
+  for (const w of t.warnings) console.warn(`  ${w}`);
+  const { owner, reader, main } = t.steps;
+  console.log('\nStep 1 — the owner\'s words (run at the same time as step 2; each agent sees only its own folder):');
+  console.log(`  folder:       ${owner.folder}\n  instructions: ${owner.instructions}\n  writes:       ${owner.output}`);
+  console.log('Step 2 — the project:');
+  console.log(`  folder:       ${reader.folder}\n  instructions: ${reader.instructions}\n  writes:       ${reader.output}`);
+  console.log('Step 3 — the main agent, after both:');
+  console.log(`  folder:       ${main.folder}\n  instructions: ${main.instructions}\n  writes:       ${main.output}`);
+  console.log(`Then put ${main.output} at ${t.destination} and take it in:\n  ${t.importCommand}`);
+}
+
+/**
+ * `pk takeover`: the three-step takeover by the table (src/table/takeover.ts, D107). `--prepare` lays out the folders
+ * for any agent; `--run codex` also runs the steps headless with Codex CLI and takes the table in. PK_TAKEOVER_AGENT
+ * names a program to run instead of `codex` (a .mjs, .js or .ts file runs under this node), for tests and stand-ins.
+ */
+async function takeoverCommand(): Promise<number> {
+  const run = arg('--run');
+  const prepare = process.argv.includes('--prepare');
+  const tableIn = arg('--table-in', 'home');
+  if (run === 'claude') {
+    console.error('pk takeover does not run Claude Code: running a Claude subscription from another tool is against Anthropic\'s terms. Run pk takeover --prepare and give the three steps to your own Claude Code, each in its folder.');
+    return 2;
+  }
+  if ((run !== null && run !== 'codex') || (run === null && !prepare) || (tableIn !== 'home' && tableIn !== 'project')) { console.error(TAKEOVER_USAGE); return 2; }
+  const options = { projectDir: resolve(arg('--project') ?? process.cwd()), home: arg('--home') ?? undefined, name: arg('--name') ?? undefined, tableIn: tableIn as TableIn };
+  if (!run) {
+    let t: PreparedTakeover;
+    try { t = await prepareTakeover(options); } catch (e) { console.error((e as Error).message); return 2; }
+    printSteps(t);
+    return 0;
+  }
+  const standIn = process.env.PK_TAKEOVER_AGENT?.trim();
+  const agentCommand = standIn ? (/\.(m?js|ts)$/i.test(standIn) ? [process.execPath, resolve(standIn)] : [standIn]) : undefined;
+  let r: Awaited<ReturnType<typeof runTakeover>>;
+  try {
+    r = await runTakeover({ ...options, model: arg('--model') ?? undefined, effort: arg('--effort') ?? undefined, agentCommand, log: (line) => console.log(line) });
+  } catch (e) { console.error((e as Error).message); return 2; }
+  const t = r.prepared;
+  console.log(`\nWork folder: ${t.workDir} (each step's events, stderr, times and last message under runs/)`);
+  for (const s of r.runs) if (s.lastMessage) console.log(`\n${s.step}, last message:\n${s.lastMessage.trim()}`);
+  if (r.stopped) {
+    console.log(`\nStopped after ${r.stopped.after}: ${r.stopped.why}. Nothing was taken in.`);
+    if (r.problems.length) printProblems(t.steps.main.output, r.problems);
+    console.log(`Once ${t.steps.main.output} checks clean, put it at ${t.destination} and take it in:\n  ${t.importCommand}`);
+    return 1;
+  }
+  console.log(`\nTaken in from ${t.destination}${r.previousTable ? ` (the table that stood there is kept as ${r.previousTable})` : ''}: ${r.imported!.counts!.graph.nodes} nodes in the graph.`);
+  for (const w of r.imported!.warnings ?? []) console.warn(`  ${w}`);
+  return 0;
+}
+
+/**
+ * `pk mcp` (D108): an MCP server on stdin and stdout until the client closes stdin. Stdout carries the protocol and
+ * nothing else, so anything that would be printed there while it runs goes to stderr instead.
+ */
+async function mcpCommand(): Promise<number> {
+  const toStderr = (...parts: unknown[]) => console.error(...parts);
+  console.log = toStderr; console.info = toStderr; console.debug = toStderr;
+  const { serveMcp } = await import('./mcp/server.ts');
+  await serveMcp(process.stdin, process.stdout, { port: arg('--port'), project: arg('--project'), cwd: resolve(arg('--cwd') ?? process.cwd()), home: arg('--home') ?? undefined });
+  return 0;
+}
+
+async function main(): Promise<number> {
+  const command = process.argv[2] ?? 'serve';
+  if (command === 'mcp') return mcpCommand();
+  if (command === 'check') return checkCommand();
+  if (command === 'takeover') return takeoverCommand();
+  // The import opens its home itself, and only for a table that holds.
+  if (command === 'import') return importCommand();
+  if (command === 'sessions') return sessionsCommand();
+  const app = new App(arg('--home') ?? undefined);
+  const VALUE_FLAGS = ['--home', '--port', '--project', '--cwd', '--thread', '--fetch', '--work', '--purpose', '--kind', '--recipient', '--since'];
+  const positionals = () => process.argv.slice(3).filter((a, i, all) => !a.startsWith('--') && !(i > 0 && VALUE_FLAGS.includes(all[i - 1]!)));
+  if (command === 'serve') {
+    const http = new HttpApp();
+    registerRoutes(http, app, join(appRoot, 'ui'), vendorDir(appRoot));
+    http.route('GET', '/api/events', ({ res }) => { http.sse.attach(res); });
+    app.on('event', (event) => http.sse.broadcast('app', event));
+    const port = Number(arg('--port', String(app.workspace.settings.port)));
+    app.servedPort = port;
+    await app.initKeeper({ fakeProvider: process.argv.includes('--fake-provider') });
+    if (app.workspace.settings.watchProjects === false) console.log('Not watching the projects (settings.watchProjects is false): this home works through what it already holds.');
+    // A project the owner has not started is not watched: before `Start` nothing counts as waiting (D105).
+    else for (const p of app.workspace.list()) { try { if (p.lastScopedAt) app.startWatching(p.id); } catch (e) { console.warn(`[watch] ${p.id}: ${(e as Error).message}`); } }
+    const server = await http.listen(port);
+    console.log(`ProjectKeeper workbench: http://127.0.0.1:${server.port}/`);
+    // Without git a repository is read as a folder of files and nothing says why (a new Mac has no git until the
+    // command line tools are installed): said here, once.
+    const aboutGit = gitNotice(gitVersionOutput());
+    if (aboutGit) console.warn(`\n${aboutGit}\n`);
+    const stop = async () => { app.stopAll(); await app.flushAll(); await server.close(); process.exit(0); };
+    process.on('SIGINT', () => { void stop(); });
+    process.on('SIGTERM', () => { void stop(); });
+    // Closing the terminal window sends this one: stopped the same way, so what was being written is written.
+    process.on('SIGHUP', () => { void stop(); });
+    return new Promise(() => { /* keep running */ });
+  }
+  if (command === 'add') {
+    const [name, ...locations] = positionals();
+    if (!name || locations.length === 0) { console.error('usage: pk add <name> <location> [...]'); return 2; }
+    const project = app.addProject(name, locations);
+    await app.flushAll();
+    console.log(JSON.stringify({ id: project.id, name: project.name, state: 'Not organized yet', next: 'Open the workbench: Keeper → Takeover → choose a depth → Start' }, null, 2));
+    return 0;
+  }
+  if (command === 'intake') {
+    const id = positionals()[0];
+    if (!id) { console.error('usage: pk intake <projectId>'); return 2; }
+    const result = await app.intakeProject(id);
+    await app.flushAll();
+    console.log(JSON.stringify(result, null, 2));
+    app.stopAll();
+    return 0;
+  }
+  if (command === 'scope') {
+    const id = positionals()[0];
+    if (!id) { console.error('usage: pk scope <projectId>'); return 2; }
+    const project = app.project(id);
+    for (const item of project.scope) {
+      console.log(`${item.category.padEnd(14)} ${item.relation.padEnd(24)} ${item.path}\n${' '.repeat(39)}${item.reason}`);
+    }
+    if (project.scopeQuestions.length) console.log('\nQuestions:\n' + project.scopeQuestions.map((q) => `- ${q.question}${q.answer ? ` → ${q.answer.text}` : ''}`).join('\n'));
+    return 0;
+  }
+  if (command === 'ask') {
+    // Query entry without any host integration (§7.6): talks to the running workbench (src/context/agent-entry.ts).
+    const portFlag = arg('--port') ? ` --port ${arg('--port')}` : '';
+    const positional = process.argv.slice(3).filter((a, i, all) => !a.startsWith('--') && !(i > 0 && all[i - 1]!.startsWith('--') && ['--project', '--cwd', '--thread', '--port', '--home', '--fetch'].includes(all[i - 1]!)));
+    return askEntry(entryTarget(app), console_, {
+      question: positional.join(' '), fetch: arg('--fetch'), thread: arg('--thread'), wait: process.argv.includes('--wait'),
+      fetchLater: (projectId, jobId) => `pk ask --project ${projectId}${portFlag} --fetch ${jobId}`,
+      askAgain: (projectId, thread) => `pk ask --project ${projectId}${portFlag} --thread ${thread} "<question>"`,
+    });
+  }
+  if (['context', 'get', 'options', 'help'].includes(command)) {
+    return agentEntry(command, entryTarget(app), console_, positionals(), { work: arg('--work'), purpose: arg('--purpose'), kind: arg('--kind'), recipient: arg('--recipient'), since: arg('--since') });
+  }
+  if (command === 'projects') {
+    for (const p of app.workspace.list()) console.log(`${p.id}\t${p.name}\t${p.locations.join(', ')}`);
+    return 0;
+  }
+  console.error(`unknown command: ${command}`);
+  return 2;
+}
+
+/** The workbench and project the agent entry reads: `--port` (default from the settings), `--project` or `--cwd`. */
+function entryTarget(app: App): EntryTarget {
+  return { base: `http://127.0.0.1:${arg('--port', String(app.workspace.settings.port))}`, project: arg('--project'), cwd: arg('--cwd') ?? process.cwd() };
+}
+
+/** The agent entry's text on the terminal: what was asked for on stdout, the rest on stderr. */
+const console_: EntryOutput = { out: (text) => console.log(text), err: (text) => console.error(text) };
+
+main().then((code) => { process.exitCode = code; }, (error) => {
+  if (error instanceof Exit) { process.exitCode = error.code; return; }
+  // A settings file that cannot be read is the owner's to correct: the message names it and says how; no stack.
+  console.error(error instanceof WorkspaceFileError ? error.message : error);
+  process.exitCode = 1;
+});

package/src/codemap/README.md

@@ -0,0 +1,13 @@
+# Code-map counting rules
+
+`CodeMapIndex` takes the existing ledger and the project's stored work items and territories. It does not invoke a model.
+
+- **What counts as code:** the ledger decides, not a list of languages. A file is code when a reader reads its references (`code_files.reader`: the TypeScript compiler for TypeScript and JavaScript, the code engine for every other language), or when it is in a language the ledger knows is code though nothing reads it (anything but the prose and data of `ledger/code.ts` `NOT_CODE`: a shell script, a C header with nothing in it to read, any code when the engine cannot run). Generated, classified (third-party) and test files are no territory's code. `Ledger.referenceReach` weighs a residual judgement by the same rule. A ledger built before the `reader` column existed has none; TypeScript and JavaScript then count as read, as the ledger itself falls back.
+- **Built by:** only commits on the trunk's first-parent line count. A merge's `commit_files` already means its diff against its first parent; each commit's changed path counts once. A retained fast-forward branch can name the contiguous first-parent run back to the preceding merge or another known work item. Commit message and branch identifiers match `WorkThread.ids` and `KeeperNumber` aliases. A confirmed `ProcessLink` to `commit:<hash>` overrides a textual match. Rows without a unique work match remain `Unclaimed`. A deleted branch with no identifying commit text or confirmed link cannot be recovered from the current refs.
+- **Generation:** the rebuild runs read-only `git blame --incremental` on the current HEAD's unclassified, non-generated files whose references a reader reads (`ledger/blame.ts`); code nothing reads is not blamed and adds no lines to a generation. The ledger stores ranges of line numbers and commit hashes, keyed by each file's git blob id. Unchanged blobs reuse the cache. A date-only `Generation.ended` includes that local author day; a timestamp uses its exact instant. Lines after all ended generations belong to the current generation (`generationId: null`). `generationOrigins()` gives the line count, share and work breakdown; `TerritoryView.generations` carries each share and the work items its lines came from.
+- **Dependency count:** one edge per distinct source-file/target-file pair crossing two territories. Every non-test kind `code_deps` records counts — the compiler's `import` and `reference`, the engine's `import`, `calls` and the other references it resolved — and duplicate kinds for the same pair count once. External packages and test-file edges do not count.
+- **Current use:** every code file takes part. Tests and generated/classified files cannot keep a source file live. Conventional `main`, `app`, `index`, `cli`, `bootstrap`, `application`, `route` and `router` files and files changed by a work item in the current generation anchor a non-test reference walk; a reference from code a reader reads can reach code nothing reads. Code outside that closure is unreferenced, including chains and isolated cycles. Who names such code comes from the ledger (`code_files.named_by`, `ledger/code.ts` `NamingKind`), read from every tracked text file: a build or manifest file naming it (a C++ source its `CMakeLists.txt` compiles, the activity `AndroidManifest.xml` launches by `.MainActivity`) makes it a named entry point; code the walk reaches naming it, a reference its reader did not resolve (a Dart `part`); a document, data or a test's fixture only mentions it. A named entry point, a file live code names, and code only they reach are not shown to be unreferenced. A territory none of whose code is reached is `Unreferenced` when some of it is read and none of it is such code, and `Not known` otherwise, as is a territory with no code. A territory whose live incoming references all come from files with at least 95% older-generation lines is `Previous generation only`; otherwise it is `In current plan` when current work changed it or its area has requirements, designs, decisions, plans or work items in force, else `In use, not in current plan`. These are program candidates from file references, not proof of runtime use or a plan link. Dynamic registration, routing, reflection and manually invoked scripts need model review. An unreferenced candidate says what is uncertain about it — nothing reads it; it is a named entry point, "named in AndroidManifest.xml"; code names it; only such files reach it — and its judgement is then `Inferred` (`Ledger.referenceReach`); a mention is said too and leaves it computed.
+- **Residual-name candidates:** a path component or token `legacy`, `old`, `deprecated`, `backup` or `v1` with a non-test inbound reference. Generic words only: whether a project's own name looks residual (a folder still called after the product's first idea) is the cross-check's judgement from that project's history. This is a naming heuristic, never an anomaly judgement.
+- **How deep each language is read:** `codeLevels()` gives `CodeView.levels` from the ledger's measured coverage (`Ledger.coverage().languages`): every language a reader reads and every language the ledger knows is code — who reads it, how many of its files, and for the engine the imports it resolved to a repository file and those it left unresolved naming one, the files code names that no counted reference reaches, and parse errors. A language is `complete` when every file is read and nothing was measured unresolved; elsewhere residual calls are `Inferred`. Named entry points say where a language's code is entered, not how deep it is read: the ledger's coverage counts them apart (`namedEntryPoints`), and a residual call on one is `Inferred` by `Ledger.referenceReach`. `Project scope` says the same per language from the same data (`ScopeKView` `ledger.languages[].code`, `ledger/views.ts` `coverageView`).
+
+The model-owned `CodeTerritory.anomalies` is unchanged. `codeAnomalyCandidates(ledger, store, project)` supplies cross-check input with ledger file and commit references. With no territories yet, `codeView()` displays measured disjoint directories under their real paths and the message `No territories drawn yet`.

package/src/codemap/engines.ts

@@ -0,0 +1,102 @@
+/**
+ * `KEngines.codemap` (server/k-views.ts): what the process view and `Code` need from the code map besides the ledger's
+ * own views (Spec v3.0 §6.17, §1.19; CKC-25 AC-6, AC-7, AC-10):
+ * - which territories each work item changed — the jump from a work to its territories, counted as `Built by` counts;
+ * - which of a territory's paths the current version no longer has;
+ * - a file of the current version, found through the ledger's `fileRefs` and read from the tree the ledger read.
+ *
+ * Program facts only, read from the ledger's tables and the assets; nothing is judged. One `CodeMapIndex` per repository
+ * is kept while neither the ledger nor the assets it reads have changed.
+ */
+import type { Ledger } from '../ledger/index.ts';
+import type { LedgerService } from '../ledger/adapters.ts';
+import type { Project } from '../model/types.ts';
+import type { CodeFileTextView, WorkTerritoryView } from '../model/views-k.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import { endsWithPath, pathKey } from '../util/paths.ts';
+import { CodeMapIndex } from './facts.ts';
+
+export interface CodeMapEngines {
+  /** The territories each work item changed, by work id; null without a ledger. */
+  workTerritories(store: ProjectStore, project: Project): Readonly<Record<string, readonly WorkTerritoryView[]>> | null;
+  /** The paths of each territory the current version no longer has, by territory id (only territories with some); null without a ledger. */
+  gonePaths(store: ProjectStore, project: Project): Readonly<Record<string, readonly string[]>> | null;
+  /** A file of the current version (§6.17 "点文件打开原文阅读"), a page of it from `fromLine`; a string says why not; null without a ledger. */
+  fileText(project: Project, input: { readonly path: string; readonly repo?: string | null; readonly fromLine?: number | null }): CodeFileTextView | string | null;
+}
+
+/** What the index reads of the assets: when any of it changes, the index is built again. */
+function storeMark(store: ProjectStore): string {
+  const part = (xs: readonly { readonly id: string; readonly updatedAt?: string }[]) => `${xs.length}:${xs.reduce((m, x) => ((x.updatedAt ?? '') > m ? x.updatedAt ?? '' : m), '')}`;
+  return [
+    part(store.threads.all()), part(store.territories.all()), part(store.generations.all()), part(store.nodes.all()),
+    part(store.numbers.all().map((n) => ({ id: n.id, updatedAt: n.at }))), part(store.links.all().map((l) => ({ id: `${l.id}${l.confirmed ? '+' : l.check?.passed ? '~' : ''}`, updatedAt: l.at }))),
+  ].join('|');
+}
+
+function ledgerMark(ledger: Ledger): string {
+  const r = ledger.db.prepare('SELECT max(id) id, max(ended_at) at FROM rebuilds').get() as { id: number | null; at: string | null } | undefined;
+  return `${r?.id ?? 0}:${r?.at ?? ''}`;
+}
+
+/** The territories of one repository of the ledger, matched as `Code` matches them (ledger/views.ts `repoOf`): by id, by
+ *  path, by the path's last part; one that matches none is the main repository's. */
+function territoriesOf(store: ProjectStore, project: Project, ledger: Ledger, repoId: string) {
+  const repos = ledger.repos();
+  const repoOf = (t: { repo: string }) => (repos.find((r) => r.id === t.repo || pathKey(r.path) === pathKey(t.repo) || endsWithPath(r.path, t.repo)) ?? repos[0])?.id;
+  return store.territories.filter((t) => t.projectId === project.id && repoOf(t) === repoId);
+}
+
+export function codeMapEngines(ledgerService: LedgerService): CodeMapEngines {
+  const cache = new Map<string, { ledger: Ledger; store: ProjectStore; mark: string; index: CodeMapIndex }>();
+  const indexOf = (store: ProjectStore, project: Project, ledger: Ledger, repoId: string): CodeMapIndex => {
+    const key = `${project.id}\x1f${repoId}`;
+    const mark = `${ledgerMark(ledger)}#${storeMark(store)}`;
+    const hit = cache.get(key);
+    if (hit && hit.ledger === ledger && hit.store === store && hit.mark === mark) return hit.index;
+    const index = new CodeMapIndex(ledger, store, repoId);
+    cache.set(key, { ledger, store, mark, index });
+    return index;
+  };
+  const withLedger = <T>(project: Project, fn: (l: Ledger) => T): T | null => {
+    const l = ledgerService.ledger(project.id);
+    if (!l) return null;
+    try { return fn(l); } catch { return null; }
+  };
+  return {
+    workTerritories: (store, project) => withLedger(project, (l) => {
+      const out: Record<string, WorkTerritoryView[]> = {};
+      for (const r of l.repos()) {
+        const territories = territoriesOf(store, project, l, r.id);
+        if (!territories.length) continue;
+        for (const [workId, rows] of indexOf(store, project, l, r.id).territoriesByWork(territories)) out[workId] = [...(out[workId] ?? []), ...rows];
+      }
+      for (const rows of Object.values(out)) rows.sort((a, b) => b.files - a.files || a.name.localeCompare(b.name));
+      return out;
+    }),
+    gonePaths: (store, project) => withLedger(project, (l) => {
+      const out: Record<string, string[]> = {};
+      for (const r of l.repos()) {
+        const territories = territoriesOf(store, project, l, r.id);
+        if (!territories.length) continue;
+        const index = indexOf(store, project, l, r.id);
+        for (const t of territories) { const gone = index.gonePaths(t.paths); if (gone.length) out[t.id] = gone; }
+      }
+      return out;
+    }),
+    fileText: (project, input) => withLedger(project, (l) => {
+      const repoId = l.repoId(input.repo ?? null);
+      if (input.repo && !repoId) return `${input.repo} is not a repository of this project's ledger.`;
+      const refs = l.fileRefs(input.path, repoId ? { repo: repoId } : {});
+      if (typeof refs === 'string') return refs;
+      const repo = l.repos().find((r) => r.id === refs.repo);
+      if (!repo?.head) return `The ledger has no current version of ${refs.path}.`;
+      const page = l.docText({ path: refs.path, commit: repo.head, repo: refs.repo }, { from: input.fromLine ?? 1 });
+      if (typeof page === 'string') return page;
+      return {
+        repo: repo.path, path: refs.path, lang: refs.lang, commit: page.commit, occurred: page.occurred, lines: page.lines,
+        fromLine: page.fromLine, toLine: page.toLine, nextFromLine: page.nextFromLine ?? null, text: page.text, generated: refs.generated,
+      };
+    }),
+  };
+}