@ngockhoale/ukit 3.0.8 → 3.0.10

package/src/core/memory/projectIdentity.js

@@ -0,0 +1,266 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
+import { buildUserPaths } from '../userPaths.js';
+
+/**
+ * Host-owned stable project identity resolver (M01-01, SPEC §5 FR-001..003).
+ *
+ * Identity authority is a USER-LEVEL registry at
+ * `~/.ukit/storage/projects/registry.json` — user-level because uninstall
+ * removes the project `.ukit/` tree. `package.json.name` is never an identity
+ * authority; it only feeds the alias index (display-name collisions degrade
+ * to `ambiguous`, never a guess).
+ *
+ * Registry shape (SPEC §7):
+ *   {schemaVersion:1,
+ *    projects:{<projectId>:{roots:[realpath], gitCommonDirs:[abs],
+ *              aliases:[name], createdAt, updatedAt}},
+ *    aliasIndex:{<name>:[<projectId>|'ambiguous']}}
+ */
+
+const REGISTRY_SCHEMA_VERSION = 1;
+
+function registryPathFor(homeDir) {
+  const { storageRoot } = buildUserPaths(homeDir === undefined ? {} : { homeDir });
+  return path.join(storageRoot, 'projects', 'registry.json');
+}
+
+function emptyRegistry() {
+  return { schemaVersion: REGISTRY_SCHEMA_VERSION, projects: {}, aliasIndex: {} };
+}
+
+/**
+ * Tolerant registry read. Missing → empty registry. Corrupt → null sentinel
+ * (caller degrades to `unverified`; the file is NEVER overwritten on read).
+ */
+async function readRegistry(regPath) {
+  let data;
+  try {
+    data = await readJsonIfExists(regPath);
+  } catch {
+    return null; // corrupt JSON — degrade, never throw, never rewrite
+  }
+  if (data === null) return emptyRegistry();
+  if (typeof data !== 'object' || typeof data.projects !== 'object' || data.projects === null) {
+    return null;
+  }
+  if (typeof data.aliasIndex !== 'object' || data.aliasIndex === null) {
+    data.aliasIndex = {};
+  }
+  return data;
+}
+
+async function realpathOrNull(target) {
+  try {
+    return await fs.realpath(target);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the git common dir for a root: `.git` dir → itself; `.git` file
+ * (`gitdir: <p>`) → `<p>/commondir` (linked worktrees share the main common
+ * dir). Returns null when there is no git binding.
+ */
+async function resolveGitCommonDir(projectRoot) {
+  const gitPath = path.join(projectRoot, '.git');
+  let stat;
+  try {
+    stat = await fs.stat(gitPath);
+  } catch {
+    return null;
+  }
+
+  if (stat.isDirectory()) {
+    return await realpathOrNull(gitPath);
+  }
+  if (!stat.isFile()) return null;
+
+  let content;
+  try {
+    content = await fs.readFile(gitPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const match = content.match(/^gitdir:\s*(.+)$/m);
+  if (!match) return null;
+  const gitDir = path.resolve(projectRoot, match[1].trim());
+
+  let commonDirRel;
+  try {
+    commonDirRel = (await fs.readFile(path.join(gitDir, 'commondir'), 'utf8')).trim();
+  } catch {
+    commonDirRel = '';
+  }
+  const commonDir = commonDirRel ? path.resolve(gitDir, commonDirRel) : gitDir;
+  return await realpathOrNull(commonDir);
+}
+
+async function aliasesFor(projectRoot, realRoot) {
+  const names = new Set();
+  const base = path.basename(realRoot ?? projectRoot);
+  if (base) names.add(base);
+  const pkg = await readJsonIfExists(path.join(projectRoot, 'package.json')).catch(() => null);
+  if (typeof pkg?.name === 'string' && pkg.name.trim() !== '') {
+    names.add(pkg.name.trim());
+  }
+  return [...names];
+}
+
+function findByRoot(registry, realRoot) {
+  for (const [projectId, entry] of Object.entries(registry.projects)) {
+    if (Array.isArray(entry?.roots) && entry.roots.includes(realRoot)) {
+      return projectId;
+    }
+  }
+  return null;
+}
+
+function findByGitCommonDir(registry, commonDir) {
+  if (!commonDir) return null;
+  for (const [projectId, entry] of Object.entries(registry.projects)) {
+    if (Array.isArray(entry?.gitCommonDirs) && entry.gitCommonDirs.includes(commonDir)) {
+      return projectId;
+    }
+  }
+  return null;
+}
+
+function findByAlias(registry, aliases) {
+  const hits = new Set();
+  for (const name of aliases) {
+    const entry = registry.aliasIndex?.[name];
+    if (entry === 'ambiguous') {
+      hits.add('ambiguous');
+      continue;
+    }
+    if (Array.isArray(entry)) {
+      for (const id of entry) hits.add(id);
+    } else if (typeof entry === 'string' && entry) {
+      hits.add(entry);
+    }
+  }
+  return hits;
+}
+
+function mintProjectId(realRoot) {
+  const digest = crypto
+    .createHash('sha256')
+    .update(`${realRoot}|${crypto.randomBytes(16).toString('hex')}`)
+    .digest('hex');
+  return `prj_${digest.slice(0, 16)}`;
+}
+
+function indexAliases(registry, projectId, aliases) {
+  for (const name of aliases) {
+    const current = registry.aliasIndex[name];
+    if (current === 'ambiguous') continue;
+    const list = Array.isArray(current) ? current : (typeof current === 'string' && current ? [current] : []);
+    if (!list.includes(projectId)) list.push(projectId);
+    registry.aliasIndex[name] = list.length > 1 ? 'ambiguous' : list;
+  }
+}
+
+/**
+ * Resolve the stable project identity for `projectRoot`.
+ *
+ * Order: (1) canonical realpath in registry roots; (2) git common-dir binding
+ * (linked worktree → same project); (3) alias index — multiple distinct
+ * projectIds → ambiguous deny; (4) mint (default) under file lock, or
+ * `unverified` when `mint:false`.
+ *
+ * @returns {Promise<{projectId: string|null, source: 'registry'|'git-common-dir'|'alias'|'unverified', ambiguous: boolean}>}
+ */
+export async function resolveProjectIdentity(projectRoot, { homeDir, mint = true } = {}) {
+  const unverified = { projectId: null, source: 'unverified', ambiguous: false };
+  const regPath = registryPathFor(homeDir);
+
+  const registry = await readRegistry(regPath);
+  if (registry === null) return unverified; // corrupt — never overwrite on read
+
+  const realRoot = (await realpathOrNull(projectRoot)) ?? path.resolve(projectRoot);
+
+  const byRoot = findByRoot(registry, realRoot);
+  if (byRoot) {
+    return {
+      projectId: byRoot,
+      source: 'registry',
+      ambiguous: false,
+      aliases: Array.isArray(registry.projects[byRoot]?.aliases)
+        ? registry.projects[byRoot].aliases.filter((a) => typeof a === 'string')
+        : [],
+    };
+  }
+
+  const commonDir = await resolveGitCommonDir(projectRoot);
+  const byGit = findByGitCommonDir(registry, commonDir);
+  if (byGit) {
+    return {
+      projectId: byGit,
+      source: 'git-common-dir',
+      ambiguous: false,
+      aliases: Array.isArray(registry.projects[byGit]?.aliases)
+        ? registry.projects[byGit].aliases.filter((a) => typeof a === 'string')
+        : [],
+    };
+  }
+
+  const aliases = await aliasesFor(projectRoot, realRoot);
+  // Alias is a weak display-name signal only: any hit for a different root
+  // denies (ambiguous) rather than letting a same-named repo inherit an id.
+  const aliasHits = findByAlias(registry, aliases);
+  if (aliasHits.size > 0) {
+    return { projectId: null, source: 'alias', ambiguous: true };
+  }
+
+  if (!mint) return unverified;
+
+  // Mint under the registry file lock; re-check inside the critical section so
+  // a concurrent minter cannot produce two ids for the same root.
+  const minted = await withFileLock(regPath, async () => {
+    const fresh = await readRegistry(regPath);
+    if (fresh === null) return null; // became corrupt between read and lock
+    const existing = findByRoot(fresh, realRoot)
+      ?? (commonDir ? findByGitCommonDir(fresh, commonDir) : null);
+    if (existing) return existing;
+
+    const now = new Date().toISOString();
+    const projectId = mintProjectId(realRoot);
+    fresh.projects[projectId] = {
+      roots: [realRoot],
+      gitCommonDirs: commonDir ? [commonDir] : [],
+      aliases,
+      createdAt: now,
+      updatedAt: now,
+    };
+    indexAliases(fresh, projectId, aliases);
+    await writeJson(regPath, fresh);
+    return projectId;
+  });
+
+  if (minted === undefined || minted === null) return unverified;
+  return { projectId: minted, source: 'registry', ambiguous: false, aliases };
+}
+
+/**
+ * lookupRegisteredProjectId(legacyId, { homeDir } = {}) → string | 'ambiguous' | null
+ * Read-only registry lookup for migration alias-collision checks (M04-01):
+ * a legacy project id that IS a registered projectId resolves to itself;
+ * an alias resolves to its bound projectId; 'ambiguous' when the alias is
+ * contested; null when unknown. Never mints, never writes.
+ */
+export async function lookupRegisteredProjectId(legacyId, { homeDir } = {}) {
+  if (typeof legacyId !== 'string' || !legacyId) return null;
+  const registry = await readRegistry(registryPathFor(homeDir));
+  if (registry === null) return null; // corrupt registry → unknown, never guess
+  if (registry.projects[legacyId]) return legacyId;
+  const aliasEntry = registry.aliasIndex?.[legacyId];
+  if (aliasEntry === 'ambiguous') return 'ambiguous';
+  if (Array.isArray(aliasEntry) && aliasEntry.length === 1) return aliasEntry[0];
+  if (Array.isArray(aliasEntry) && aliasEntry.length > 1) return 'ambiguous';
+  if (typeof aliasEntry === 'string' && aliasEntry) return aliasEntry;
+  return null;
+}

package/src/core/memory/recordIndex.js

@@ -0,0 +1,178 @@
+// TASK-003 (M04-J1b) — bounded in-process inverted index for v2 record
+// retrieval (SPEC §5 FR-006/FR-007, §8). Token → postings map; the index
+// narrows candidates, `eligible()` in policy.js still gates — the index
+// accelerates, never decides. In-memory only, never persisted.
+//
+// createIndex({maxRecords?, maxPostings?}) → {build, query, invalidate, stats}
+//   build(records, {generation})  — rebuild postings; records beyond
+//                                   maxRecords/maxPostings are evicted,
+//                                   lowest base-score first.
+//   query(tokens, {limit})        — ranked [{record, id, score}] using the
+//                                   same token-overlap semantics as
+//                                   retrieval.js scoreRecord; [] when the
+//                                   index is empty, stale, or tokens empty.
+//   invalidate(generation)        — record a newer store generation; a
+//                                   mismatch drops postings so no stale
+//                                   hits are served until the next build.
+//   stats()                       — {generation, records, postings, evicted}
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',
+  'this', 'that', 'it', 'as', 'by', 'be', 'use', 'using', 'implement', 'fix', 'task',
+  'cần', 'và', 'là', 'cho', 'một', 'những', 'dùng',
+]);
+
+const RECORD_TYPE_WEIGHTS = Object.freeze({
+  project_rule: 7, derived_fact: 5, procedure: 5, episode: 3,
+});
+
+export function normalize(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s./:_-]/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function tokenize(text) {
+  return normalize(text)
+    .split(/\s+/)
+    .filter((token) => token && !STOPWORDS.has(token) && token.length > 1);
+}
+
+function recordTokens(record) {
+  return new Set(tokenize(`${record.text ?? ''} ${record.provenance ?? ''}`));
+}
+
+// Identical scoring to retrieval.js scoreRecord — keep in sync (parity test).
+export function scoreRecordTokens(record, queryTokens) {
+  const typeWeight = RECORD_TYPE_WEIGHTS[record.type] ?? 1;
+  if (queryTokens.length === 0) {
+    return typeWeight * Math.max(0.1, record.confidence ?? 1);
+  }
+  const tokens = recordTokens(record);
+  let matched = 0;
+  for (const token of queryTokens) {
+    if (tokens.has(token)) matched += 1;
+  }
+  if (matched === 0) return 0;
+  const recencyBonus = record.created_at > 0
+    ? Math.min(1, record.created_at / Date.now())
+    : 0;
+  return typeWeight * matched * Math.max(0.1, record.confidence ?? 1) + recencyBonus;
+}
+
+// Base score used only for eviction order (lowest evicted first): type
+// weight × confidence, then oldest first — mirrors the ranking inputs so
+// eviction drops what would rank last anyway.
+function evictionKey(record) {
+  const typeWeight = RECORD_TYPE_WEIGHTS[record.type] ?? 1;
+  return typeWeight * Math.max(0.1, record.confidence ?? 1);
+}
+
+export function createIndex({ maxRecords = 10000, maxPostings = 50000 } = {}) {
+  let records = [];
+  let postings = new Map(); // token → number[] (indexes into records)
+  let postingsCount = 0;
+  let generation = 0;
+  let builtGeneration = -1; // generation the postings actually reflect
+  let evicted = 0;
+
+  function stats() {
+    return {
+      generation,
+      records: records.length,
+      postings: postingsCount,
+      evicted,
+    };
+  }
+
+  function dropRecord(idx) {
+    for (const token of recordTokens(records[idx])) {
+      const list = postings.get(token);
+      if (!list) continue;
+      const pos = list.indexOf(idx);
+      if (pos !== -1) {
+        list.splice(pos, 1);
+        postingsCount -= 1;
+      }
+      if (list.length === 0) postings.delete(token);
+    }
+    records[idx] = null;
+    evicted += 1;
+  }
+
+  function enforceBounds() {
+    if (records.length <= maxRecords && postingsCount <= maxPostings) return;
+    // Rank survivors by eviction priority; drop lowest until within bounds.
+    const order = records
+      .map((record, idx) => ({ record, idx }))
+      .filter((entry) => entry.record !== null)
+      .sort((a, b) => evictionKey(a.record) - evictionKey(b.record)
+        || (a.record.created_at ?? 0) - (b.record.created_at ?? 0));
+    for (const { idx } of order) {
+      if (records.filter(Boolean).length <= maxRecords && postingsCount <= maxPostings) break;
+      dropRecord(idx);
+    }
+    // Compact: rebuild postings against a dense records array.
+    records = records.filter(Boolean);
+    postings = new Map();
+    postingsCount = 0;
+    records.forEach((record, idx) => {
+      for (const token of recordTokens(record)) {
+        let list = postings.get(token);
+        if (!list) postings.set(token, (list = []));
+        list.push(idx);
+        postingsCount += 1;
+      }
+    });
+  }
+
+  function build(input, { generation: gen = 0 } = {}) {
+    records = Array.isArray(input) ? [...input] : [];
+    postings = new Map();
+    postingsCount = 0;
+    evicted = 0;
+    records.forEach((record, idx) => {
+      for (const token of recordTokens(record)) {
+        let list = postings.get(token);
+        if (!list) postings.set(token, (list = []));
+        list.push(idx);
+        postingsCount += 1;
+      }
+    });
+    enforceBounds();
+    generation = gen;
+    builtGeneration = gen;
+  }
+
+  function invalidate(newGeneration) {
+    generation = Number.isInteger(newGeneration) && newGeneration >= 0 ? newGeneration : generation;
+    if (generation !== builtGeneration) {
+      // Store moved on — never serve postings built against an older doc.
+      postings = new Map();
+      postingsCount = 0;
+      records = [];
+    }
+  }
+
+  function query(queryTokens, { limit = 10 } = {}) {
+    if (!Array.isArray(queryTokens) || queryTokens.length === 0) return [];
+    if (builtGeneration !== generation || records.length === 0) return [];
+    const seen = new Set();
+    for (const token of queryTokens) {
+      for (const idx of postings.get(token) ?? []) seen.add(idx);
+    }
+    if (seen.size === 0) return [];
+    return [...seen]
+      .map((idx) => ({ record: records[idx], score: scoreRecordTokens(records[idx], queryTokens) }))
+      .filter((entry) => entry.score > 0)
+      .sort((a, b) => b.score - a.score
+        || (b.record.created_at ?? 0) - (a.record.created_at ?? 0)
+        || String(b.record.text ?? '').localeCompare(String(a.record.text ?? '')))
+      .slice(0, limit)
+      .map((entry) => ({ record: entry.record, id: entry.record.id, score: entry.score }));
+  }
+
+  return { build, query, invalidate, stats };
+}

package/src/core/memory/recordStore.js

@@ -1,16 +1,35 @@
 // Record-document store core — SPEC §3 / FR-007.
 // Path-agnostic read/write of the v2 records document
-// ({ schemaVersion: 2, records: [...] }) so both the project store
-// (storeV2.js) and the user store (userMemory.js) share one implementation.
-// Writes go through fileOps.writeJson (tmp+rename).
+// ({ schemaVersion: 2, generation: int, tombstones: [...], records: [...] })
+// so both the project store (storeV2.js) and the user store (userMemory.js)
+// share one implementation. Writes go through fileOps.writeJson (tmp+rename,
+// fsync before rename).
 
-import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { copyFileRawExclusive, readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
 import { normalizeRecord } from './records.js';
 
 const SCHEMA_VERSION = 2;
+const TOMBSTONE_MAX = 512;
+
+/**
+ * Thrown by mutateRecordStore when the on-disk doc is corrupt or carries an
+ * unsupported schema. `code` is 'store-corrupt' or 'unsupported-schema';
+ * the message carries the quarantine path, never file content.
+ */
+export class StoreCorruptError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'StoreCorruptError';
+    this.code = code;
+  }
+}
 
 export const PATCHABLE_FIELDS = ['type', 'scope', 'text', 'provenance', 'confidence',
-  'valid_until', 'status', 'project_id', 'meta', 'source_fingerprint'];
+  'valid_until', 'status', 'project_id', 'meta', 'source_fingerprint', 'revision',
+  'supersedes', 'superseded_by', 'reason', 'evidence', 'trust_tier'];
 
 export function isRawRecord(input) {
   return input && typeof input === 'object' && typeof input.id === 'string'
@@ -18,18 +37,26 @@ export function isRawRecord(input) {
 }
 
 /**
- * readRecordStore(recordsPath) → { records, invalidSkipped }
- * Tolerant: missing file → {records:[]}; unparseable → {records:[], invalidSkipped:1};
- * per-record normalizeRecord skip.
+ * readRecordStore(recordsPath) → { records, invalidSkipped, state }
+ * Typed states (M01-03): 'missing' (ENOENT/null doc), 'corrupt' (parse
+ * failure), 'empty' (parsed, zero usable records), 'ok' (≥1 record).
+ * Tolerant: per-record normalizeRecord skip. Read path never writes —
+ * corrupt bytes stay byte-identical.
  */
 export async function readRecordStore(recordsPath) {
   let doc;
   try {
     doc = await readJsonIfExists(recordsPath);
   } catch {
-    return { records: [], invalidSkipped: 1 };
+    return { records: [], invalidSkipped: 1, state: 'corrupt', generation: 0, tombstones: [] };
+  }
+  if (!doc) return { records: [], invalidSkipped: 0, state: 'missing', generation: 0, tombstones: [] };
+
+  // Newer/foreign schema: never yield records — a newer build may have written
+  // fields this build cannot roundtrip (SPEC §14).
+  if (typeof doc.schemaVersion !== 'number' || doc.schemaVersion > SCHEMA_VERSION) {
+    return { records: [], invalidSkipped: 0, state: 'unsupported-schema', generation: 0, tombstones: [] };
   }
-  if (!doc) return { records: [], invalidSkipped: 0 };
 
   const rawRecords = Array.isArray(doc.records) ? doc.records : [];
   const records = [];
@@ -39,21 +66,47 @@ export async function readRecordStore(recordsPath) {
     if (normalized) records.push(normalized);
     else invalidSkipped += 1;
   }
-  return { records, invalidSkipped };
+  const generation = Number.isInteger(doc.generation) && doc.generation >= 0 ? doc.generation : 0;
+  const tombstones = Array.isArray(doc.tombstones) ? doc.tombstones : [];
+  return { records, invalidSkipped, state: records.length > 0 ? 'ok' : 'empty', generation, tombstones };
 }
 
 /**
  * writeRecordStore(recordsPath, records) → void
  * Atomic write; drops unrecoverable entries.
+ *
+ * Generation is strictly monotonic (SPEC §5 FR-005): the persisted value is
+ * `max(supplied, on-disk prior) + 1`, so a caller that passes a stale or
+ * backwards generation can never regress the doc. The prior re-read is cheap
+ * (one stat+parse) and keeps this function safe even when invoked outside
+ * mutateRecordStore's lock.
  */
-export async function writeRecordStore(recordsPath, records) {
+export async function writeRecordStore(recordsPath, records, { generation, tombstones } = {}) {
   const normalized = (Array.isArray(records) ? records : [])
     .map((raw) => normalizeRecord(raw))
     .filter(Boolean);
+  const prior = await readRecordStore(recordsPath);
+  const supplied = Number.isInteger(generation) && generation >= 0 ? generation : 0;
+  const baseGeneration = Math.max(supplied, prior.generation);
+  const baseTombstones = tombstones === undefined ? prior.tombstones : tombstones;
+  const nextTombstones = (Array.isArray(baseTombstones) ? baseTombstones : []).slice(-TOMBSTONE_MAX);
   await writeJson(recordsPath, {
     schemaVersion: SCHEMA_VERSION,
+    generation: baseGeneration + 1,
+    tombstones: nextTombstones,
     records: normalized,
-  });
+  }, { fsync: true });
+}
+
+/**
+ * isTombstoned(doc, {id, fingerprint}) → boolean
+ * `doc` is a readRecordStore result or any `{ tombstones }` shape. A record
+ * matches when its id OR fingerprint equals a tombstone entry.
+ */
+export function isTombstoned(doc, { id, fingerprint } = {}) {
+  const tombstones = Array.isArray(doc?.tombstones) ? doc.tombstones : [];
+  return tombstones.some((t) => (id !== undefined && t.id === id)
+    || (fingerprint !== undefined && t.fingerprint === fingerprint));
 }
 
 /**
@@ -85,16 +138,54 @@ export function applyRecordPatch(records, id, patch = {}) {
  * Serializes a read-modify-write cycle on the records document under the
  * shared file lock (fileOps.withFileLock) so concurrent add/update flows —
  * in-process or across hook processes — never lose each other's writes.
- * `mutate(records)` returns { result, records } to persist, or null to skip
- * the write (e.g. id not found). Throws when the lock wait expires: a
- * silently dropped mutation would corrupt caller state worse than an error.
+ * `mutate(records, prior)` returns:
+ *   - null → skip the write entirely (result null);
+ *   - { result } → skip the write but return `result` (typed no-op);
+ *   - { result, records, tombstones?, postWrite? } → persist records
+ *     (tombstones defaults to prior's), then run `postWrite()` inside the
+ *     same lock after the doc write (journal appends).
+ * Throws when the lock wait expires: a silently dropped mutation would
+ * corrupt caller state worse than an error.
  */
