@dzhechkov/harness-core 0.8.47 → 0.8.49

package/src/setup.ts

@@ -16,9 +16,12 @@
  * @packageDocumentation
  */
 
-import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync, renameSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative } from 'node:path';
-import { execSync, spawnSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
+
+import { randomUUID } from 'node:crypto';
+import { reconcileMemoryDependencies } from './setup-memory-deps.js';
 
 import { mergeManagedHookEntries } from './managed-hooks.js';
 import { writeUniqueStampedFile } from './stamped-path.js';
@@ -146,6 +149,8 @@ export interface SetupResult {
   readonly skipped: number;
   /** The memory backend this run actually used (feature `setup-backend-from-config`, FR-1). */
   readonly memoryBackend: MemoryBackend;
+  /** Observed persisted state; unknown is explicit on failed/uninitialized setup. */
+  readonly memoryBackendObserved?: MemoryBackend | 'unknown';
   /** Where {@link memoryBackend} came from — FR-3, also the `--json` field name. */
   readonly memoryBackendSource: MemoryBackendSource;
   /** `true` when an explicit `--memory jsonl` pulled an agentdb-configured project down (FR-2). */
@@ -547,11 +552,6 @@ function generateDzConfig(target: string, preset: string | undefined, backend: M
   }, null, 2);
 }
 
-/** True if `agentdb` resolves from the project's node_modules (the hook writer needs it there). */
-function isAgentdbInstalledLocally(projectRoot: string): boolean {
-  return existsSync(join(projectRoot, 'node_modules', 'agentdb', 'package.json'));
-}
-
 /**
  * The exact agentdb version installed in the project, or `'latest'` as a fallback. Used to pin the
  * MCP server spec (`agentdb@<version>`) so the long-running MCP server and the hook writer — which
@@ -573,38 +573,6 @@ function installedAgentdbSpec(projectRoot: string): string {
  * build tools — and gives true cross-process WAL concurrency so the hook and the MCP server share
  * one live store). Best-effort: returns false (caller degrades to jsonl) if install fails.
  */
-function installAgentdbLocally(projectRoot: string): boolean {
-  if (isAgentdbInstalledLocally(projectRoot)) return true;
-  try {
-    // Anchor npm to THIS project: without a package.json here, npm's prefix walk-up would
-    // install into (and mutate the lockfile of) the nearest ANCESTOR project (audit code#2).
-    const pkgJsonPath = join(projectRoot, 'package.json');
-    if (!existsSync(pkgJsonPath)) {
-      writeFileSync(pkgJsonPath, JSON.stringify({ name: 'dz-harness-project', private: true, version: '0.0.0' }, null, 2) + '\n');
-    }
-    // NB: use the ESM-imported execSync — `require()` is undefined in this ESM module (the
-    // original agentdb hooks failed silently for exactly this reason). stdio:'ignore' (not
-    // 'pipe') avoids execSync's 1 MB maxBuffer aborting the child on npm's verbose output.
-    // --save-exact: agentdb is alpha; a semver range would let a later `npm update` drift the
-    // local copy away from the version the MCP registration pins (audit gap G7).
-    //
-    // better-sqlite3@^11 (AM-2, dz-harness-hub issue #10 defect 1, MEASURED Node 20.20.2 with no
-    // `make` on PATH): an unpinned `npm install better-sqlite3` resolved 12.11.1, which ships no
-    // prebuilt binary for Node 20's ABI 115 — the install fell through to a node-gyp source build
-    // and failed on a machine with no C toolchain. `agentdb` itself requests `^11.8.1`, which DOES
-    // publish an ABI-115 prebuild, so pinning the range here costs nothing agentdb wasn't already
-    // going to resolve to, and buys a working install on a bare Node 20/22 host.
-    execSync('npm install agentdb better-sqlite3@^11 --save-exact --no-audit --no-fund --loglevel=error', {
-      cwd: projectRoot,
-      stdio: 'ignore',
-      timeout: 300000,
-    });
-    return isAgentdbInstalledLocally(projectRoot);
-  } catch {
-    return false;
-  }
-}
-
 /** Run full environment setup. */
 /** Marker that brackets the dz-harness section in a shared CLAUDE.md/AGENTS.md. */
 const DRIVER_MARKER_START = '<!-- dz-harness-driver:start -->';
