@dzhechkov/harness-core 0.8.46 → 0.8.48

package/src/run-records.ts

@@ -13,11 +13,28 @@
  * Pure: payload in, verdict out. The CLI owns paths, the append, the read-back and the exit code.
  */
 
+import { createHash } from 'node:crypto';
 import { matchCodexRollouts } from './codex-rollouts.js';
 import type { CodexRollout } from './codex-rollouts.js';
-import { redactTrainingPayload } from './feature-adr-checkpoints.js';
+import { fnv1a64, redactTrainingPayload } from './feature-adr-checkpoints.js';
 import { validateExperimentEnvelope } from './feature-adr-envelope.js';
 
+// Capture contract: ordered named fields, with absent distinct from explicit null.
+// Kept private at producer/reader boundaries; both use this exact sha256 representation.
+function capturedPayload(evidence: Record<string, unknown>): string {
+  const value = (v: unknown) => v === undefined ? { absent: true } : v;
+  const receipts = Array.isArray(evidence['receipts']) ? evidence['receipts'] : [];
+  return JSON.stringify([
+    ...['schema', 'sessionId', 'turnId', 'sourcePath', 'matchBasis', 'capturedFrom', 'capturedTo', 'model', 'cwd', 'reportedTotalBasis', 'inputCacheSemantics'].map((k) => [k, value(evidence[k])]),
+    ['owner', ...['runId', 'taskId', 'stage', 'attempt', 'role'].map((k) => [k, value((evidence['owner'] as Record<string, unknown> | undefined)?.[k])])],
+    receipts.map((raw) => {
+      const r = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw as Record<string, unknown> : {}; const t = r['totals'] as Record<string, unknown> | undefined;
+      return [...['key', 'responseId', 'turnId', 'turnIndex', 'timestamp', 'payloadDigest', 'source'].map((k) => [k, value(r[k])]),
+        ['totals', ...['input', 'output', 'cachedInput', 'cachedWrite', 'reasoning', 'total'].map((k) => [k, value(t?.[k])])]];
+    }),
+  ]);
+}
+
 /** Structural — a caller passes `cost-scoring.ts`'s `ModelPricing`; kept local so `run-records.ts`
  *  does not have to import `cost-scoring.ts` just to name a type.
  *
@@ -86,6 +103,44 @@ export function parseModelSpec(spec: unknown): ParsedModelSpec | null {
   return null;
 }
 
+/** Internal shared ledger authority resolver; not a package-public barrel API.
+ * Capture/source values are comparison targets and never participate in claimant resolution. */
+export function resolveLedgerModelProvenance(row: Readonly<Record<string, unknown>>) {
+  const diagnostics: string[] = [];
+  const canonicalFamily = (v: string) => v === 'openai' ? 'codex' : v;
+  const direct = typeof row['model'] === 'string' && row['model'].length <= 128 && /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)?$/.test(row['model']) ? row['model'] : null;
+  if (row['model'] != null && direct === null) diagnostics.push('model-invalid-direct');
+  const family = typeof row['family'] === 'string' && SPEC_PART.test(row['family']) ? row['family'] : null;
+  if (row['family'] != null && family === null) diagnostics.push('model-invalid-family');
+  const specs: ParsedModelSpec[] = []; const familyHints: string[] = [];
+  for (const key of ['coder', 'reviewer']) {
+    const raw = row[key]; if (raw == null) continue;
+    if (raw === 'codex' || raw === 'claude') { familyHints.push(raw); continue; }
+    const spec = parseModelSpec(raw);
+    const parts = typeof raw === 'string' ? raw.trim().split(':') : [];
+    if (!spec || !SPEC_PART.test(spec.model) || (parts[0] === 'claude' && parts.length !== 2)) {
+      diagnostics.push('model-invalid-executor:' + key); continue;
+    }
+    specs.push(spec); familyHints.push(spec.family);
+  }
+  const models = new Set(specs.map((v) => v.model)); const families = new Set(familyHints);
+  if (models.size > 1 || families.size > 1) diagnostics.push('model-executor-conflict');
+  const unique = models.size === 1 ? specs[0]! : null;
+  if (direct !== null && unique && direct !== unique.model) diagnostics.push('model-direct-executor-conflict');
+  if (family !== null && [...families].some((v) => canonicalFamily(family) !== v)) diagnostics.push('model-family-conflict');
+  const declaredProvenance = row['modelProvenance'];
+  const validProvenance = new Set(['caller-recorded', 'executor-spec', 'provider-reported', 'dispatcher-reported', 'probed-request', 'not-recorded']);
+  if (declaredProvenance != null && (typeof declaredProvenance !== 'string' || !validProvenance.has(declaredProvenance))) diagnostics.push('model-invalid-provenance');
+  if (declaredProvenance === 'executor-spec' && (!unique || (direct !== null && direct !== unique.model))) diagnostics.push('model-provenance-conflict');
+  if (declaredProvenance != null && declaredProvenance !== 'executor-spec' && declaredProvenance !== 'not-recorded' && direct === null) diagnostics.push('model-provenance-conflict');
+  const conflict = diagnostics.some((d) => /invalid|conflict/.test(d));
+  const model = conflict ? null : direct ?? unique?.model ?? null;
+  if (model === null && !conflict) diagnostics.push('model-not-recorded');
+  const resolvedFamily = family ?? (families.size === 1 ? [...families][0]! : null);
+  return { model, family: resolvedFamily, modelProvenance: model === null ? 'not-recorded' : direct !== null
+    ? typeof declaredProvenance === 'string' ? declaredProvenance : 'caller-recorded' : 'executor-spec', diagnostics };
+}
+
 /** measurement-integrity FR-5/FR-6: enrichment the WRITER supplies at write time — the rollout logs
  *  it already read (I/O lives in the CLI; this stays pure) and the price table snapshot. Absent
  *  entirely ⇒ zero behavior change from before this feature (NFR-1). */
