simt-dev 0.7.0 → 0.8.0

package/src/journal.mjs

@@ -16,10 +16,14 @@
 //   - The plan row says `.simt-dev/journal/`, which predates the STATE_DIR
 //     rename (the same stale spelling survives in bench/probes.mjs comments).
 //     The journal lives under STATE_DIR like every other per-repo state.
-//   - Nothing under `.simt/` is journaled. The journal recording itself is
-//     recursion; the ledger, index and candidates are evidence and caches, and
-//     restoring those to an earlier byte-shape would corrupt R17 rather than
-//     repair anything. `journaledWriteFile` performs those writes unrecorded.
+//   - Nothing under `.simt/` is journaled, one named exception: the shim
+//     directory. The journal recording itself is recursion; the ledger, index
+//     and candidates are evidence and caches, and restoring those to an earlier
+//     byte-shape would corrupt R17 rather than repair anything. The shims are
+//     the opposite of that: git's routing points at them, and the undo that
+//     restores the routing must restore the shims with it (review 0003 Q22;
+//     ADR-122 moved them under STATE_DIR). `journaledWriteFile` performs the
+//     other writes unrecorded.
 //   - Only regular files. Symlinks carry no bytes for beforeBytes to hold, and
 //     the record shape is file bytes — pointer changes are reported by the
 //     command as before and are not undone. Removals are journaled as entries
@@ -37,16 +41,15 @@
 // a second `undo` naturally targets the set before it, and the untouched-check
 // refuses when the two sets overlap on a file the first undo already restored.
 