-export async function mutateRecordStore(recordsPath, mutate) {
+export async function mutateRecordStore(recordsPath, mutate, opts = {}) {
   const outcome = await withFileLock(recordsPath, async () => {
-    const { records } = await readRecordStore(recordsPath);
-    const mutation = await mutate(records);
+    const prior = await readRecordStore(recordsPath);
+    let { records } = prior;
+    if (prior.state === 'corrupt' || prior.state === 'unsupported-schema') {
+      const quarantinePath = await quarantineStoreFile(recordsPath);
+      if (prior.state === 'unsupported-schema') {
+        // Never proceed empty on a newer-schema doc — that would destroy data
+        // written by a newer build. No onCorrupt escape hatch.
+        throw new StoreCorruptError(
+          'unsupported-schema',
+          `mutateRecordStore: unsupported schema in ${recordsPath} — quarantined to ${quarantinePath}`,
+        );
+      }
+      if (opts.onCorrupt !== 'quarantine-empty') {
+        throw new StoreCorruptError(
+          'store-corrupt',
+          `mutateRecordStore: corrupt records doc ${recordsPath} — quarantined to ${quarantinePath}`,
+        );
+      }
+      // Explicit restore path: quarantine preserved the bytes; proceed empty.
+      records = [];
+    }
+    const mutation = await mutate(records, prior);
     if (!mutation) return null;
-    await writeRecordStore(recordsPath, mutation.records);
+    if (mutation.records !== undefined) {
+      // Generation contract: pass the generation read under THIS lock —
+      // writeRecordStore persists prior.generation + 1 (and clamps against
+      // the on-disk doc, so a stale caller can never regress it).
+      await writeRecordStore(recordsPath, mutation.records, {
+        generation: prior.generation,
+        tombstones: mutation.tombstones ?? prior.tombstones,
+      });
+      // Test-only crash-injection hook (TASK-002): UKIT_TEST_CRASH_AT=
+      // 'post-doc-write' kills the process after the doc rename but before
+      // postWrite (journal append), proving crash recovery never duplicates.
+      if (process.env.UKIT_TEST_CRASH_AT === 'post-doc-write') process.exit(1);
+      if (typeof mutation.postWrite === 'function') await mutation.postWrite();
+    }
     return mutation.result ?? null;
   });
   if (outcome === undefined) {
@@ -102,3 +193,25 @@ export async function mutateRecordStore(recordsPath, mutate) {
   }
   return outcome;
 }
+
+/**
+ * Copy the corrupt doc aside for manual review — never overwrite, never
+ * delete the original. Exclusive-create destination + 0600 mode (the copy
+ * may contain secrets — same boundary as the canonical store, SPEC §14).
+ * Best-effort: a failed copy still yields the error path, with the attempted
+ * path in the message.
+ */
+async function quarantineStoreFile(recordsPath) {
+  const quarantinePath = path.join(
+    path.dirname(recordsPath),
+    'quarantine',
+    `${path.basename(recordsPath)}-${Date.now()}.json`,
+  );
+  try {
+    await copyFileRawExclusive(recordsPath, quarantinePath);
+    await fs.chmod(quarantinePath, 0o600).catch(() => {});
+  } catch {
+    // Quarantine copy failed — still fail closed; the original stays untouched.
+  }
+  return quarantinePath;
+}