@@ -93,6 +148,9 @@ export interface LedgerEnrichInput {
   /** Parsed Codex rollout logs for the window the CLI read — usually every rollout from the days the
    *  window spans. Pure data; the CLI is the one that walked `~/.codex/sessions`. */
   readonly rollouts?: readonly CodexRollout[];
+  readonly rolloutId?: string;
+  readonly turnId?: string;
+  readonly discoveryDiagnostics?: readonly string[];
   /** The stage's own time window — usually [the previous ledger row's `ts`, this write's `ts`], or
    *  an explicit `--window-from/--window-to`. Omitted ⇒ no rollout match is even attempted. */
   readonly window?: { readonly from: string; readonly to: string };
@@ -492,32 +550,29 @@ export function decideRecordWrite(input: {
     // one that already has a token figure, is left untouched. The loose `/codex/i` check below only
     // decides whether this row is WORTH TRYING at all.
     const tokensIsNull = stamped['tokens'] === null;
-    const looksCodexFamily = isCodexFamily(stamped['coder']) || isCodexFamily(stamped['reviewer']);
-    if (tokensIsNull && looksCodexFamily) {
-      // measurement-integrity fix-round-1/F4 (Codex r1 HIGH #4): the matcher REQUIRES a reliable
-      // model, parsed the same way FR-7's price lookup parses one — never `/codex/i` alone. If
-      // `coder`/`reviewer` do not resolve to exactly ONE codex model between them (a bare `'codex'`
-      // with no model at all, or the two fields naming DIFFERENT codex models), the matcher is never
-      // even called with an unreliable/omitted model filter — a lone rollout in the window would
-      // otherwise be accepted as `'one'` on time+cwd alone and its tokens misattributed to the wrong
-      // model's stage.
-      const codexModels = new Set(
-        [parseModelSpec(stamped['coder']), parseModelSpec(stamped['reviewer'])]
-          .filter((s): s is ParsedModelSpec => s !== null && s.family === 'codex')
-          .map((s) => s.model),
-      );
-      if (codexModels.size !== 1) {
+    const looksCodexFamily = isCodexFamily(stamped['coder']) || isCodexFamily(stamped['reviewer']) || stamped['family'] === 'codex' || stamped['family'] === 'openai';
+    if (enrich.discoveryDiagnostics?.length) {
+      stamped['usageDiagnostics'] = enrich.discoveryDiagnostics;
+      stamped['tokensSource'] = 'codex-rollout:source-discovery-unavailable';
+    } else if ((tokensIsNull || enrich.rolloutId !== undefined || enrich.turnId !== undefined) && looksCodexFamily) {
+      // Use the same authority contract as the readonly source comparison and normalized report.
+      // A direct model or unique agreeing executor specs supply authority; a source never does.
+      const identity = resolveLedgerModelProvenance(stamped);
+      if (identity.model === null || !['codex', 'openai'].includes(identity.family ?? '')) {
         stamped['tokensSource'] = 'codex-rollout:no-model';
-      } else if (enrich.window !== undefined) {
-        const model = [...codexModels][0]!;
+        stamped['usageDiagnostics'] = [...(Array.isArray(stamped['usageDiagnostics']) ? stamped['usageDiagnostics'] : []), ...identity.diagnostics];
+      } else if (enrich.window !== undefined || enrich.rolloutId !== undefined || enrich.turnId !== undefined) {
+        const model = identity.model;
         const match = matchCodexRollouts(enrich.rollouts ?? [], {
-          from: enrich.window.from,
-          to: enrich.window.to,
+          ...(enrich.window !== undefined ? { from: enrich.window.from, to: enrich.window.to } : {}),
           model,
+          ...(enrich.rolloutId !== undefined ? { rolloutId: enrich.rolloutId } : {}),
+          ...(enrich.turnId !== undefined ? { turnId: enrich.turnId } : {}),
           ...(enrich.cwd !== undefined ? { cwd: enrich.cwd } : {}),
         });
         if (match.status === 'one') {
-          stamped['tokens'] = match.rollout.totals.total;
+          if (tokensIsNull || stamped['tokens'] === undefined) stamped['tokens'] = match.rollout.totals.total;
+          else if (stamped['tokens'] !== match.rollout.totals.total) stamped['usageDiagnostics'] = ['caller-source-total-mismatch'];
           const startMs = match.rollout.startedAt !== null ? Date.parse(match.rollout.startedAt) : NaN;
           const endMs = match.rollout.endedAt !== null ? Date.parse(match.rollout.endedAt) : NaN;
           // measurement-integrity fix-round-1/F6 (Codex r1 HIGH #6): fill-ONLY-null — an existing
@@ -528,9 +583,26 @@ export function decideRecordWrite(input: {
           }
           stamped['tokensSource'] = 'codex-rollout';
           stamped['rolloutId'] = match.rollout.id;
+          const found = match.rollout;
+          for (const [key, value] of Object.entries({ tokensTotal: found.totals.total, tokensIn: found.totals.input,
+            tokensOut: found.totals.output, tokensCacheRead: found.totals.cachedInput, tokensCacheWrite: found.totals.cachedWrite ?? null,
+            tokensReasoning: found.totals.reasoning, reportedTotalBasis: 'raw-inclusive', inputCacheSemantics: 'includes-cache-read-write',
+            usageDiagnostics: found.diagnostics ?? [] })) if (stamped[key] === undefined || stamped[key] === null) stamped[key] = value;
+          const receipts = (found.receipts ?? []).map((receipt) => ({ ...receipt, key: JSON.stringify([found.id, receipt.key]) }));
+          const usageEvidence: Record<string, unknown> = { schema: 'codex-rollout-scope-1', sessionId: found.id, turnId: found.turnId ?? null,
+            sourcePath: found.sourcePath ?? null, matchBasis: enrich.rolloutId !== undefined || enrich.turnId !== undefined ? 'exact' : 'legacy-window',
+            capturedFrom: found.startedAt, capturedTo: found.endedAt, receipts, model: found.model, cwd: found.cwd,
+            owner: Object.fromEntries(['runId', 'taskId', 'stage', 'attempt', 'role'].map((key) => [key, stamped[key] ?? null])),
+            reportedTotalBasis: 'raw-inclusive', inputCacheSemantics: 'includes-cache-read-write',
+            payloadDigest: fnv1a64(JSON.stringify(receipts.map((r) => [r.key, r.payloadDigest]))) };
+          usageEvidence['captureSha256'] = createHash('sha256').update(capturedPayload(usageEvidence)).digest('hex');
+          if (JSON.stringify(usageEvidence).length <= 16000) {
+            if (stamped['usageEvidence'] === undefined || stamped['usageEvidence'] === null) stamped['usageEvidence'] = usageEvidence;
+          } else stamped['usageDiagnostics'] = [...(Array.isArray(stamped['usageDiagnostics']) ? stamped['usageDiagnostics'] : []), 'source-scope-over-record-limit'];
+
         } else {
           // `none` or `ambiguous` — NFR-3: an explicit status, never a guessed number.
-          stamped['tokensSource'] = `codex-rollout:${match.status}`;
+          stamped['tokensSource'] = `codex-rollout:${enrich.rolloutId !== undefined || enrich.turnId !== undefined ? 'exact-' : ''}${match.status}`;
         }
       } else {
         // Eligible in principle (codex family, one reliable model, tokens null) but no window was
@@ -544,6 +616,7 @@ export function decideRecordWrite(input: {
     // above (a Claude row gets priced too; only tokens enrichment is codex-specific).
     if (enrich.prices !== undefined) {
       const modelIds = new Set<string>();
+      if (typeof stamped['model'] === 'string' && stamped['model'].trim()) modelIds.add(stamped['model'].trim());
       for (const v of [stamped['coder'], stamped['reviewer']]) {
         if (typeof v === 'string' && v.trim() !== '') modelIds.add(v.trim());
       }
@@ -566,7 +639,13 @@ export function decideRecordWrite(input: {
         if (price === null) unknown.push(modelId);
         else table[modelId] = { prompt: price.prompt, completion: price.completion, cachedInput: price.cachedInput, cacheCreation: price.cacheCreation };
       }
+      const matches = Object.fromEntries([...modelIds].map((id) => {
+        const parsed = parseModelSpec(id); const normalized = parsed?.family === 'claude' ? 'claude-' + parsed.model : parsed?.model ?? id;
+        const key = Object.keys(enrich.prices ?? {}).filter((k) => normalized.toLowerCase().startsWith(k)).sort((a,b) => b.length-a.length)[0] ?? null;
+        return [id, { tableKey: key, kind: key !== null && key === normalized && !key.includes('claude') ? 'exact' : key !== null ? 'family-estimate' : 'unknown' }];
+      }));
       const computedPrices = {
+        matches,
         snapshotAt: input.timestamp ?? null,
         table,
         ...(unknown.length > 0 ? { unknown } : {}),

package/src/setup-memory-deps.ts

@@ -0,0 +1,166 @@
+/** Exact consumer npm persistence and local native readiness. No ancestor/global installs. */
+import { existsSync, readFileSync, writeFileSync, rmSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { isDeepStrictEqual } from 'node:util';
+
+export const MEMORY_DEFAULTS = { agentdb: '3.0.0-alpha.20', 'better-sqlite3': '11.10.0' } as const;
+const names = Object.keys(MEMORY_DEFAULTS) as (keyof typeof MEMORY_DEFAULTS)[];
+const sections = ['dependencies', 'devDependencies', 'optionalDependencies'] as const;
+type Json = Record<string, any>;
+export interface MemoryDependencyResult {
+  readonly ready: boolean;
+  readonly changedManifest: boolean;
+  readonly changedLock: boolean;
+  readonly detail: string;
+}
+const object = (value: unknown): value is Json => value !== null && typeof value === 'object' && !Array.isArray(value);
+const same = (a: unknown, b: unknown) => isDeepStrictEqual(a, b);
+const bytes = (path: string) => existsSync(path) ? readFileSync(path, 'utf8') : null;
+function json(path: string): Json {
+  const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!object(value)) throw Error(`${path}: expected a JSON object`);
+  return value;
+}
+export function supportedMemoryVersion(name: keyof typeof MEMORY_DEFAULTS, value: unknown): value is string {
+  const number = '(?:0|[1-9][0-9]*)';
+  return typeof value === 'string' && new RegExp(name === 'agentdb'
+    ? `^(?:3\\.${number}\\.${number}|3\\.0\\.0-alpha\\.${number})$`
+    : `^11\\.${number}\\.${number}$`).test(value);
+}
+function installed(root: string, name: string): string | null {
+  const path = join(root, 'node_modules', name, 'package.json');
+  if (!existsSync(path)) return null;
+  const pkg = json(path);
+  if (pkg['name'] !== name || typeof pkg['version'] !== 'string') throw Error(`${name}: malformed installed package metadata`);
+  return pkg['version'];
+}
+function lockVersion(lock: Json | null, name: string): string | null {
+  const item = lock?.['packages']?.[`node_modules/${name}`] ?? lock?.['dependencies']?.[name];
+  return item?.version ?? null;
+}
+function selectVersions(root: string, pkg: Json, lock: Json | null): Record<string, string> {
+  for (const section of [...sections, 'peerDependencies']) {
+    if (pkg[section] !== undefined && !object(pkg[section])) throw Error(`package.json: malformed ${section}`);
+  }
+  const versions: Record<string, string> = {};
+  for (const name of names) {
+    if (Object.hasOwn(pkg['peerDependencies'] ?? {}, name)) throw Error(`${name}: peer declaration is outside exact persistence repair`);
+    const declared = sections.flatMap(section => Object.hasOwn(pkg[section] ?? {}, name) ? [pkg[section][name]] : []);
+    if (declared.some(value => !supportedMemoryVersion(name, value)) || new Set(declared).size > 1) throw Error(`${name}: conflicting or non-exact/unsupported saved declaration; original files preserved`);
+    if (declared.length) { versions[name] = declared[0]; continue; }
+    const local = installed(root, name), locked = lockVersion(lock, name);
+    if (local !== null) {
+      if (!supportedMemoryVersion(name, local)) throw Error(`${name}: unsupported installed-only version ${local}`);
+      if (locked !== null && locked !== local) throw Error(`${name}: installed-only and orphan lock versions conflict`);
+      versions[name] = local;
+    } else if (locked !== null) throw Error(`${name}: incomplete legacy lock-only state; original files preserved`);
+    else versions[name] = MEMORY_DEFAULTS[name];
+  }
+  return versions;
+}
+function persisted(pkg: Json, lock: Json | null, versions: Record<string, string>): boolean {
+  return names.every(name => pkg['devDependencies']?.[name] === versions[name]
+    && !Object.hasOwn(pkg['dependencies'] ?? {}, name) && !Object.hasOwn(pkg['optionalDependencies'] ?? {}, name)
+    && lockVersion(lock, name) === versions[name] && lock?.['packages']?.['']?.['devDependencies']?.[name] === versions[name]
+    && !Object.hasOwn(lock?.['packages']?.['']?.['dependencies'] ?? {}, name)
+    && !Object.hasOwn(lock?.['packages']?.['']?.['optionalDependencies'] ?? {}, name));
+}
+function protectedManifest(pkg: Json): Json {
+  const copy: Json = JSON.parse(JSON.stringify(pkg));
+  for (const section of sections) {
+    if (!object(copy[section])) continue;
+    for (const name of names) delete copy[section][name];
+    if (!Object.keys(copy[section]).length) delete copy[section];
+  }
+  return copy;
+}
+function resolutions(lock: Json | null): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (object(lock?.['packages'])) for (const [path, item] of Object.entries(lock['packages'])) {
+    if (path && !names.some(name => path === `node_modules/${name}`) && object(item) && typeof item['version'] === 'string') result[path] = item['version'];
+  }
+  else if (object(lock?.['dependencies'])) for (const [name, item] of Object.entries(lock['dependencies'])) {
+    if (!names.includes(name as keyof typeof MEMORY_DEFAULTS) && object(item) && typeof item['version'] === 'string') result[`node_modules/${name}`] = item['version'];
+  }
+  return result;
+}
+function npm(root: string, args: string[]): void {
+  execFileSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, {
+    cwd: root, timeout: 300000, maxBuffer: 8 * 1024 * 1024, stdio: 'pipe', shell: process.platform === 'win32',
+  });
+}
+export function probeMemoryNative(root: string): string | null {
+  try {
+    for (const name of names) if (installed(root, name) === null) return `${name}: local package missing`;
+    const script = `const {createRequire}=require('node:module'),fs=require('node:fs'),path=require('node:path');
+const root=process.argv[1],r=createRequire(path.join(root,'package.json')),local=fs.realpathSync(path.join(root,'node_modules'));
+const resolved=fs.realpathSync(r.resolve('better-sqlite3')); if(path.relative(local,resolved).startsWith('..'))throw Error('native module resolved outside project');
+const Sqlite=r('better-sqlite3'),db=new Sqlite(':memory:');try{if(db.prepare('SELECT 42 AS answer').get().answer!==42)throw Error('native SELECT failed');}finally{db.close();}
+process.stdout.write('native-sql-ready');`;
+    const output = execFileSync(process.execPath, ['-e', script, realpathSync(root)], { cwd: root, timeout: 60000, maxBuffer: 4 * 1024 * 1024, stdio: 'pipe', encoding: 'utf8' });
+    return output === 'native-sql-ready' ? null : 'native SQL readiness stdout not established';
+  } catch (error) { return `native SQLite unavailable: ${error instanceof Error ? error.message : String(error)}`; }
+}
+export function reconcileMemoryDependencies(projectRoot: string, repair = true): MemoryDependencyResult {
+  const pkgPath = join(projectRoot, 'package.json'), lockPath = join(projectRoot, 'package-lock.json');
+  const beforePkg = bytes(pkgPath), beforeLock = bytes(lockPath);
+  let stage = 'validate', repaired = false;
+  const result = (ready: boolean, detail: string): MemoryDependencyResult => ({ ready, changedManifest: bytes(pkgPath) !== beforePkg, changedLock: bytes(lockPath) !== beforeLock, detail });
+  try {
+    const pkg = beforePkg === null ? { name: 'dz-harness-project', private: true, version: '0.0.0' } : json(pkgPath);
+    const lock = beforeLock === null ? null : json(lockPath);
+    const versions = selectVersions(projectRoot, pkg, lock);
+    const localCurrent = names.every(name => installed(projectRoot, name) === versions[name]);
+    const savedCurrent = persisted(pkg, lock, versions);
+    if (!repair && (!savedCurrent || !localCurrent)) return result(false, 'saved/local dependency state is inconsistent; run setup to repair exact devDependencies');
+    const nativeBefore = localCurrent ? probeMemoryNative(projectRoot) : 'local package versions need repair';
+    if (!repair && nativeBefore) return result(false, nativeBefore);
+    if (!savedCurrent || !localCurrent) {
+      stage = 'npm persistence repair';
+      const protectedFields = protectedManifest(pkg), protectedLock = resolutions(lock);
+      try {
+        // npm can retain an existing optional declaration despite --save-dev. Selection and
+        // conflicts were validated above; normalize ONLY the two memory declarations first.
+        const canonical: Json = JSON.parse(JSON.stringify(pkg));
+        for (const section of sections) {
+          if (!object(canonical[section])) continue;
+          let removed = false;
+          for (const name of names) if (Object.hasOwn(canonical[section], name)) { delete canonical[section][name]; removed = true; }
+          if (removed && !Object.keys(canonical[section]).length) delete canonical[section];
+        }
+        canonical['devDependencies'] = { ...(canonical['devDependencies'] ?? {}), ...versions };
+        if (beforePkg === null || !same(canonical, pkg)) writeFileSync(pkgPath, JSON.stringify(canonical, null, 2) + '\n');
+        npm(projectRoot, ['install', ...names.map(name => `${name}@${versions[name]}`), '--save-dev', '--save-exact', '--no-audit', '--no-fund', '--loglevel=error']);
+        const after = json(pkgPath), afterLock = json(lockPath), afterResolutions = resolutions(afterLock);
+        if (!same(protectedManifest(after), protectedFields) || Object.entries(protectedLock).some(([path, version]) => afterResolutions[path] !== version)) {
+          throw Error('npm changed protected unrelated manifest fields/lock resolutions');
+        }
+        if (!persisted(after, afterLock, versions) || !names.every(name => installed(projectRoot, name) === versions[name])) throw Error('npm did not establish requested exact manifest/lock/local versions');
+        repaired = true;
+      } catch (error) {
+        // npm is not a whole-project transaction. Restore only protected manifest/lock files.
+        let changedProtected = false;
+        try {
+          const after = existsSync(pkgPath) ? json(pkgPath) : {};
+          const afterResolutions = resolutions(existsSync(lockPath) ? json(lockPath) : null);
+          changedProtected = !same(protectedManifest(after), protectedFields) || Object.entries(protectedLock).some(([path, version]) => afterResolutions[path] !== version);
+        } catch { changedProtected = true; }
+        if (changedProtected) {
+          if (beforePkg === null) rmSync(pkgPath, { force: true }); else writeFileSync(pkgPath, beforePkg);
+          if (beforeLock === null) rmSync(lockPath, { force: true }); else writeFileSync(lockPath, beforeLock);
+          throw Error(`protected manifest/lock restored after npm changed unrelated state; local modules may be incomplete: ${String(error)}`);
+        }
+        throw error;
+      }
+    } else if (repair && nativeBefore) {
+      stage = 'native rebuild'; npm(projectRoot, ['rebuild', 'better-sqlite3', '--no-audit', '--no-fund', '--loglevel=error']); repaired = true;
+    }
+    stage = 'native SQL probe';
+    const nativeError = probeMemoryNative(projectRoot);
+    if (nativeError) return result(false, `INCOMPLETE ${stage}: ${nativeError}; package.json ${bytes(pkgPath) === beforePkg ? 'unchanged' : 'changed'}, package-lock.json ${bytes(lockPath) === beforeLock ? 'unchanged' : 'changed'}`);
+    return result(true, `${repaired ? 'repaired exact devDependencies/local readiness' : 'already current exact devDependencies and native SQLite'}; package.json ${bytes(pkgPath) === beforePkg ? 'unchanged' : 'changed'}, package-lock.json ${bytes(lockPath) === beforeLock ? 'unchanged' : 'changed'}; ${names.map(name => `${name}@${versions[name]}`).join(', ')}; native SELECT 42 passed`);
+  } catch (error) {
+    return result(false, `INCOMPLETE ${stage}: ${error instanceof Error ? error.message : String(error)}; package.json ${bytes(pkgPath) === beforePkg ? 'unchanged' : 'changed'}, package-lock.json ${bytes(lockPath) === beforeLock ? 'unchanged' : 'changed'}`);
+  }
+}