@davesheffer/hunch 1.45.1 → 1.46.0

package/dist/serve/writelock.js

@@ -13,7 +13,9 @@
  * equality and never by clock arithmetic (see core/procstart.ts). Where no token can
  * compare them (macOS, Windows, legacy records) a stale-looking lock whose live pid
  * belongs to a process CREATED after the lock's recorded `at` is taken over too: that
- * process cannot be the one that took it (issue #287). Removing a stale
+ * process cannot be the one that took it (issue #287). That creation-time check
+ * runs on macOS and Windows only; on linux `processStartedAt` returns null, so a
+ * tokenless live pid there is never taken over. Removing a stale
  * lock is itself serialized behind an exclusive `.reclaim` claim directory, because
  * judging and removing are two steps and two contenders can otherwise both "win"
  * (see `takeOver`).
@@ -22,7 +24,10 @@ import { hostname } from "node:os";
 import { randomBytes } from "node:crypto";
 import { closeSync, mkdirSync, openSync, readFileSync, rmSync, rmdirSync, statSync, writeSync } from "node:fs";
 import { join } from "node:path";
-import { heldLockNonces, judgeSameHostOwner, processStartedAt, selfStartToken, startTokenOf } from "../core/procstart.js";
+import { createdAfterLock, heldLockNonces, judgeSameHostOwner, processStartedAt, selfStartToken, startTokenOf } from "../core/procstart.js";
+/** Shared with jsonStore's `.rmw-lock` (core/procstart.ts); re-exported so this
+ *  module's surface is unchanged. */
+export { CREATED_AFTER_SLACK_MS } from "../core/procstart.js";
 /** Longest a write may hold the lock before another process may steal it: a put plus a
  *  git commit and push — seconds, not minutes. */
 export const STALE_AFTER_MS = 60_000;
@@ -33,10 +38,6 @@ export const ACQUIRE_TIMEOUT_MS = 10_000;
  *  crashed inside it. */
 export const CLAIM_STALE_MS = 10_000;
 const POLL_MS = 25;
-/** How much later than the lock's recorded `at` the pid's current process must
- *  have been created before it is proven not to be the owner. A genuine owner
- *  started BEFORE it took the lock; the slack only absorbs clock granularity. */
-export const CREATED_AFTER_SLACK_MS = 5_000;
 export class WriteLockTimeout extends Error {
     path;
     heldBy;
@@ -57,12 +58,19 @@ export function writeLockPath(hunchDir) {
 function readOwner(path) {
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (typeof parsed.pid !== "number" || typeof parsed.nonce !== "string")
+        // A missing nonce is not unreadable metadata: the pid still names a
+        // same-host owner, so it gets the live-pid judgement `.rmw-lock` gives it,
+        // never the age fallback that would steal a live writer's lock (#491).
+        // The pid check mirrors `.rmw-lock`'s: `kill(0|-n, 0)` signals a process
+        // group and always "succeeds" (a live wedge forever), and a fractional or
+        // huge pid throws (stolen even when fresh) — so such a record is unreadable
+        // and age decides.
+        if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid < 1)
             return undefined;
         return {
             pid: parsed.pid,
             host: typeof parsed.host === "string" ? parsed.host : "",
-            nonce: parsed.nonce,
+            ...(typeof parsed.nonce === "string" ? { nonce: parsed.nonce } : {}),
             at: typeof parsed.at === "string" ? parsed.at : "",
             ...(typeof parsed.start === "string" ? { start: parsed.start } : {}),
         };
@@ -104,9 +112,10 @@ function stealable(path, owner, now, token) {
     // and any skew between them would "prove" a live owner recycled and steal its
     // lock. Anything the token cannot settle stays "not proven".
     //
-    // The whole table lives in core/procstart.ts so this lock and jsonStore's
-    // `.rmw-lock` can never drift apart; "age" means it proved nothing and the
-    // fallback below governs, exactly as for a foreign host.
+    // The whole table, and the creation-time check for an "unproven" pid, live in
+    // core/procstart.ts so this lock and jsonStore's `.rmw-lock` apply one rule;
+    // "age" means it proved nothing and the fallback below governs, exactly as
+    // for a foreign host.
     if (owner && owner.host === hostname()) {
         const verdict = judgeSameHostOwner(owner, {
             alive: pidAlive,
@@ -117,21 +126,12 @@ function stealable(path, owner, now, token) {
             heldNonces: heldLockNonces,
         });
         if (verdict === "unproven")
-            return ageMs > STALE_AFTER_MS && createdAfterLock(owner, token);
+            return ageMs > STALE_AFTER_MS && createdAfterLock(owner, token.startedAt);
         if (verdict !== "age")
             return verdict === "stale";
     }
     return ageMs > STALE_AFTER_MS;
 }
-/** Is the process now holding the owner's pid provably newer than the lock?
- *  Unreadable either way means not proven, and a live pid keeps its lock. */
-function createdAfterLock(owner, token) {
-    const at = Date.parse(owner.at);
-    if (!Number.isFinite(at))
-        return false;
-    const started = (token.startedAt ?? processStartedAt)(owner.pid);
-    return started !== null && started > at + CREATED_AFTER_SLACK_MS;
-}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** The claim a contender must hold to REMOVE a stale lock. A sibling directory,
  *  created with the same exclusive `mkdir` the commit lock uses
@@ -277,6 +277,11 @@ export async function withWriteLock(hunchDir, fn, opts = {}) {
         // from, the file now protects another writer. The nonce is dropped in a
         // `finally` of its own, so a throw from the conditional remove can never
         // leave us vouching for a lock we no longer hold.
+        //
+        // DIFFERS from `.rmw-lock` on release: a readable record WITHOUT a nonce is
+        // left in place here (it is not ours — a legacy or foreign writer replaced
+        // our file), where `.rmw-lock` removes it. Only an unreadable record is
+        // removed unconditionally.
         try {
             const current = readOwner(path);
             if (!current || current.nonce === nonce)

package/dist/store/hunchStore.d.ts

@@ -4,6 +4,7 @@ import { type DB } from "./db.js";
 import { type Embedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { type RankingContext, type RankingQuery, type RankingWeights, type SlotOptions, type TaskSelection } from "../core/taskRanking.js";
+import { type WhyById } from "../core/whyRecord.js";
 import { type VetoTier } from "../core/strictgate.js";
 import { type DiffAnalysis, type DiffStatus } from "../extractors/diff.js";
 import type { CheckReport, CausalWhy, ImpactReport } from "../core/checkreport.js";
@@ -43,6 +44,8 @@ export interface WhyResult {
     constraints: Constraint[];
     symbols: Symbol[];
     components: Component[];
+    /** Set when the target is a record id (`dec_…`, `con_…`, …; issue #474). */
+    byId?: WhyById;
 }
 export interface FragileNode {
     id: string;
@@ -391,9 +394,17 @@ export declare class HunchStore {
         asOf?: string;
         canRead?: (record: unknown) => boolean;
     }): WhyResult;
+    /** Look a record up by id across the record kinds why() explains (public ∪ private
+     *  via recs(), narrowed by `canRead`). A decision carries its supersession chain.
+     *  With `asOf`, a record outside its valid window then is "no record", and only
+     *  chain links/neighbours already in effect then are shown. Status is the STORED
+     *  status, exactly as the path/symbol view prints it.
+     *  Neighbour ids the caller may not read are never printed. */
+    private whyRecord;
     /** Transitive blast radius: every symbol/component that (in)directly depends on
      *  `id`, via a recursive CTE over the edges graph (hunch_get_dependents). We
-     *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains. */
+     *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains,
+     *  plus `references` — the only edge YAML/Helm/Kustomize emit (issue #486). */
     getDependents(id: string, maxDepth?: number): Array<{
         id: string;
         depth: number;

package/dist/store/hunchStore.js

@@ -4,7 +4,7 @@
  *
  *   - reindex():        JSON  -> SQLite (rebuild the derived index + FTS)
  *   - search():         FTS5 ranked query (hunch_query)
- *   - why():            decisions/bugs/constraints explaining a path/symbol
+ *   - why():            decisions/bugs/constraints explaining a path/symbol, or one record by id
  *   - getDependents():  recursive-CTE blast radius over the call/dep graph
  *   - checkConstraints(): constraints whose scope matches a glob/path
  *   - bugLineage():     bugs matching a symptom/symbol + their lineage
@@ -26,6 +26,7 @@ import { normalizePath, rankTaskRecords, recordIdsOf, selectLatestTasks, selectT
 import { resolveTaskRankingMode } from "../core/taskRankingMode.js";
 import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
+import { WHY_GENERATED_ID, WHY_RECORD_ID } from "../core/whyRecord.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
 import { effectiveForbids, matchForbids } from "../core/constraintmatch.js";
 import { analyzeDiff, diffContentGaps } from "../extractors/diff.js";
@@ -1343,6 +1344,16 @@ export class HunchStore {
         // An absolute target (an agent's edit-payload path, verbatim) never matched
         // the repo-relative stored file paths below (issue #299).
         target = repoRelativeTarget(target, this.paths.root);
+        // A record id (every delivered brief line ends in `hunch_why("dec_…")`) resolves
+        // to that record directly (issue #474). With `asOf`, a record not in force then
+        // is "no record"; status stays as stored, like the path view (see whyRecord).
+        const lookup = WHY_RECORD_ID.test(target) ? this.whyRecord(target, opts.canRead, opts.asOf) : undefined;
+        if (lookup?.record)
+            return { target, decisions: [], bugs: [], constraints: [], symbols: [], components: [], byId: lookup };
+        // A miss is reported for a generated-shape id, or for any id on file that was not
+        // in force at `asOf` (issue #493); anything else resolves as before.
+        const byId = lookup && (WHY_GENERATED_ID.test(target) || (opts.asOf && this.whyRecord(target, opts.canRead).record))
+            ? lookup : undefined;
         const decisions = this.recs("decisions").filter(opts.canRead ?? (() => true));
         const bugs = this.recs("bugs").filter(opts.canRead ?? (() => true));
         const constraints = this.recs("constraints").filter(opts.canRead ?? (() => true));
@@ -1379,11 +1390,66 @@ export class HunchStore {
                 && inWindow(c.valid_from, c.valid_to, asOf)),
             symbols: matchedSymbols,
             components: components.filter((c) => c.paths.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))),
+            ...(byId ? { byId } : {}),
         };
     }
+    /** Look a record up by id across the record kinds why() explains (public ∪ private
+     *  via recs(), narrowed by `canRead`). A decision carries its supersession chain.
+     *  With `asOf`, a record outside its valid window then is "no record", and only
+     *  chain links/neighbours already in effect then are shown. Status is the STORED
+     *  status, exactly as the path/symbol view prints it.
+     *  Neighbour ids the caller may not read are never printed. */
+    whyRecord(id, canRead = () => true, asOf) {
+        const find = (kind) => this.recs(kind).find((r) => r.id === id && canRead(r));
+        // Decisions the caller may read that had taken effect by `asOf` (all when no asOf).
+        const decs = new Map(this.recs("decisions").filter((x) => canRead(x) && inWindow(x.valid_from, null, asOf)).map((x) => [x.id, x]));
+        const visible = (ref) => (ref && decs.has(ref) ? ref : null);
+        const existed = (instant) => !asOf || instant <= asOf;
+        let record = null;
+        switch (id.slice(0, id.indexOf("_"))) {
+            case "dec": {
+                const d = find("decisions");
+                if (!d || !inWindow(d.valid_from, d.valid_to, asOf))
+                    break;
+                // Stored status, as the path view prints it; asOf only hides neighbours not yet in effect.
+                const shown = { ...d, supersedes: visible(d.supersedes), superseded_by: visible(d.superseded_by) };
+                record = { kind: "decision", record: shown, chain: supersessionChain(shown, decs) };
+                break;
+            }
+            case "con": {
+                const c = find("constraints");
+                if (!c || !inWindow(c.valid_from, c.valid_to, asOf))
+                    break;
+                record = { kind: "constraint", record: { ...c, source_decision: visible(c.source_decision) } };
+                break;
+            }
+            case "bug": {
+                const b = find("bugs");
+                if (b)
+                    record = { kind: "bug", record: b };
+                break;
+            }
+            case "fnd": {
+                const f = find("findings");
+                if (f && existed(f.observed_at))
+                    record = { kind: "finding", record: f };
+                break;
+            }
+            // Not gated by asOf: the path view lists components regardless of asOf too.
+            // Findings stay gated by observed_at (the path view does not list findings).
+            case "cmp": {
+                const c = find("components");
+                if (c)
+                    record = { kind: "component", record: c };
+                break;
+            }
+        }
+        return { id, record, ...(asOf ? { asOf } : {}) };
+    }
     /** Transitive blast radius: every symbol/component that (in)directly depends on
      *  `id`, via a recursive CTE over the edges graph (hunch_get_dependents). We
-     *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains. */
+     *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains,
+     *  plus `references` — the only edge YAML/Helm/Kustomize emit (issue #486). */
     getDependents(id, maxDepth = 6) {
         return this.db.prepare(
         /* sql */ `
@@ -1392,7 +1458,7 @@ export class HunchStore {
         UNION
         SELECT e."from", up.depth + 1
         FROM edges e JOIN up ON e."to" = up.node
-        WHERE e.type IN ('calls','depends_on','imports','contains','implements') AND up.depth < ?
+        WHERE e.type IN ('calls','depends_on','imports','contains','implements','references') AND up.depth < ?
       )
       SELECT up.node AS id, MIN(up.depth) AS depth,
              COALESCE(s.name || ' @ ' || s.file, c.name, up.node) AS via
@@ -1434,7 +1500,7 @@ export class HunchStore {
         UNION
         SELECT e."from", up.depth + 1
         FROM edges e JOIN up ON e."to" = up.node
-        WHERE e.type IN ('calls','depends_on','imports','contains','implements') AND up.depth < ?
+        WHERE e.type IN ('calls','depends_on','imports','contains','implements','references') AND up.depth < ?
       )
       SELECT s.file AS file, s.name AS via, MIN(up.depth) AS depth
       FROM up JOIN symbols s ON s.id = up.node
@@ -2334,6 +2400,22 @@ function inWindow(valid_from, valid_to, asOf) {
         return false;
     return true;
 }
+/** A decision's supersedes/superseded_by chain over `decs` (the readable, already
+ *  in-effect decisions), oldest first, cycle-guarded. `d` is the record as shown. */
+function supersessionChain(d, decs) {
+    const seen = new Set([d.id]);
+    const back = [];
+    for (let cur = d.supersedes ? decs.get(d.supersedes) : undefined; cur && !seen.has(cur.id); cur = cur.supersedes ? decs.get(cur.supersedes) : undefined) {
+        seen.add(cur.id);
+        back.unshift(cur);
+    }
+    const fwd = [];
+    for (let cur = d.superseded_by ? decs.get(d.superseded_by) : undefined; cur && !seen.has(cur.id); cur = cur.superseded_by ? decs.get(cur.superseded_by) : undefined) {
+        seen.add(cur.id);
+        fwd.push(cur);
+    }
+    return [...back, d, ...fwd].map((x) => ({ id: x.id, status: x.status, title: x.title }));
+}
 function round(n) {
     return Math.round(n * 100) / 100;
 }

package/dist/store/jsonStore.d.ts

@@ -6,8 +6,11 @@ export declare const MAX_JSON_RECORD_BYTES: number;
 export declare const MAX_JSON_INDEX_BYTES: number;
 export declare const MAX_JSON_MANIFEST_BYTES: number;
 export declare const MAX_JSON_DIRECTORY_ENTRIES_PER_KIND = 100000;
+/** When the process now holding `pid` was created (wall-clock ms), or null. */
+type StartedAtProbe = (pid: number) => number | null;
 export declare class JsonStore {
     private readonly paths;
+    private readonly lockOpts;
     private _warnedForward;
     /** Memoized validated records per kind. loadAll() is on every read-path method
      *  (why/checkConstraints/fragility/assembleContext…), each of which previously
@@ -20,7 +23,13 @@ export declare class JsonStore {
     private readonly lexicalRoot;
     private readonly canonicalRoot;
     private readonly lexicalHunch;
-    constructor(paths: HunchPaths);
+    /** `lockOpts.startedAt` is an INTERNAL TEST SEAM, not API: it replaces the OS
+     *  creation-time probe of the `.rmw-lock` "unproven" rule so the suite can
+     *  drive it on linux, where the real probe reports nothing. Callers outside
+     *  this repo must leave it unset — `processStartedAt` is the only sound probe. */
+    constructor(paths: HunchPaths, lockOpts?: {
+        startedAt?: StartedAtProbe;
+    });
     private lstatOrMissing;
     private expectedCanonical;
     /** Require an ordinary, canonically-contained directory. Creation is one
@@ -117,11 +126,22 @@ export declare class JsonStore {
      *  overlay. Returns the number of files removed. Invalidates the memoized load. */
     dropAll(kind: EntityKind): number;
     /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
-     *  A record that still fails validation after migration is kept untouched (never
-     *  deleted) and counted as `skipped`, so migration can't lose data. The caller
-     *  bumps the manifest afterward. */
+     *  A record that still fails validation after migration (or whose migration
+     *  throws) is kept in its ORIGINAL shape (never deleted, never half-migrated) and
+     *  counted as `skipped`, so migration can't lose data. The caller stamps the
+     *  manifest at the returned `version`: SCHEMA_VERSION only when nothing was
+     *  skipped, else the FROM version, so a manual fix plus a rerun re-applies the
+     *  (idempotent) migrations to the skipped records instead of skipping them.
+     *  A bad record of a kind NO pending migration touches can't be fixed by a
+     *  rerun, so it is counted as `invalid` instead and doesn't hold the version. */
     persistMigration(): {
         migrated: number;
         skipped: number;
+        invalid: number;
+        version: number;
     };
+    /** Migrate + validate one raw record for persistMigration; a throwing migration
+     *  step counts as a failure, so the record stays in its original shape. */
+    private tryMigrate;
 }
+export {};

package/dist/store/jsonStore.js

@@ -8,10 +8,10 @@ import { randomBytes } from "node:crypto";
 import { hostname } from "node:os";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
-import { BASELINE_VERSION, migrateRaw, SCHEMA_VERSION } from "../core/migrate.js";
+import { BASELINE_VERSION, hasPendingMigration, migrateRaw, SCHEMA_VERSION } from "../core/migrate.js";
 import { writeFileAtomic } from "../core/io.js";
 import { readStoreArtifact } from "../core/storeArtifact.js";
-import { heldLockNonces, judgeSameHostOwner, selfStartToken, startTokenOf } from "../core/procstart.js";
+import { createdAfterLock, heldLockNonces, judgeSameHostOwner, processStartedAt, selfStartToken, startTokenOf } from "../core/procstart.js";
 /** High-cardinality collections (symbols, edges) are stored as a single
  *  index.json array — there can be thousands, and one file per edge would create
  *  enormous git noise. Curated, low-volume entities (components, decisions, bugs,
@@ -118,6 +118,7 @@ function readRmwOwnerOnce(lock) {
             host: parsed.host,
             ...(typeof parsed.nonce === "string" ? { nonce: parsed.nonce } : {}),
             ...(typeof parsed.start === "string" ? { start: parsed.start } : {}),
+            ...(typeof parsed.at === "string" ? { at: parsed.at } : {}),
         };
     }
     catch {
@@ -143,9 +144,14 @@ const RMW_CLAIM_STALE_MS = 10_000;
  *  The owner's recorded process-instance token settles that by string equality
  *  (core/procstart.ts); no clock is compared, because a lock's mtime and a start
  *  time come from different clocks and any skew would "prove" a live owner
- *  recycled. `readRmwOwner` stays FIRST: it throws on unsafe/hardlinked or
- *  oversized ownership metadata, and unsafe ownership never licenses removal. */
-function rmwLockIsStale(lock) {
+ *  recycled. Where no token exists (macOS, Windows) a live pid is "unproven",
+ *  and an AGED lock is still taken over once the OS proves the process now
+ *  holding that pid was created after the lock's recorded `at` (issue #457) —
+ *  the same `createdAfterLock` rule as the write lock. `startedAt` is
+ *  memoized per acquisition by the caller, because the OS probe spawns.
+ *  `readRmwOwner` stays FIRST: it throws on unsafe/hardlinked or oversized
+ *  ownership metadata, and unsafe ownership never licenses removal. */
+function rmwLockIsStale(lock, startedAt) {
     let stat;
     try {
         stat = lstatSync(lock);
@@ -157,9 +163,10 @@ function rmwLockIsStale(lock) {
     }
     const owner = readRmwOwner(lock);
     if (owner && owner.host === hostname()) {
-        // One shared table with src/serve/writelock.ts (core/procstart.ts), so the
-        // two locks can never drift apart; "age" means nothing was proven and the
-        // fallback below governs, exactly as for a foreign host.
+        // One shared table with src/serve/writelock.ts (core/procstart.ts), and one
+        // shared creation-time check for an "unproven" pid, so the two locks apply
+        // the same rule; "age" means nothing was proven and the fallback below
+        // governs, exactly as for a foreign host.
         const verdict = judgeSameHostOwner(owner, {
             alive: rmwPidAlive,
             self: selfStartToken(),
@@ -168,6 +175,8 @@ function rmwLockIsStale(lock) {
             selfPid: process.pid,
             heldNonces: heldLockNonces,
         });
+        if (verdict === "unproven")
+            return Date.now() - stat.mtimeMs > 10_000 && createdAfterLock(owner, startedAt);
         if (verdict !== "age")
             return verdict === "stale";
     }
@@ -210,7 +219,7 @@ function rmwLockIsStale(lock) {
  * so the race persists until every writer on the store is upgraded. Returns true
  * when the path may now be free.
  */
-function takeOverRmwLock(lock) {
+function takeOverRmwLock(lock, startedAt) {
     const claim = `${lock}.reclaim`;
     try {
         mkdirSync(claim);
@@ -229,7 +238,7 @@ function takeOverRmwLock(lock) {
         return false;
     }
     try {
-        if (!rmwLockIsStale(lock))
+        if (!rmwLockIsStale(lock, startedAt))
             return false; // re-judged from scratch under the claim
         rmSync(lock, { recursive: true, force: true });
         return true;
@@ -253,6 +262,7 @@ function unsafePath(path, reason) {
 }
 export class JsonStore {
     paths;
+    lockOpts;
     _warnedForward = false;
     /** Memoized validated records per kind. loadAll() is on every read-path method
      *  (why/checkConstraints/fragility/assembleContext…), each of which previously
@@ -265,8 +275,13 @@ export class JsonStore {
     lexicalRoot;
     canonicalRoot;
     lexicalHunch;
-    constructor(paths) {
+    /** `lockOpts.startedAt` is an INTERNAL TEST SEAM, not API: it replaces the OS
+     *  creation-time probe of the `.rmw-lock` "unproven" rule so the suite can
+     *  drive it on linux, where the real probe reports nothing. Callers outside
+     *  this repo must leave it unset — `processStartedAt` is the only sound probe. */
+    constructor(paths, lockOpts = {}) {
         this.paths = paths;
+        this.lockOpts = lockOpts;
         this.lexicalRoot = resolve(paths.root);
         this.canonicalRoot = realpathSync(this.lexicalRoot);
         this.lexicalHunch = resolve(paths.hunch);
@@ -666,6 +681,15 @@ export class JsonStore {
         const lock = join(directory.lexical, ".rmw-lock");
         const deadline = Date.now() + 2_000;
         const nonce = randomBytes(8).toString("hex");
+        // The creation-time probe spawns; ask it once per pid for this acquisition,
+        // not on every poll nor again under the takeover claim (as writelock.ts).
+        const createdAt = new Map();
+        const probe = this.lockOpts.startedAt ?? processStartedAt;
+        const startedAt = (pid) => {
+            if (!createdAt.has(pid))
+                createdAt.set(pid, probe(pid));
+            return createdAt.get(pid);
+        };
         for (;;) {
             try {
                 mkdirSync(lock);
@@ -676,10 +700,11 @@ export class JsonStore {
                 // writer may exceed the stale-age heuristic while serializing a large
                 // index; its PID must prevent a second writer from taking over. The
                 // process-instance token (when this platform has one) is what lets a
-                // successor tell that PID apart from a recycled one.
+                // successor tell that PID apart from a recycled one; without one, `at`
+                // lets it prove the pid's current process was created after this lock.
                 try {
                     const start = selfStartToken();
-                    writeFileAtomic(join(lock, "owner.tmp.json"), JSON.stringify({ pid: process.pid, host: hostname(), nonce, ...(start !== null ? { start } : {}) }));
+                    writeFileAtomic(join(lock, "owner.tmp.json"), JSON.stringify({ pid: process.pid, host: hostname(), nonce, at: new Date().toISOString(), ...(start !== null ? { start } : {}) }));
                 }
                 catch (error) {
                     try {
@@ -694,7 +719,7 @@ export class JsonStore {
             catch (error) {
                 if (error.code !== "EEXIST")
                     throw error;
-                if (rmwLockIsStale(lock) && takeOverRmwLock(lock))
+                if (rmwLockIsStale(lock, startedAt) && takeOverRmwLock(lock, startedAt))
                     continue;
                 // The deadline is checked only AFTER an acquire has been attempted: with
                 // the check at the top of the loop, a successful takeover could still be
@@ -917,19 +942,29 @@ export class JsonStore {
         return names.length;
     }
     /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
-     *  A record that still fails validation after migration is kept untouched (never
-     *  deleted) and counted as `skipped`, so migration can't lose data. The caller
-     *  bumps the manifest afterward. */
+     *  A record that still fails validation after migration (or whose migration
+     *  throws) is kept in its ORIGINAL shape (never deleted, never half-migrated) and
+     *  counted as `skipped`, so migration can't lose data. The caller stamps the
+     *  manifest at the returned `version`: SCHEMA_VERSION only when nothing was
+     *  skipped, else the FROM version, so a manual fix plus a rerun re-applies the
+     *  (idempotent) migrations to the skipped records instead of skipping them.
+     *  A bad record of a kind NO pending migration touches can't be fixed by a
+     *  rerun, so it is counted as `invalid` instead and doesn't hold the version. */
     persistMigration() {
         let migrated = 0;
         let skipped = 0;
+        let invalid = 0;
         this.cache.clear(); // every record is rewritten; drop all memoized loads
         const version = this.schemaVersion(); // read once; we're migrating FROM this
         for (const kind of ENTITY_KINDS) {
             const directory = this.safeKindDirectory(kind, false);
             if (!directory)
                 continue;
-            const schema = SCHEMAS[kind];
+            const pending = hasPendingMigration(kind, version);
+            const fail = () => { if (pending)
+                skipped++;
+            else
+                invalid++; };
             const single = SINGLE_FILE[kind];
             if (single) {
                 const f = join(directory.lexical, single);
@@ -941,23 +976,23 @@ export class JsonStore {
                     arr = JSON.parse(text);
                 }
                 catch {
-                    skipped++;
+                    fail();
                     continue;
                 }
                 if (!Array.isArray(arr)) {
-                    skipped++;
+                    fail();
                     continue;
                 }
                 const kept = [];
                 for (const raw of arr) {
-                    const r = schema.safeParse(this.migrate(kind, raw, version));
+                    const r = this.tryMigrate(kind, raw, version);
                     if (r.success) {
                         kept.push(r.data);
                         migrated++;
                     }
                     else {
                         kept.push(raw); // preserve unmigratable records rather than drop them
-                        skipped++;
+                        fail();
                     }
                 }
                 this.writeContainedFile(directory, f, encode(kept), this.maxBytes(kind));
@@ -970,24 +1005,38 @@ export class JsonStore {
                         const text = this.readContainedFile(directory, p, this.maxBytes(kind));
                         if (text === null)
                             continue;
+                        // A 0-byte merge-driver tombstone holds no record (issue #37) — the
+                        // loader's rule; counting it would pin the manifest version forever.
+                        if (text.trim() === "")
+                            continue;
                         raw = JSON.parse(text);
                     }
                     catch {
-                        skipped++;
+                        fail();
                         continue;
                     }
-                    const r = schema.safeParse(this.migrate(kind, raw, version));
+                    const r = this.tryMigrate(kind, raw, version);
                     if (r.success) {
                         this.writeContainedFile(directory, p, encode(r.data), this.maxBytes(kind));
                         migrated++;
                     }
                     else {
-                        skipped++; // leave the file as-is
+                        fail(); // leave the file as-is
                     }
                 }
             }
         }
-        return { migrated, skipped };
+        return { migrated, skipped, invalid, version: skipped ? version : SCHEMA_VERSION };
+    }
+    /** Migrate + validate one raw record for persistMigration; a throwing migration
+     *  step counts as a failure, so the record stays in its original shape. */
+    tryMigrate(kind, raw, version) {
+        try {
+            return SCHEMAS[kind].safeParse(this.migrate(kind, raw, version));
+        }
+        catch {
+            return { success: false };
+        }
     }
 }
 //# sourceMappingURL=jsonStore.js.map

package/dist/store/stateBinding.js

@@ -795,15 +795,21 @@ function writeStateAuthorized(store, input, opts, access) {
         // land its `superseded` event in THIS ledger, invisible to that partition's subscribers.
         if (!inScope(supersededRecord))
             throw new StateRefusal("conflict", `supersedes ${request.supersedes} is on record in ${scopePath(recordScope(supersededRecord, repo))}, not ${scopePath(request.scope)}: a write supersedes only a record in its own partition`, { incumbent_id: String(supersededRecord.id), reason: "supersede target in another partition" });
+        const matches = typeof request.expected_version === 'number'
+            ? latestSeqFor(ledger, String(supersededRecord.id)) === request.expected_version
+            : request.expected_version === stateHash(supersededRecord);
         if (stateHash(supersededVisibility ?? null) !== stateHash(nextVisibility ?? null)) {
             if (supersededVisibility ? supersededVisibility.owner !== request.principal.id : request.principal.kind !== 'human')
                 deny();
-            const matches = typeof request.expected_version === 'number'
-                ? latestSeqFor(readLedger(hunchDir, request.scope), String(supersededRecord.id)) === request.expected_version
-                : request.expected_version === stateHash(supersededRecord);
-            if (!matches)
+            if (request.expected_version === null)
                 throw new StateRefusal('malformed', 'changing visibility during supersession requires the predecessor expected_version');
         }
+        // A supersession's expected_version names the predecessor (#510): a stale one is a conflict.
+        if (request.expected_version !== null && !matches)
+            throw new StateRefusal("conflict", `expected_version does not match the superseded ${supersededRecord.id}`, { incumbent_id: String(supersededRecord.id), reason: "expected_version mismatch" });
+    }
+    else if (request.supersedes && request.expected_version !== null) {
+        throw new StateRefusal("conflict", `expected_version names ${request.supersedes}, which is not on record`, { incumbent_id: request.supersedes, reason: "expected_version without incumbent" });
     }
     if (!incumbent && !supersededRecord && nextVisibility?.owner !== undefined && nextVisibility.owner !== request.principal.id)
         deny();
@@ -873,6 +879,13 @@ function writeStateAuthorized(store, input, opts, access) {
         if (!ok)
             throw new StateRefusal("conflict", `expected_version does not match the incumbent ${id}`, { incumbent_id: id, reason: "expected_version mismatch" });
     }
+    // Compare-and-swap with no incumbent (#510): a writer naming a version believes a record exists,
+    // so a fresh create under it is a stale read, never silently accepted. Numeric 0 is the ledger's
+    // "never seen" and asserts absence; a supersession's expected_version names its predecessor.
+    if (!existing && request.expected_version !== null && !request.supersedes
+        && !(typeof request.expected_version === "number" && latestSeqFor(ledger, id) === request.expected_version)) {
+        throw new StateRefusal("conflict", `expected_version ${JSON.stringify(request.expected_version)} names a version, but ${id} has none on record: pass null to create it (0 asserts the id was never written)`, { incumbent_id: id, reason: "expected_version without incumbent" });
+    }
     if (replayLink) {
         const recordHash = stateHash(replayLink);
         appendChanges(hunchDir, request.scope, missingEventFor(ledger, facet, replayLink, request.principal.id), { key: request.idempotency_key, entry: { record_id: replayLink.id, record_hash: recordHash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);