@@ -957,19 +925,39 @@ export function runSetup(opts: SetupOptions): SetupResult {
   const resolvedMemory = resolveSetupMemoryBackend(opts.projectRoot, opts.memory, opts.noMemory === true);
   const backend: MemoryBackend = resolvedMemory.backend;
 
-  // Step 0: Install agentdb + better-sqlite3 locally so the session-hook writer can import them
-  // and share a native store with the MCP server. Best-effort — the writer self-degrades to a
-  // jsonl marker (and self-heals once the deps exist) if this fails.
-  if (backend === 'agentdb') {
-    const ready = installAgentdbLocally(opts.projectRoot);
-    if (ready) {
-      steps.push({ name: 'Install agentdb + better-sqlite3', status: 'done', detail: 'local deps for real vector writes' });
-    } else {
-      steps.push({
-        name: 'Install agentdb + better-sqlite3',
-        status: 'error',
-        detail: 'install failed — hooks log to sessions.jsonl until you run: npm i agentdb better-sqlite3',
-      });
+  const configPath = join(dzDir, 'config.json');
+  let config: Record<string, unknown> | undefined;
+  const observedBackend = (): MemoryBackend | 'unknown' => {
+    try {
+      const value = JSON.parse(readFileSync(configPath, 'utf8')) as { memory?: { backend?: unknown } };
+      return value?.memory?.backend === 'agentdb' || value?.memory?.backend === 'jsonl' ? value.memory.backend : 'unknown';
+    } catch { return 'unknown'; }
+  };
+  const finish = (): SetupResult => ({
+    steps, totalSteps: steps.length, completed: steps.filter(step => step.status === 'done').length,
+    skipped: steps.filter(step => step.status === 'skipped').length,
+    memoryBackend: observedBackend() === 'unknown' ? resolvedMemory.backend : observedBackend() as MemoryBackend,
+    memoryBackendObserved: observedBackend(), memoryBackendSource: resolvedMemory.source,
+    memoryBackendDowngraded: resolvedMemory.downgraded,
+  });
+  try {
+    if (existsSync(configPath)) {
+      const value: unknown = JSON.parse(readFileSync(configPath, 'utf8'));
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) throw Error('config must be an object');
+      config = value as Record<string, unknown>;
+      const memory = config['memory'];
+      if (memory === null || typeof memory !== 'object' || Array.isArray(memory) || !['jsonl', 'agentdb'].includes(String((memory as Record<string, unknown>)['backend']))) throw Error('memory.backend must be jsonl or agentdb');
+    }
+  } catch (error) {
+    steps.push({ name: 'Memory saved state', status: 'error', detail: `unknown INCOMPLETE: malformed .dz/config.json preserved; ${String(error)}` });
+    return finish();
+  }
+  if (backend === 'agentdb' && !opts.noMemory) {
+    const deps = reconcileMemoryDependencies(opts.projectRoot);
+    steps.push({ name: 'Memory dependencies', status: deps.ready ? (deps.changedManifest || deps.changedLock || deps.detail.startsWith('repaired') ? 'done' : 'skipped') : 'error', detail: deps.detail });
+    if (!deps.ready) {
+      steps.push({ name: 'Memory backend transition', status: 'error', detail: `saved backend ${observedBackend()} INCOMPLETE before config persistence; dependency/npm/native failure; later memory phases not run` });
+      return finish();
     }
   }
 
@@ -981,38 +969,32 @@ export function runSetup(opts: SetupOptions): SetupResult {
     steps.push({ name: 'Create .dz directory', status: 'skipped', detail: 'already exists' });
   }
 
-  // Step 2: Write .dz/config.json. FR-2: a DOWNGRADE (explicit --memory jsonl over an
-  // agentdb-configured project) forces the write even without --force — "two truths after any
-  // setup coincide" means the config may not keep claiming agentdb once the caller has explicitly
-  // asked for jsonl.
-  const configPath = join(dzDir, 'config.json');
-  if (!existsSync(configPath) || opts.force) {
-    writeFileSync(configPath, generateDzConfig(opts.target, opts.preset, backend));
-    steps.push({ name: 'Write .dz/config.json', status: 'done', detail: `${backend} backend` });
-  } else if (resolvedMemory.downgraded) {
-    // Lead edit after Codex review (finding 3): a downgrade changes ONLY memory.backend — every other
-    // field the owner keeps in .dz/config.json survives; an unparsable file falls back to regeneration.
-    let rewritten = false;
-    try {
-      const cfg = JSON.parse(readFileSync(configPath, 'utf-8')) as Record<string, unknown>;
-      const memory = (cfg['memory'] !== null && typeof cfg['memory'] === 'object') ? (cfg['memory'] as Record<string, unknown>) : {};
-      cfg['memory'] = { ...memory, backend };
-      writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
-      rewritten = true;
-    } catch { /* fall through to regeneration */ }
-    if (!rewritten) writeFileSync(configPath, generateDzConfig(opts.target, opts.preset, backend));
-    steps.push({ name: 'Write .dz/config.json', status: 'done', detail: `memory.backend → ${backend} (other fields kept)` });
+  // Persist only the requested backend field of readable existing config, atomically.
+  const priorBackend = observedBackend();
+  if (opts.noMemory) {
+    steps.push({ name: 'Write .dz/config.json', status: 'skipped', detail: '--no-memory: existing memory configuration preserved' });
   } else {
-    steps.push({ name: 'Write .dz/config.json', status: 'skipped', detail: 'already exists (use --force)' });
-  }
-  if (resolvedMemory.downgraded) {
-    steps.push({
-      name: 'Memory backend downgrade',
-      status: 'done',
-      detail: '⚠ memory backend downgraded agentdb → jsonl by --memory jsonl',
-    });
+    const transition = config !== undefined && opts.memory !== undefined && priorBackend !== backend;
+    if (config === undefined || opts.force || transition) {
+      const next = config !== undefined
+        ? { ...config, memory: { ...(config['memory'] as Record<string, unknown>), backend } }
+        : JSON.parse(generateDzConfig(opts.target, opts.preset, backend));
+      const temporary = `${configPath}.${randomUUID()}.tmp`;
+      try {
+        writeFileSync(temporary, JSON.stringify(next, null, 2) + '\n', { flag: 'wx' });
+        renameSync(temporary, configPath);
+        steps.push({ name: 'Write .dz/config.json', status: 'done', detail: transition ? `memory.backend ${priorBackend} → ${backend}; all other config fields kept` : `${backend} backend` });
+      } catch (error) {
+        if (existsSync(temporary)) rmSync(temporary);
+        steps.push({ name: 'Memory backend transition', status: 'error', detail: `saved backend ${observedBackend()} INCOMPLETE: config persistence failed; later memory wiring not run; ${String(error)}` });
+        return finish();
+      }
+    } else steps.push({ name: 'Write .dz/config.json', status: 'skipped', detail: 'already current; existing config preserved' });
+    if (resolvedMemory.downgraded) steps.push({ name: 'Memory backend downgrade', status: 'done', detail: '⚠ memory backend downgraded agentdb → jsonl by --memory jsonl; other config fields kept' });
   }
 
+  try {
+  if (!opts.noMemory) {
   // Step 3: Initialize session log
   const sessionsPath = join(dzDir, 'sessions.jsonl');
   if (!existsSync(sessionsPath)) {
@@ -1064,18 +1046,20 @@ export function runSetup(opts: SetupOptions): SetupResult {
     }
   }
 
+  } // --no-memory performs no memory store initialization.
+
   // Step 4.6: Install apply-leg — the WORK happens here (before "Configure hooks" writes
   // SessionStart), so a foreign SessionStart entry is already in place before that step's own
   // merge ever sees it; see `applyLegStepResult`'s doc for why order matters. The STEP is reported
   // further down, after "Configure hooks" pushes its own, so the printed order still reads as
   // "collect → rank → apply".
-  const applyLegStep = applyLegStepResult(opts, backend);
+  const applyLegStep: SetupStep = opts.noMemory ? { name: 'Install apply-leg', status: 'skipped', detail: '--no-memory' } : applyLegStepResult(opts, backend);
 
   // Step 5: Configure hooks (write to .claude/settings.json) — EVENT-LEVEL merge (gap G2):
   // dz-generated entries (recognized by signature, incl. the broken legacy `agentdb add` hooks
   // this feature fixes) are replaced in place WITHOUT --force; the user's own hooks and every
   // other settings key are preserved. Full-file overwrite happens only when the file is absent.
-  if (!opts.noHooks) {
+  if (!opts.noHooks && !opts.noMemory) {
     const settingsDir = join(opts.projectRoot, '.claude');
     const settingsPath = join(settingsDir, 'settings.json');
 
@@ -1253,7 +1237,7 @@ export function runSetup(opts: SetupOptions): SetupResult {
       }
     }
   } else {
-    steps.push({ name: 'Configure hooks', status: 'skipped', detail: '--no-hooks' });
+    steps.push({ name: 'Configure hooks', status: 'skipped', detail: opts.noMemory ? '--no-memory: existing hooks and guards preserved; no delivery' : '--no-hooks' });
   }
 
   // Step 5.6: Install apply-leg — report pushed AFTER "Configure hooks" below (for a report order
@@ -1264,7 +1248,7 @@ export function runSetup(opts: SetupOptions): SetupResult {
   // Step 5.5: Register agentdb MCP through the SAME ownership-aware transaction used by `dz init`.
   // `.mcp.json` is the project-scope carrier Claude Code actually loads. A known historical dz
   // agentdb shape is adopted; an ambiguous hand-authored entry is preserved and named as an error.
-  if (backend === 'agentdb') {
+  if (backend === 'agentdb' && !opts.noHooks && !opts.noMemory) {
     const agentdbEntry = {
       command: 'npx',
       // Pin to the INSTALLED agentdb version (not @latest) so the MCP server and the hook
@@ -1322,12 +1306,28 @@ export function runSetup(opts: SetupOptions): SetupResult {
     }
   }
 
+  } catch (error) {
+    steps.push({ name: 'Memory backend transition', status: 'error', detail: `saved backend ${observedBackend()} INCOMPLETE: managed wiring failed after persistence; ${String(error)}` });
+    return finish();
+  }
+
+  // Saved/local/native agreement is independent of hook installation.
+  if (!opts.noMemory) {
+    const actual = observedBackend();
+    const problems: string[] = actual === backend ? [] : [`saved backend ${actual} differs from requested ${backend}`];
+    if (backend === 'agentdb') {
+      const deps = reconcileMemoryDependencies(opts.projectRoot, false);
+      if (!deps.ready) problems.push(deps.detail);
+    }
+    steps.push({ name: 'Memory saved state', status: problems.length ? 'error' : 'done', detail: problems.length ? `saved backend ${actual} INCOMPLETE: ${problems.join('; ')}` : `saved backend ${actual}; dependencies/native state consistent` });
+  }
+
   // Step 5.9: agentdb wiring invariant check (audit code#3). Skip-branches across repeated runs
   // can leave inconsistent combinations (e.g. writer+MCP present but hooks still jsonl). Verify
   // the three-way invariant explicitly and surface a loud error step instead of silent "skipped"s.
-  if (backend === 'agentdb' && !opts.noHooks) {
+  if (backend === 'agentdb' && !opts.noHooks && !opts.noMemory) {
     const problems: string[] = [];
-    if (!isAgentdbInstalledLocally(opts.projectRoot)) problems.push('deps missing (npm i agentdb better-sqlite3)');
+    if (observedBackend() !== backend) problems.push(`saved backend ${observedBackend()} differs from ${backend}`);
     try {
       const settings = JSON.parse(readFileSync(join(opts.projectRoot, '.claude', 'settings.json'), 'utf-8')) as {
         hooks?: Record<string, unknown[]>;
@@ -1357,7 +1357,7 @@ export function runSetup(opts: SetupOptions): SetupResult {
   // sentinel check (e.g. sessions.jsonl, present in both backends) would skip agentdb.db/-wal/-shm
   // on the documented jsonl→agentdb `--force` switch, leaking the binary store into git.
   const gitignorePath = join(opts.projectRoot, '.gitignore');
-  const dzIgnoreLines = backend === 'agentdb'
+  const dzIgnoreLines = opts.noMemory ? [] : backend === 'agentdb'
     ? ['.dz/agentdb.db', '.dz/agentdb.db-wal', '.dz/agentdb.db-shm',
        '.dz/agentdb-mcp.db', '.dz/agentdb-mcp.db-wal', '.dz/agentdb-mcp.db-shm',
        '.dz/sessions.jsonl']
@@ -1374,7 +1374,7 @@ export function runSetup(opts: SetupOptions): SetupResult {
       detail: `added ${missing.join(', ')}`,
     });
   } else {
-    steps.push({ name: 'Update .gitignore', status: 'skipped', detail: 'already ignoring .dz data' });
+    steps.push({ name: 'Update .gitignore', status: 'skipped', detail: opts.noMemory ? '--no-memory: existing ignore rules preserved' : 'already ignoring .dz data' });
   }
 
   // Step 7: Install the CLI-driver skill + agent docs (--install-driver)
@@ -1383,13 +1383,10 @@ export function runSetup(opts: SetupOptions): SetupResult {
     steps.push({ name: 'Install driver skill', status: 'done', detail });
   }
 
-  return {
-    steps,
-    totalSteps: steps.length,
-    completed: steps.filter((s) => s.status === 'done').length,
-    skipped: steps.filter((s) => s.status === 'skipped').length,
-    memoryBackend: resolvedMemory.backend,
-    memoryBackendSource: resolvedMemory.source,
-    memoryBackendDowngraded: resolvedMemory.downgraded,
-  };
+  const failed = steps.filter(step => step.status === 'error');
+  if (!opts.noMemory && backend === 'agentdb') steps.push({
+    name: 'Memory backend transition', status: failed.length ? 'error' : 'done',
+    detail: failed.length ? `saved backend ${observedBackend()} INCOMPLETE; failed phase: ${failed.map(step => step.name).join(', ')}` : `saved backend ${observedBackend()} ready; ${priorBackend === backend ? 'already current' : `${priorBackend} → ${backend} transition complete`}`,
+  });
+  return finish();
 }

package/src/stage-usage.ts

@@ -54,6 +54,199 @@ function price(row: RecordRow, dimensions: Record<typeof tokenFields[number], nu
       capturedAt: text(prices?.['snapshotAt']), fingerprint: fnv1a64(JSON.stringify(prices ?? MODEL_PRICES)), current: false, billed: false } };
 }
 
+type RoutingInput = Parameters<typeof buildStageUsageReport>[0];
+type RoutingAttempt = { ordinal: number; model: string | null; family: 'openai' | 'claude'; wrapperInvoked: boolean;
+  outcome: 'answered' | 'failed' | 'rejected'; reason: string; selected: boolean };
+type RoutingStage = { evidenceKey: string; dispatchSeq: number; plannedModel: string | null;
+  plannedModelSource: 'plan-declared' | 'plan-omitted' | 'unavailable' | 'not-recorded'; requestedModel: string | null;
+  probeId: string | null; linkStatus: string };
+type RoutingProbe = { probeId: string; runId: string; family: 'openai' | 'claude'; source: string;
+  selectedModel: string | null; complete: boolean; totalConsidered: number; attempts: RoutingAttempt[] };
+const safeRoutingModel = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(value);
+const routingId = (value: unknown): value is string => typeof value === 'string' && /^[0-9a-f]{32}$/.test(value);
+const routingRun = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z0-9_.-]{1,128}$/.test(value) && value !== '.' && value !== '..';
+const routingFamily = (value: unknown): value is 'openai' | 'claude' => value === 'openai' || value === 'claude';
+const exactRoutingKeys = (value: unknown, keys: readonly string[]): value is RecordRow => record(value)
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+  && Reflect.ownKeys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const routingAbsenceReasons = ['producer-not-recorded', 'id-factory-missing'];
+const routingErrorReasons = ['id-factory-invalid', 'provenance-invalid', 'candidate-model-invalid', 'wrapper-result-invalid', 'selected-model-invalid'];
+
+function validateRoutingAttempts(value: unknown, family: unknown, selectedModel: unknown): { complete: boolean; totalConsidered: number; attempts: RoutingAttempt[] } | null {
+  if (!exactRoutingKeys(value, ['schema', 'complete', 'totalConsidered', 'attempts']) || value['schema'] !== 'wf-probe-attempts-1'
+    || typeof value['complete'] !== 'boolean' || !routingFamily(family) || (selectedModel !== null && !safeRoutingModel(selectedModel))) return null;
+  const total = count(value['totalConsidered']);
+  const attempts = value['attempts'];
+  if (total === null || total === 0 || !Array.isArray(attempts) || attempts.length !== Math.min(total, 32) || value['complete'] !== (total <= 32)) return null;
+  const safe: RoutingAttempt[] = [];
+  for (const [index, a] of attempts.entries()) {
+    if (!exactRoutingKeys(a, ['ordinal', 'model', 'family', 'wrapperInvoked', 'outcome', 'reason', 'selected']) || a['ordinal'] !== index + 1
+      || a['family'] !== family || typeof a['wrapperInvoked'] !== 'boolean' || typeof a['selected'] !== 'boolean') return null;
+    const rejected = family === 'claude' && !a['wrapperInvoked'] && !a['selected'] && a['model'] === null && a['outcome'] === 'rejected' && a['reason'] === 'invalid-candidate';
+    const answered = a['wrapperInvoked'] && a['selected'] && safeRoutingModel(a['model']) && a['outcome'] === 'answered' && a['reason'] === 'answered';
+    const failed = a['wrapperInvoked'] && !a['selected'] && safeRoutingModel(a['model']) && a['outcome'] === 'failed'
+      && ['timeout', 'spawn-error', 'no-exit-code', 'exit-nonzero', 'unexpected-response'].includes(a['reason'] as string);
+    if (!(rejected || answered || failed)) return null;
+    safe.push({ ordinal: index + 1, model: a['model'] as string | null, family, wrapperInvoked: a['wrapperInvoked'],
+      outcome: a['outcome'] as RoutingAttempt['outcome'], reason: a['reason'] as string, selected: a['selected'] });
+  }
+  const selected = safe.filter(a => a.selected);
+  if (!value['complete'] ? selected.length !== 0 : selectedModel === null ? selected.length !== 0
+    : selected.length !== 1 || selected[0]?.ordinal !== total || selected[0]?.model !== selectedModel) return null;
+  return { complete: value['complete'], totalConsidered: total, attempts: safe };
+}
+
+function routingStageIdentity(row: RecordRow): { evidenceKey: string; dispatchSeq: number } | null {
+  const seq = count(row['dispatchSeq']);
+  if (seq === null || seq === 0 || !routingRun(row['runId'])) return null;
+  const evidenceKey = JSON.stringify(['wf-dispatch', row['runId'], seq]);
+  if (Object.hasOwn(row, 'evidenceKey') && row['evidenceKey'] !== evidenceKey) return null;
+  return { evidenceKey, dispatchSeq: seq };
+}
+
+/** Routing uses raw bounded evidence, independently of numerical first-wins normalization. */
+function projectRoutingProvenance(input: RoutingInput) {
+  const diagnostics = new Set<string>();
+  let defect = false;
+  let partial = false;
+  let scopeInvalid = false;
+  let scopeIncomplete = false;
+  const mark = (reason: string, severity: 'defect' | 'partial' = 'partial') => {
+    diagnostics.add(reason);
+    if (severity === 'defect') defect = true; else partial = true;
+  };
+  const metadataInvalid = (reason = 'metadata-invalid') => mark(reason, 'defect');
+  const sourceMap: Record<string, [string, 'defect' | 'partial']> = {
+    'inventory-truncated': ['source-truncated', 'partial'], 'source-input-too-large': ['source-too-large', 'partial'],
+    'missing-or-unreadable-source': ['source-unreadable', 'partial'], 'malformed-record': ['source-malformed', 'defect'],
+    'malformed-budget-schema': ['source-malformed', 'defect'],
+    'inventory-run-state-unavailable-or-foreign': ['source-scope-incomplete', 'partial'],
+    'inventory-trace-binding-unavailable': ['source-scope-incomplete', 'partial'],
+  };
+  const invalidSources = ['source-outside-root-or-nonregular', 'source-symlink', 'source-changed-during-read',
+    'inventory-trace-binding-mismatch', 'inventory-trace-invalid', 'inventory-workflow-projection-identity-invalid',
+    'inventory-workflow-projection-identity-mismatch', 'foreign-project-root', 'foreign-trace-run', 'unknown-source',
+    'source-selection-ambiguous', 'source-selection-conflicting-run-dir', 'workflow-source-missing-or-ambiguous', 'fa-run-selection-ambiguous-or-unidentified'];
+  for (const diagnostic of input.diagnostics ?? []) {
+    if (typeof diagnostic !== 'string' || diagnostic.length === 0) continue;
+    const name = diagnostic.split(':', 1)[0]!;
+    const mapping = invalidSources.includes(name) ? ['source-scope-invalid', 'defect'] as const : sourceMap[name];
+    if (mapping) { mark(mapping[0], mapping[1]); scopeInvalid ||= mapping[0] === 'source-scope-invalid'; scopeIncomplete ||= mapping[1] === 'partial'; }
+    else { mark('source-diagnostic-unmapped'); scopeIncomplete = true; }
+  }
+  const maximum = input.maxRecords ?? 100000;
+  if (input.rows.length > maximum || (input.expected?.length ?? 0) > maximum) { mark('source-truncated'); scopeIncomplete = true; }
+  const rawRows = input.rows.slice(0, maximum);
+  const invalidNormalizedKeys = new Set<string>();
+  const stageMaps = new Map<string, { raw: RecordRow; tuple: string; conflict: boolean; legacy: boolean; valid: boolean; modelInvalid: boolean }>();
+  const probeMaps = new Map<string, { raw: RecordRow; tuple: string; conflict: boolean; valid: boolean; reason: string | null; summary: RoutingProbe | null }>();
+  let hasNew = false;
+  let hasLegacy = false;
+  if (input.sourceKind === 'workflow-budget') {
+    if (!routingRun(input.runId)) { mark('source-scope-invalid', 'defect'); scopeInvalid = true; }
+    if (input.expected === undefined) { mark('source-scope-incomplete'); scopeIncomplete = true; }
+    for (const raw of rawRows) {
+      if (raw['kind'] === 'probe') {
+        const keys = ['probeId', 'probeProvenance', 'probeSource', 'probeObservationReason'];
+        const present = keys.map(key => Object.hasOwn(raw, key));
+        if (present.every(value => !value)) { hasLegacy ||= raw['runId'] === input.runId; continue; }
+        hasNew ||= raw['runId'] === input.runId;
+        const reason = raw['probeObservationReason'];
+        const modelValid = raw['model'] === null || safeRoutingModel(raw['model']);
+        const reasonValid = reason === null || (typeof reason === 'string' && [...routingAbsenceReasons, ...routingErrorReasons].includes(reason));
+        const idValid = raw['probeId'] === null || routingId(raw['probeId']);
+        const sourceValid = raw['probeSource'] === 'dispatcher-child-seam' || raw['probeSource'] === 'scripted-dispatcher';
+        const provenance = reason === null ? validateRoutingAttempts(raw['probeProvenance'], raw['family'], raw['model']) : null;
+        const valid = present.every(Boolean) && routingRun(raw['runId']) && routingFamily(raw['family']) && idValid && sourceValid && modelValid && reasonValid
+          && (reason === null ? routingId(raw['probeId']) && provenance !== null : raw['probeProvenance'] === null);
+        const supplied = raw['probeProvenance'];
+        const unsafeAttemptModel = record(supplied) && Array.isArray(supplied['attempts']) && supplied['attempts'].slice(0, 32).some(a => record(a)
+          && Object.hasOwn(a, 'model') && a['model'] !== null && !safeRoutingModel(a['model']));
+        if (!valid) metadataInvalid(modelValid && !unsafeAttemptModel ? 'metadata-invalid' : 'model-invalid');
+        else if (typeof reason === 'string') mark(reason, routingErrorReasons.includes(reason) ? 'defect' : 'partial');
+        else if (provenance && !provenance.complete) mark('attempts-truncated');
+        if (!routingId(raw['probeId'])) continue;
+        const summary: RoutingProbe | null = valid && reason === null && provenance !== null ? {
+          probeId: raw['probeId'], runId: raw['runId'] as string, family: raw['family'] as RoutingProbe['family'], source: raw['probeSource'] as string,
+          selectedModel: raw['model'] as string | null, complete: provenance.complete, totalConsidered: provenance.totalConsidered, attempts: provenance.attempts,
+        } : null;
+        // Rejected metadata is one closed marker: never traverse, copy or stringify its raw payload.
+        const tuple = JSON.stringify(valid
+          ? ['valid', raw['runId'], raw['family'], raw['model'], raw['probeSource'], reason, provenance]
+          : ['invalid']);
+        const old = probeMaps.get(raw['probeId']);
+        if (old && old.tuple !== tuple) { old.conflict = true; metadataInvalid('identity-conflict'); }
+        else if (!old) probeMaps.set(raw['probeId'], { raw, tuple, conflict: false, valid, reason: typeof reason === 'string' ? reason : null, summary });
+      } else if (raw['kind'] === 'stage') {
+        const identity = routingStageIdentity(raw);
+        if (!identity || raw['runId'] !== input.runId) {
+          metadataInvalid();
+          const key = text(raw['evidenceKey']) ?? (count(raw['dispatchSeq']) !== null ? JSON.stringify(['wf-dispatch', raw['runId'], raw['dispatchSeq']]) : null);
+          if (key !== null) invalidNormalizedKeys.add(key);
+          continue;
+        }
+        const keys = ['plannedModel', 'plannedModelSource', 'probeId'];
+        const present = keys.map(key => Object.hasOwn(raw, key));
+        const legacy = present.every(value => !value);
+        hasLegacy ||= legacy; hasNew ||= !legacy;
+        const plan = raw['plannedModel'];
+        const source = raw['plannedModelSource'];
+        const requestValid = raw['requestedModel'] === null || safeRoutingModel(raw['requestedModel']);
+        const planValid = source === 'plan-declared' ? safeRoutingModel(plan) : (source === 'plan-omitted' || source === 'unavailable') && plan === null;
+        const valid = legacy || present.every(Boolean) && requestValid && planValid && routingFamily(raw['family']) && (raw['probeId'] === null || routingId(raw['probeId']));
+        const modelInvalid = !legacy && (!requestValid || (source === 'plan-declared' && !safeRoutingModel(plan)) || source === 'unavailable');
+        if (!valid || modelInvalid) metadataInvalid(modelInvalid ? 'model-invalid' : 'metadata-invalid');
+        const tuple = JSON.stringify(legacy
+          ? ['legacy', routingFamily(raw['family']) ? raw['family'] : null, safeRoutingModel(raw['requestedModel']) ? raw['requestedModel'] : null]
+          : valid ? ['valid', raw['family'], raw['requestedModel'], plan, source, raw['probeId']] : ['invalid']);
+        const old = stageMaps.get(identity.evidenceKey);
+        if (old && old.tuple !== tuple) { old.conflict = true; metadataInvalid('identity-conflict'); }
+        else if (!old) stageMaps.set(identity.evidenceKey, { raw, tuple, conflict: false, legacy, valid, modelInvalid });
+      } else metadataInvalid();
+    }
+    for (const expected of (input.expected ?? []).slice(0, maximum)) {
+      const identity = routingStageIdentity(expected);
+      if (!identity || expected['runId'] !== input.runId) { metadataInvalid(); continue; }
+      if (!stageMaps.has(identity.evidenceKey)) { mark('expected-dispatch-missing'); scopeIncomplete = true; }
+    }
+  }
+  if (hasNew && hasLegacy) mark('not-recorded');
+  const stages: RoutingStage[] = [];
+  for (const [evidenceKey, stage] of [...stageMaps].sort(([a], [b]) => a.localeCompare(b))) {
+    const raw = stage.raw;
+    const referenced = routingId(raw['probeId']) ? probeMaps.get(raw['probeId']) : undefined;
+    let linkStatus = 'linked';
+    if (stage.conflict || referenced?.conflict) linkStatus = 'identity-conflict';
+    else if (scopeInvalid || !stage.valid || stage.modelInvalid || referenced && (!referenced.valid || referenced.reason !== null && routingErrorReasons.includes(referenced.reason))) linkStatus = 'invalid';
+    else if (stage.legacy) linkStatus = 'not-recorded';
+    else if (referenced && referenced.raw['runId'] !== input.runId) linkStatus = 'foreign-probe';
+    else if (referenced && referenced.raw['family'] !== raw['family']) linkStatus = 'family-mismatch';
+    else if (referenced?.summary && (referenced.summary.selectedModel === null || referenced.summary.selectedModel !== raw['requestedModel'])) linkStatus = 'selection-mismatch';
+    else if (raw['probeId'] !== null && !referenced) linkStatus = 'missing-probe';
+    else if (raw['probeId'] === null || referenced?.reason !== null && referenced?.reason !== undefined) linkStatus = 'probe-unavailable';
+    else if (scopeIncomplete) linkStatus = 'scope-incomplete';
+    const suppress = ['identity-conflict', 'invalid', 'foreign-probe', 'family-mismatch', 'selection-mismatch'].includes(linkStatus);
+    if (suppress) metadataInvalid(linkStatus === 'invalid' ? 'metadata-invalid' : linkStatus);
+    else if (linkStatus !== 'linked' && linkStatus !== 'not-recorded') mark(linkStatus === 'scope-incomplete' ? 'source-scope-incomplete' : linkStatus);
+    const identity = routingStageIdentity(raw)!;
+    stages.push({ evidenceKey, dispatchSeq: identity.dispatchSeq, plannedModel: suppress || stage.legacy ? null : raw['plannedModel'] as string | null,
+      plannedModelSource: suppress ? 'unavailable' : stage.legacy ? 'not-recorded' : raw['plannedModelSource'] as RoutingStage['plannedModelSource'],
+      requestedModel: suppress || stage.legacy ? null : raw['requestedModel'] as string | null,
+      probeId: !suppress && (linkStatus === 'linked' || linkStatus === 'scope-incomplete') ? raw['probeId'] as string : null, linkStatus });
+  }
+  const probes = [...probeMaps.values()].filter(probe => !scopeInvalid && !probe.conflict && probe.summary && probe.raw['runId'] === input.runId)
+    .map(probe => probe.summary!).sort((a, b) => a.probeId.localeCompare(b.probeId));
+  if (!hasNew) diagnostics.add('not-recorded');
+  const status = defect ? 'defect' : partial ? 'partial' : hasNew ? 'observed' : 'not-recorded';
+  const exposedStages = hasNew || defect ? stages : [];
+  const stageFields = new Map(stages.map(stage => [stage.evidenceKey, {
+    plannedModel: stage.plannedModel, plannedModelSource: stage.plannedModelSource, probeId: stage.probeId,
+  }]));
+  for (const key of invalidNormalizedKeys) stageFields.set(key, { plannedModel: null, plannedModelSource: 'unavailable', probeId: null });
+  return { report: { schema: 'routing-provenance-1', status, probes: probes.length ? probes : null,
+    stages: exposedStages.length ? exposedStages : null, diagnostics: [...diagnostics].sort() }, stageFields };
+}
+
 /** All amounts remain source-specific; inventory never substitutes for a numeric witness. */
 export function buildStageUsageReport(input: {
   sourceKind: string; sourcePath: string; runId: string | null; rows: readonly RecordRow[];
@@ -173,8 +366,9 @@ export function buildStageUsageReport(input: {
   const pricingComplete = rows.length > 0 && rows.every((r) => r.pricingKnown) && totalComplete;
   const conservation = { status: quantitativeDefect ? 'DEFECT' : totalComplete ? 'BALANCED' : 'INSUFFICIENT_DATA', scope: 'reported receipt attribution; not independent source verification', metric };
   const dimensionCoverage = Object.fromEntries(tokenFields.map((key) => [key, { known: rows.filter((r) => r[key] !== null).length, unknown: rows.filter((r) => r[key] === null).length + expectedMissing.length }]));
-  return { schema: 'stage-usage-1', sourceKind: input.sourceKind, sourcePath: input.sourcePath, runId: input.runId, metric: compatible ? metric : 'incompatible-metrics',
-    rows, verdict: conservation.status, complete: totalComplete && witnessComplete && pricingComplete,
+  const routing = projectRoutingProvenance(input);
+  return { routingProvenance: routing.report, schema: 'stage-usage-1', sourceKind: input.sourceKind, sourcePath: input.sourcePath, runId: input.runId, metric: compatible ? metric : 'incompatible-metrics',
+    rows: rows.map(row => ({ ...row, ...(routing.stageFields.get(row.evidenceKey ?? '') ?? { plannedModel: null, plannedModelSource: 'not-recorded', probeId: null }) })), verdict: conservation.status, complete: totalComplete && witnessComplete && pricingComplete,
     knownRunTotalTokens: known, knownAccountedTokens: accounted, knownUnaccountedTokens: unaccounted,
     stageTokensSum: accounted !== null && doubled !== null ? accounted + doubled : null, doubleAttributedTokens: doubled,
     runTotalTokens: totalComplete ? known : null, sourceVerifiedTotalTokens: witnessComplete && totalComplete ? known : null,