-import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { chmod, cp, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { chmod, cp, mkdir, readFile, readdir, rename, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, sep } from 'node:path';
-import { promisify } from 'node:util';
 
+import { noteEvent } from './state/events.mjs';
 import { STATE_DIR } from './name.mjs';
 import { LOCAL_DIR } from './state.mjs';
-
-const exec = promisify(execFile);
+import { HOOKS_DIR } from './hooks/shim.mjs';
+import { git, gitText } from './sys/git.mjs';
 
 const JOURNAL_DIR = join(LOCAL_DIR, 'journal');
 const JOURNAL_DIR_LEGACY = '.simt/journal';
@@ -129,8 +132,11 @@ export async function journaledWriteFile(root, acc, path, text, { mode } = {}) {
     throw new Error(`journal refuses a write outside the repository: ${path}`);
   }
   const before = await readOrNull(path);
-  // Internal state is written, not recorded — see the module header.
-  const internal = rel(root, path) === STATE_DIR || rel(root, path).startsWith(`${STATE_DIR}/`);
+  // Internal state is written, not recorded — see the module header, which
+  // names the shim directory as the one exception under STATE_DIR.
+  const r = rel(root, path);
+  const internal =
+    (r === STATE_DIR || r.startsWith(`${STATE_DIR}/`)) && r !== HOOKS_DIR && !r.startsWith(`${HOOKS_DIR}/`);
   await mkdir(dirname(path), { recursive: true });
   // tmp + rename, the way this module writes its own set files: a crash
   // mid-write leaves the old bytes in place, never a half-written file
@@ -202,7 +208,9 @@ export async function journaledRemoveFile(root, acc, path) {
   }
   const before = await readOrNull(path);
   if (before === null) return;
-  const internal = rel(root, path) === STATE_DIR || rel(root, path).startsWith(`${STATE_DIR}/`);
+  const r = rel(root, path);
+  const internal =
+    (r === STATE_DIR || r.startsWith(`${STATE_DIR}/`)) && r !== HOOKS_DIR && !r.startsWith(`${HOOKS_DIR}/`);
   await unlink(path);
   if (!internal) {
     acc.push(fileEntry(rel(root, path), before, null));
@@ -212,8 +220,7 @@ export async function journaledRemoveFile(root, acc, path) {
 /** Read one git config value in a repo, or null when unset. */
 export async function readGitValue(root, key) {
   try {
-    const { stdout } = await exec('git', ['config', '--get', key], { cwd: root });
-    return stdout.replace(/\n$/, '');
+    return await gitText(root, ['config', '--get', key]);
   } catch (error) {
     if (error.code === 1) return null;
     throw error;
@@ -236,9 +243,9 @@ export async function journaledGitConfig(root, acc, key, value) {
   const before = await readGitValue(root, key);
   if (before === value) return null;
   if (value === null) {
-    await exec('git', ['config', '--unset', key], { cwd: root });
+    await git(root, ['config', '--unset', key]);
   } else {
-    await exec('git', ['config', key, value], { cwd: root });
+    await git(root, ['config', key, value]);
   }
   const entry = { kind: 'git-config', key, before, after: value };
   acc.push(entry);
@@ -324,6 +331,61 @@ function coalesceEntries(acc) {
   });
 }
 
+/**
+ * Move the sets that predate the move into `.simt/local/journal` (review 0003
+ * Q19's fallback directory) into the current directory, and take the legacy
+ * directory down when the move empties it. While the current directory is
+ * absent, `listJournalSets` falls back to the legacy one; once it exists, the
+ * two are disjoint and the legacy sets are invisible to `undo` — a repo that
+ * accumulated history under the old path loses it on its first write after the
+ * move (plan 0005 H3). `commitJournal` is the only writer, so the migration
+ * rides on it and heals on the next journal activity. Every legacy set
+ * predates every current set — the current directory is created by this
+ * writer — so the move cannot disturb recency order. A name present in both
+ * keeps both copies when the bytes differ: a set file is history, and a
+ * collision is not a reason to drop one of the two records. A crash mid-move
+ * splits the sets between the two directories; the move is idempotent, so the
+ * next call finishes it.
+ */
+async function migrateLegacyJournal(root) {
+  const legacy = join(root, JOURNAL_DIR_LEGACY);
+  let names;
+  try {
+    names = await readdir(legacy);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return;
+  }
+  const dir = join(root, JOURNAL_DIR);
+  await mkdir(dir, { recursive: true });
+  for (const name of names) {
+    // Sets, `.undone.json` history and `.undoing.json` markers all end in
+    // `.json`; a stray file of any other kind keeps the directory in place.
+    if (!name.endsWith(SET_SUFFIX)) continue;
+    const from = join(legacy, name);
+    const to = join(dir, name);
+    try {
+      await stat(to);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      await rename(from, to);
+      continue;
+    }
+    // The name is taken: equal bytes are a duplicate of the same set (drop the
+    // legacy copy); differing bytes are a collision (keep both — the current
+    // copy shadows the legacy one in the listing).
+    const [a, b] = await Promise.all([readFile(from), readFile(to)]);
+    if (a.equals(b)) await unlink(from);
+  }
+  // `rmdir` fails when the directory is not empty, which is exactly the
+  // safety: a stray file the move does not take keeps the directory.
+  try {
+    await rmdir(legacy);
+  } catch (error) {
+    if (error.code !== 'ENOTEMPTY' && error.code !== 'EEXIST') throw error;
+  }
+}
+
 /**
  * Persist a run's set. Writes nothing when the run changed nothing, so the
  * last set on disk is always the last run that wrote.
@@ -331,6 +393,7 @@ function coalesceEntries(acc) {
  * @returns {Promise<string|null>} the set id (file name), or null
  */
 export async function commitJournal(root, command, acc, { at = Date.now() } = {}) {
+  await migrateLegacyJournal(root);
   const entries = coalesceEntries(acc);
   if (entries.length === 0) return null;
   await ignoreJournal(root);
@@ -341,6 +404,14 @@ export async function commitJournal(root, command, acc, { at = Date.now() } = {}
   const tmp = join(dir, `${id}.tmp-${process.pid}`);
   await writeFile(tmp, body, 'utf8');
   await rename(tmp, join(dir, id));
+  // The log is the record; the journal set is what `undo` restores from. Written after the
+  // set, so the event describes what landed rather than what was intended (Q73).
+  await noteEvent(root, {
+    kind: 'write.committed',
+    subject: command,
+    tree: null,
+    data: { entries: entries.length, paths: entries.map((entry) => entry.path) },
+  });
   return id;
 }
 
@@ -365,7 +436,10 @@ export async function journalHygiene(root) {
 
 /** Set ids newest-first, undone sets excluded. */
 export async function listJournalSets(root) {
-  // The pre-move directory is a fallback for one release (review 0003 Q19).
+  // The pre-move directory is a fallback for one release (review 0003 Q19);
+  // the sets in it move into the current directory on the next write
+  // (`migrateLegacyJournal`, plan 0005 H3), so the fallback only serves a
+  // repo that has not written since the move.
   let names;
   try {
     names = await readdir(join(root, JOURNAL_DIR));
@@ -459,9 +533,7 @@ function entryBytes(entry) {
 /** Restore one entry: bytes and permission bits for files, the value for config. */
 async function restoreEntry(root, entry) {
   if (entry.kind === 'git-config') {
-    await exec('git', entry.before === null ? ['config', '--unset', entry.key] : ['config', entry.key, entry.before], {
-      cwd: root,
-    });
+    await git(root, entry.before === null ? ['config', '--unset', entry.key] : ['config', entry.key, entry.before]);
     return;
   }
   const abs = join(root, entry.path);
@@ -541,5 +613,7 @@ export async function undoLastJournalSet(root) {
   const [id] = await listJournalSets(root);
   if (!id) return { empty: true };
   const result = await undoJournalSet(root, id);
+  // The set is gone from disk, so the log is now the only record it existed (Q73).
+  await noteEvent(root, { kind: 'write.undone', subject: id, data: { restored: result?.restored?.length ?? 0 } });
   return { set: id, ...result };
 }

package/src/kernel/card.mjs

@@ -22,7 +22,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { ECOSYSTEMS } from '../projection/manifest.mjs';
+import { cardBuilds, cardFocused, cardFallbacks, ecosystemGateRows, evalTemplate, matches } from '../ecosystem/records.mjs';
 import { resolveNodeRunner, runScript } from '../ecosystem/node-runner.mjs';
 
 /**
@@ -53,59 +53,35 @@ const VERBS = CARD_VERBS;
 const DROP_ORDER = ['format', 'typecheck', 'lint', 'build'];
 
 /**
- * Build commands for ecosystems whose build entrypoint is not a package script. Keyed by
- * a marker fact or stack tag, whichever the ecosystem is identified by. `npm` is handled
- * before this table, because a Node repository states its own build script and stating it
- * again here would be a second answer to the same question.
+ * Build commands for ecosystems whose build entrypoint is not a package script. The rows are
+ * the records' `card.build` facet, in first-match-wins order; `npm` is handled before this
+ * table, because a Node repository states its own build script and stating it again here
+ * would be a second answer to the same question.
  */
-const BUILDS = [
-  { fact: 'has-cargo-toml', command: 'cargo build' },
-  { fact: 'has-go-mod', command: 'go build ./...' },
-  { fact: 'has-nuget', command: 'dotnet build' },
-  { fact: 'has-swift-package', command: 'swift build' },
-  { fact: 'has-mix', command: 'mix compile' },
-  { stack: 'gradle', command: './gradlew build' },
-];
+function buildRows(root) {
+  return cardBuilds(root);
+}
 
 /**
- * One focused-test template per path kind. Entries are ordered, and the FIRST match wins,
- * so a repository that carries more than one marker gets the more specific template:
- * `has-uv-lock` before `has-pyproject`, `has-android-manifest` before the plain `gradle`
- * tag, `has-deno-config` before the Node fallback. A duplicate template for the same path
- * kind would be two answers, and the second is the wrong one.
+ * One focused-test template per path kind. The rows are the records' `card.focused` facet,
+ * in first-match-wins order: a repository that carries more than one marker gets the more
+ * specific template — `has-uv-lock` before `has-pyproject`, `has-android-manifest` before
+ * the plain `gradle` tag, `has-deno-config` before the Node fallback. A duplicate template
+ * for the same path kind would be two answers, and the second is the wrong one.
+ *
+ * The Node row is the one whose shape depends on the repo's own runner: a repository whose
+ * test script is vitest or jest takes a file argument through the script; one with no such
+ * script gets the built-in runner, which is the only answer that needs nothing installed to
+ * already be true. `<manager> test -- <file>` is the ADR-010 shape (never `npx`) — that
+ * choice is the template's `dynamic` form in the record, resolved by `evalTemplate`.
  */
-const FOCUSED = [
-  { kind: 'Android', when: (s, f) => f.has('has-android-manifest'), template: () => './gradlew :{module}:testDebugUnitTest --tests {class}' },
-  { kind: 'JVM', when: (s) => s.has('gradle'), template: () => './gradlew test --tests {class}' },
-  { kind: 'Maven', when: (s, f) => f.has('has-maven-pom'), template: () => './mvnw test -Dtest={class}' },
-  { kind: 'Go package', when: (s, f) => f.has('has-go-mod'), template: () => 'go test ./{pkg} -run {Test}' },
-  { kind: 'Rust', when: (s, f) => f.has('has-cargo-toml'), template: () => 'cargo test {name}' },
-  { kind: 'Python', when: (s, f) => f.has('has-uv-lock'), template: () => 'uv run -m pytest {file}::{test}' },
-  { kind: 'Python', when: (s, f) => f.has('has-pyproject') || f.has('has-requirements'), template: () => 'pytest {file}::{test}' },
-  { kind: '.NET', when: (s, f) => f.has('has-nuget'), template: () => 'dotnet test --filter {test}' },
-  { kind: 'Swift', when: (s, f) => f.has('has-swift-package'), template: () => 'swift test --filter {test}' },
-  { kind: 'Deno', when: (s, f) => f.has('has-deno-config'), template: () => 'deno test {file}' },
-  { kind: 'Ruby', when: (s, f) => f.has('has-gemfile'), template: () => 'bundle exec rspec {file}' },
-  { kind: 'Dart', when: (s, f) => f.has('has-pubspec'), template: () => 'dart test {file}' },
-  { kind: 'Elixir', when: (s, f) => f.has('has-mix'), template: () => 'mix test {file}' },
-  {
-    kind: 'Node',
-    when: (s) => s.has('node'),
-    // The repo's own runner decides the shape. A repository whose test script is vitest
-    // or jest takes a file argument through the script; one with no such script gets the
-    // built-in runner, which is the only answer that needs nothing installed to already
-    // be true. `<manager> test -- <file>` is the ADR-010 shape (never `npx`).
-    template: (s, f, scripts, runner) => {
-      const test = scripts?.test ?? '';
-      if (!/vitest|jest/.test(test)) return 'node --test {file}';
-      const run = runner?.run ?? 'npm';
-      return `${run} test -- {file}`;
-    },
-  },
-];
+function focusedRows(root) {
+  return cardFocused(root);
+}
 
 /**
- * Verbs for ecosystems the gate table does not seed, used by the card alone.
+ * Verbs for ecosystems the gate table does not seed, used by the card alone. The rows are
+ * the records' `card.fallback` facet.
  *
  * Python is the case, and it is not an oversight that the tool seeds no Python gate: the
  * runner genuinely varies (uv, poetry, tox, nox, a project wrapper), so a seeded gate would
@@ -116,10 +92,9 @@ const FOCUSED = [
  * test. Without a lockfile the card names the plain runner, which is what the python
  * profile assumes when it says "no `pytest.skip`".
  */
-const CARD_FALLBACKS = [
-  { when: (s, f) => f.has('has-uv-lock'), commands: { test: 'uv run -m pytest' } },
-  { when: (s, f) => f.has('has-pyproject') || f.has('has-requirements'), commands: { test: 'pytest' } },
-];
+function fallbackRows(root) {
+  return cardFallbacks(root);
+}
 
 /** A non-empty string, or null. Guards JSON that is present but not a command. */
 function text(value) {
@@ -165,7 +140,7 @@ async function readScripts(root) {
  * repository has declared nothing. The last is the same table the tool seeds gates from,
  * so the card and the gate list cannot name two different commands for one repository.
  */
-function resolveVerb(verb, { manifest, facts, stack, scripts, runner }) {
+function resolveVerb(verb, { manifest, facts, stack, scripts, runner, root }) {
   const declared = text(manifest?.gates?.commands?.[verb]);
   if (declared) return declared;
 
@@ -179,20 +154,19 @@ function resolveVerb(verb, { manifest, facts, stack, scripts, runner }) {
 
   if (verb === 'build') {
     if (text(scripts?.build)) return runScript(runner?.id ?? 'npm', 'build');
-    for (const row of BUILDS) {
-      if (row.fact && facts.has(row.fact)) return row.command;
-      if (row.stack && stack.has(row.stack)) return row.command;
+    for (const row of buildRows(root)) {
+      if (matches(row.condition, { facts, stack })) return row.command;
     }
     return null;
   }
 
-  for (const eco of ECOSYSTEMS) {
+  for (const eco of ecosystemGateRows(root)) {
     if (!facts.has(eco.fact)) continue;
     const command = text(eco.commands?.[verb]);
     if (command) return command;
   }
-  for (const row of CARD_FALLBACKS) {
-    if (!row.when(stack, facts, scripts)) continue;
+  for (const row of fallbackRows(root)) {
+    if (!matches(row.condition, { facts, stack })) continue;
     const command = text(row.commands?.[verb]);
     if (command) return command;
   }
@@ -246,17 +220,17 @@ export async function commandCard({ root, manifest = null, stack = [], facts = [
 
   const lines = [];
   for (const verb of VERBS) {
-    const command = resolveVerb(verb, { manifest, facts: factSet, stack: stackSet, scripts, runner: effective });
+    const command = resolveVerb(verb, { manifest, facts: factSet, stack: stackSet, scripts, runner: effective, root });
     if (command) lines.push({ label: verb, command, verb });
   }
-  for (const entry of FOCUSED) {
-    if (!entry.when(stackSet, factSet, scripts)) continue;
+  for (const entry of focusedRows(root)) {
+    if (!matches(entry.condition, { facts: factSet, stack: stackSet })) continue;
     // One template per path kind: `has-uv-lock` and `has-pyproject` both match a uv repo,
     // and two Python lines would be two answers with the second one wrong.
     if (lines.some((l) => l.kind === entry.kind)) continue;
     lines.push({
       label: `focused test (${entry.kind})`,
-      command: entry.template(stackSet, factSet, scripts, effective),
+      command: evalTemplate(entry.template, { scripts, runner: effective }),
       kind: entry.kind,
       verb: 'focused',
     });

package/src/kernel/checks.mjs

@@ -9,14 +9,11 @@
 // index has the edges (R21). A direction still has to be named before the prose
 // can leave, or the line would say Enforced and nothing would be enforcing it.
 
-import { execFile } from 'node:child_process';
 import { readFile, stat } from 'node:fs/promises';
 import { relative, resolve, sep } from 'node:path';
-import { promisify } from 'node:util';
 
 import { CLI } from '../name.mjs';
-
-const exec = promisify(execFile);
+import { git, gitPaths } from '../sys/git.mjs';
 
 export const CHECK_MARKER = 'simt-check';
 
@@ -360,8 +357,7 @@ function exempt(rel, prefixes) {
 
 async function tracked(root) {
   try {
-    const { stdout } = await exec('git', ['ls-files', '-z'], { cwd: root });
-    return stdout.split('\0').filter((p) => p !== '');
+    return await gitPaths(root, ['ls-files']);
   } catch {
     return null;
   }
@@ -370,8 +366,7 @@ async function tracked(root) {
 async function workDiff(root) {
   let text = '';
   try {
-    const { stdout } = await exec('git', ['diff', '--no-ext-diff', '--unified=0', 'HEAD'], { cwd: root, maxBuffer: 8 * 1024 * 1024 });
-    text = stdout;
+    text = await git(root, ['diff', '--no-ext-diff', '--unified=0', 'HEAD'], { maxBuffer: 8 * 1024 * 1024 });
   } catch (error) {
     if (error.code === 'ENOENT') return null;
     text = typeof error.stdout === 'string' ? error.stdout : '';
@@ -379,8 +374,7 @@ async function workDiff(root) {
   const files = parseDiff(text);
   let untracked = [];
   try {
-    const { stdout } = await exec('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd: root });
-    untracked = stdout.split('\0').filter((p) => p !== '');
+    untracked = await gitPaths(root, ['ls-files', '--others', '--exclude-standard']);
   } catch {
     return { files };
   }

package/src/lease.mjs

@@ -25,7 +25,7 @@ export const LEASE_FILE = localRel('leases.json');
 const LEASE_FILE_LEGACY = '.simt/leases.json';
 
 /** The schema the file is written with; a reader that does not know it refuses. */
-const LEASE_SCHEMA = 1;
+const LEASE_SCHEMA = 2;
 
 /**
  * How long a claim lives when the caller does not say.
@@ -35,6 +35,89 @@ const LEASE_SCHEMA = 1;
  */
 export const DEFAULT_TTL_SECONDS = 3600;
 
+/**
+ * A v1 record in the v2 shape.
+ *
+ * v1 stored `{path, session, harness, expiresAt}`; v2 stores a resource, a holder, a
+ * fencing token and an acquisition time (Q74). The reader accepts both because a claim
+ * file written by the previous release is still a claim the hook must honour, and
+ * refusing it would silently un-lease every held path on upgrade.
+ */
+export function toV2(entry) {
+  if (entry !== null && typeof entry === 'object' && entry.resource !== undefined && entry.holder !== undefined) {
+    return entry;
+  }
+  // `...entry` keeps the fields a caller put on its own claim - a slice claim carries
+  // `kind: 'slice'` and the slice id - which the schema does not name but must not drop.
+  return {
+    ...entry,
+    resource: { kind: 'path', id: entry.path },
+    holder: { session: entry.session, harness: entry.harness ?? null },
+    fence: Number.isInteger(entry.fence) ? entry.fence : 1,
+    acquiredAt: typeof entry.acquiredAt === 'number' ? entry.acquiredAt : null,
+    expiresAt: entry.expiresAt,
+  };
+}
+
+/**
+ * The v2 record flattened into the fields every reader of this tool already uses.
+ *
+ * Keeping `path`, `session`, `harness` and `expiresAt` on the in-memory entry is not
+ * backwards compatibility theatre: the hook, the command and four call sites compare
+ * those fields, and rewriting all of them to reach through `resource.id` would be a
+ * second change riding on a schema change.
+ */
+export function flattenLease(entry) {
+  const v2 = toV2(entry);
+  return {
+    ...v2,
+    path: v2.resource.id,
+    session: v2.holder.session,
+    harness: v2.holder.harness ?? null,
+    expiresAt: v2.expiresAt,
+  };
+}
+
+/** A record that is worth honouring, or null. A bad expiry would hold a path forever. */
+function normaliseLease(entry) {
+  if (entry === null || typeof entry !== 'object') return null;
+  const v2 = entry.resource !== undefined ? entry : toV2(entry);
+  const id = v2?.resource?.id;
+  const session = v2?.holder?.session;
+  if (typeof id !== 'string' || typeof session !== 'string' || !Number.isFinite(v2.expiresAt)) return null;
+  if (v2.resource.kind !== 'path' && v2.resource.kind !== 'dir') return null;
+  return flattenLease(v2);
+}
+
+/**
+ * Whether a claim covers a repository-relative path.
+ *
+ * A `dir` claim covers everything under it, which is what makes "this session owns
+ * `src/index/`" one claim instead of forty (Q74). The prefix test includes the separator
+ * so `src/index` does not cover `src/indexer`.
+ */
+export function leaseCovers(lease, rel) {
+  const resource = toV2(lease).resource;
+  if (resource.kind === 'dir') return rel === resource.id || rel.startsWith(`${resource.id}/`);
+  return rel === resource.id;
+}
+
+/**
+ * The store the lease commands read and write through.
+ *
+ * A file today; a remote store and a server clock later (Q74). Everything above this line
+ * is a function of the records, not of the file, so the second implementation changes
+ * where `read` and `write` point and nothing else.
+ */
+export function fileLeaseStore(root) {
+  return {
+    root,
+    read: () => readLeases(root),
+    write: (leases) => writeLeases(root, leases),
+    withLock: (fn) => withLeaseLock(root, fn),
+  };
+}
+
 /**
  * The one spelling a path has for lease matching: repository-relative, symlinks
  * resolved, case-folded when the repository's git compares case-insensitively, or
@@ -105,10 +188,7 @@ export async function readLeases(root) {
     }
     // A malformed entry is dropped rather than trusted: an expiry that is not a number
     // would otherwise live forever, which is the opposite of what a TTL promises.
-    const leases = parsed.leases.filter(
-      (l) => l !== null && typeof l === 'object' && typeof l.path === 'string' &&
-        typeof l.session === 'string' && Number.isFinite(l.expiresAt),
-    );
+    const leases = parsed.leases.map(normaliseLease).filter((l) => l !== null);
     return { path, leases, error: null };
   } catch (error) {
     return { path, leases: [], error: `${LEASE_FILE} is not valid JSON (${error.message})` };
@@ -136,8 +216,23 @@ export function activeLeases({ leases } = { leases: [] }, now = Date.now()) {
  */
 export async function writeLeases(root, leases) {
   const path = join(root, LEASE_FILE);
-  const sorted = [...leases].sort((a, b) => a.path.localeCompare(b.path));
-  const body = `${JSON.stringify({ schemaVersion: LEASE_SCHEMA, leases: sorted }, null, 2)}\n`;
+  // v2 on disk: a resource, a holder and a fence, sorted by resource id so two writes of
+  // the same claims produce the same bytes (Q74).
+  const records = leases
+    .map(toV2)
+    .map((l) => ({
+      // Additive, not a rename: the pre-edit hook, the slice claim and the tests read
+      // `path` and `session` straight off the file, and a v2 writer that stopped writing
+      // them would break every one of those readers at once.
+      ...l,
+      resource: l.resource,
+      holder: { session: l.holder.session, harness: l.holder.harness ?? null },
+      fence: l.fence,
+      acquiredAt: l.acquiredAt,
+      expiresAt: l.expiresAt,
+    }))
+    .sort((a, b) => a.resource.id.localeCompare(b.resource.id));
+  const body = `${JSON.stringify({ schemaVersion: LEASE_SCHEMA, leases: records }, null, 2)}\n`;
   await mkdir(dirname(path), { recursive: true });
   // Atomic against a concurrent writer and a concurrent reader: a half-written
   // claim file fails closed for every edit (review 0003 Q20).