@vincemakes/kiso-runtime 0.1.37 → 1.0.0

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./recovery.js";
 export * from "./compose.js";
 export * from "./summarize.js";
 export * from "./store.js";
+export * from "./lock-adapter.js";
 export * from "./ledger.js";
 export * from "./extensions.js";
 export * from "./trust.js";

package/dist/index.js

@@ -5,6 +5,7 @@ export * from "./recovery.js";
 export * from "./compose.js";
 export * from "./summarize.js";
 export * from "./store.js";
+export * from "./lock-adapter.js";
 export * from "./ledger.js";
 export * from "./extensions.js";
 export * from "./trust.js";

package/dist/lock-adapter.d.ts

@@ -0,0 +1,92 @@
+/**
+ * LockAdapter — the cross-process single-writer lock contract (R-G 0.1.47,
+ * ADR-0050).
+ *
+ * The default adapter is the identity-confirmed link lock — a pure Node
+ * mechanism. Node's stdlib has no advisory-lock primitive (the round-4
+ * python3 flock helper is the dependency this round retires), so possession
+ * of `<id>.lock` is decided by atomic filesystem operations, and the file
+ * itself carries the holder's identity.
+ *
+ * The protocol (the decision path is synchronous — no awaits between the
+ * read and the act):
+ *
+ * acquire — read the identity; if it is absent or names a dead pid (fresh
+ *   path / dead holder / stale residue): rename the path away (atomic —
+ *   exactly one contender wins), re-read what was moved, and if it differs
+ *   from what was judged (a rival's LIVE file got moved) abort the takeover
+ *   and restore-or-keep. Then write MY identity to a temp file, fsync it,
+ *   and LINK it at the final path (atomic create-if-absent). The link is
+ *   the only way the final path ever exists — a kill can never leave an
+ *   empty or half-written lock (see the fsync note below). A live foreign
+ *   identity refuses immediately; a live identity naming OUR OWN process is
+ *   a same-process writer's residue (round 5) and is retried until its
+ *   release or the cap.
+ *
+ * verify — possession is re-checked at every append: the file must still
+ *   name this handle's pid AND token. Failure is a STRICT refusal — no
+ *   retry, no wait heuristic (ADR-0050: the guard must be reason-able; a
+ *   displaced holder fails honestly and the session resumes from a fresh
+ *   store — never two writers).
+ *
+ * release — rename my file away, confirm it is mine, leave the EMPTY
+ *   released marker (the path is never deleted — a contender must be able
+ *   to read it), remove the tombstone. A moved rival's file is
+ *   restored-or-kept, never clobbered.
+ *
+ * The fsync-before-link order is LOAD-BEARING: the temp file is fully
+ * written AND fsynced before the final name is linked, so a power loss can
+ * never produce an empty or half-written file at the final path — the
+ * inode's data is durable before the name exists. The final path itself
+ * needs no directory fsync: if the name is lost in a crash, the holder
+ * died with it, and the residue is acquirable (ADR-0050 §crash-durability).
+ *
+ * The identity FILE format is the cross-version channel (unchanged from
+ * round 4): modern `{"pid": number, "token": string}`, legacy bare-pid
+ * (string or JSON number), empty (the released marker / a legacy-format
+ * writer's create window), half-written (crash residue). A legacy-format
+ * writer sees a live modern identity and refuses to take over; we refuse a
+ * live foreign legacy pid. Empty and half-written files are taken over as
+ * residue — under the documented QUARANTINE upgrade contract (round 5
+ * P1-4), no live legacy holder exists to be split (ADR-0050 §migration).
+ *
+ * Hard-link dependence: linkSync requires a link-capable filesystem
+ * (macOS/Linux/Windows NTFS). EPERM/ENOTSUP is an honest
+ * LockUnavailableError carrying the errno — never a silent degradation to
+ * a weaker scheme (that would re-open the empty-file window, ADR-0050).
+ *
+ * Test-only affordances (KISO_LOCK_TEST_* env, default off): the race
+ * gates (native-lock-race.test.ts) freeze a contender between the read and
+ * the rename-away, and between the rename-away and the verify, via fixed
+ * pauses plus SIGSTOP/SIGCONT, and locate the freeze points via
+ * ready-marker files (ADR-0050 §test affordances).
+ */
+/** A live foreign writer owns the lock — never taken over. */
+export declare class LockedError extends Error {
+    constructor(message: string);
+}
+/** The mechanism cannot operate (fs/link failure) — never a lock conflict. */
+export declare class LockUnavailableError extends Error {
+    constructor(reason: string);
+}
+export interface LockHandle {
+    readonly pid: number;
+    readonly token: string;
+    /** True iff the lock file at the path still names THIS identity. */
+    verify(): boolean;
+    /** Idempotent release; the path is left as the empty released marker. */
+    release(): void;
+}
+export interface LockAdapter {
+    readonly name: string;
+    /**
+     * Take (or take over) the lock at lockPath. Rejects with LockedError
+     * when a live foreign writer owns it (or the same-process-residue retry
+     * cap is hit), LockUnavailableError when the mechanism cannot operate.
+     * cancelled() is invoked at each retry decision and may throw to abort
+     * the acquisition (the store's lifecycle barrier).
+     */
+    acquire(lockPath: string, sessionId: string, cancelled: () => void): Promise<LockHandle>;
+}
+/** The default adapter: the identity-confirmed link lock (ADR-0050). */
+export declare const nativeLockAdapter: LockAdapter;

package/dist/lock-adapter.js

@@ -0,0 +1,339 @@
+/**
+ * LockAdapter — the cross-process single-writer lock contract (R-G 0.1.47,
+ * ADR-0050).
+ *
+ * The default adapter is the identity-confirmed link lock — a pure Node
+ * mechanism. Node's stdlib has no advisory-lock primitive (the round-4
+ * python3 flock helper is the dependency this round retires), so possession
+ * of `<id>.lock` is decided by atomic filesystem operations, and the file
+ * itself carries the holder's identity.
+ *
+ * The protocol (the decision path is synchronous — no awaits between the
+ * read and the act):
+ *
+ * acquire — read the identity; if it is absent or names a dead pid (fresh
+ *   path / dead holder / stale residue): rename the path away (atomic —
+ *   exactly one contender wins), re-read what was moved, and if it differs
+ *   from what was judged (a rival's LIVE file got moved) abort the takeover
+ *   and restore-or-keep. Then write MY identity to a temp file, fsync it,
+ *   and LINK it at the final path (atomic create-if-absent). The link is
+ *   the only way the final path ever exists — a kill can never leave an
+ *   empty or half-written lock (see the fsync note below). A live foreign
+ *   identity refuses immediately; a live identity naming OUR OWN process is
+ *   a same-process writer's residue (round 5) and is retried until its
+ *   release or the cap.
+ *
+ * verify — possession is re-checked at every append: the file must still
+ *   name this handle's pid AND token. Failure is a STRICT refusal — no
+ *   retry, no wait heuristic (ADR-0050: the guard must be reason-able; a
+ *   displaced holder fails honestly and the session resumes from a fresh
+ *   store — never two writers).
+ *
+ * release — rename my file away, confirm it is mine, leave the EMPTY
+ *   released marker (the path is never deleted — a contender must be able
+ *   to read it), remove the tombstone. A moved rival's file is
+ *   restored-or-kept, never clobbered.
+ *
+ * The fsync-before-link order is LOAD-BEARING: the temp file is fully
+ * written AND fsynced before the final name is linked, so a power loss can
+ * never produce an empty or half-written file at the final path — the
+ * inode's data is durable before the name exists. The final path itself
+ * needs no directory fsync: if the name is lost in a crash, the holder
+ * died with it, and the residue is acquirable (ADR-0050 §crash-durability).
+ *
+ * The identity FILE format is the cross-version channel (unchanged from
+ * round 4): modern `{"pid": number, "token": string}`, legacy bare-pid
+ * (string or JSON number), empty (the released marker / a legacy-format
+ * writer's create window), half-written (crash residue). A legacy-format
+ * writer sees a live modern identity and refuses to take over; we refuse a
+ * live foreign legacy pid. Empty and half-written files are taken over as
+ * residue — under the documented QUARANTINE upgrade contract (round 5
+ * P1-4), no live legacy holder exists to be split (ADR-0050 §migration).
+ *
+ * Hard-link dependence: linkSync requires a link-capable filesystem
+ * (macOS/Linux/Windows NTFS). EPERM/ENOTSUP is an honest
+ * LockUnavailableError carrying the errno — never a silent degradation to
+ * a weaker scheme (that would re-open the empty-file window, ADR-0050).
+ *
+ * Test-only affordances (KISO_LOCK_TEST_* env, default off): the race
+ * gates (native-lock-race.test.ts) freeze a contender between the read and
+ * the rename-away, and between the rename-away and the verify, via fixed
+ * pauses plus SIGSTOP/SIGCONT, and locate the freeze points via
+ * ready-marker files (ADR-0050 §test affordances).
+ */
+import { closeSync, fsyncSync, linkSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+/** A live foreign writer owns the lock — never taken over. */
+export class LockedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LockedError";
+    }
+}
+/** The mechanism cannot operate (fs/link failure) — never a lock conflict. */
+export class LockUnavailableError extends Error {
+    constructor(reason) {
+        super(`session locking unavailable: ${reason}`);
+        this.name = "LockUnavailableError";
+    }
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Read a lock file's holder identity (round 4 formats, unchanged — the
+ * cross-version channel). Empty, unreadable, or half-written locks have no
+ * identity: they are residue, taken over (ADR-0050 §migration).
+ */
+function readLockIdentity(lockPath) {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        parsed = trimmed; // half-written JSON — try as a bare pid
+    }
+    if (typeof parsed === "number" && Number.isInteger(parsed)) {
+        return { pid: parsed }; // JSON.parse("123") — a legacy bare pid
+    }
+    if (typeof parsed === "string") {
+        const pid = Number.parseInt(parsed, 10);
+        return Number.isFinite(pid) ? { pid } : null;
+    }
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        const v = parsed;
+        return {
+            ...(typeof v.pid === "number" ? { pid: v.pid } : {}),
+            ...(typeof v.token === "string" ? { token: v.token } : {}),
+        };
+    }
+    return null;
+}
+function sameIdentity(a, b) {
+    if (a === null && b === null)
+        return true;
+    if (a === null || b === null)
+        return false;
+    return a.pid === b.pid && (a.token ?? null) === (b.token ?? null);
+}
+function unavailable(err) {
+    const e = err;
+    return new LockUnavailableError(`${e.code ?? "?"}: ${e.message}`);
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+class NativeLockHandle {
+    pid;
+    token;
+    #lockPath;
+    #tombstone;
+    #released = false;
+    constructor(lockPath, tombstone, identity) {
+        this.#lockPath = lockPath;
+        this.#tombstone = tombstone;
+        this.pid = identity.pid;
+        this.token = identity.token;
+    }
+    verify() {
+        if (this.#released)
+            return false;
+        const now = readLockIdentity(this.#lockPath);
+        return now !== null && now.pid === this.pid && now.token === this.token;
+    }
+    release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        try {
+            renameSync(this.#lockPath, this.#tombstone);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return; // nothing of ours at the path
+            // A fs-level failure: fall back to clearing in place (advisory
+            // best effort — a missing marker can only wedge same-process
+            // residue, never split a writer).
+            try {
+                writeFileSync(this.#lockPath, "");
+            }
+            catch {
+                // advisory only
+            }
+            return;
+        }
+        const moved = readLockIdentity(this.#tombstone);
+        if (moved !== null && moved.pid === this.pid && moved.token === this.token) {
+            // Mine. Leave the EMPTY released marker — the path is never
+            // deleted (a contender must be able to read it; the
+            // storage-identity suite pins it) — created ONLY-if-absent, so
+            // a rival that linked in the window keeps its lock untouched.
+            try {
+                const fd = openSync(this.#lockPath, "wx");
+                closeSync(fd);
+            }
+            catch (err) {
+                // EEXIST → a rival's lock stands; anything else → advisory.
+            }
+            try {
+                unlinkSync(this.#tombstone);
+            }
+            catch {
+                // the stray tombstone is inert
+            }
+            return;
+        }
+        // A rival's file was moved (the displacement cascade, ADR-0050
+        // §residual) — restore-or-keep, never clobber: link it back
+        // only-if-absent; on EEXIST the path already carries a newer lock
+        // and the moved file stays at its distinct name (inert residue).
+        try {
+            linkSync(this.#tombstone, this.#lockPath);
+        }
+        catch {
+            // EEXIST or fs failure — inert
+        }
+    }
+}
+class NativeLock {
+    name = "link-lock";
+    async acquire(lockPath, sessionId, cancelled) {
+        const pid = process.pid;
+        const token = randomUUID();
+        // The staging name is PER-ATTEMPT: a later rename-away in the same
+        // acquire must never atomically overwrite an earlier attempt's
+        // abandoned staging (that would clobber the displacement residue,
+        // ADR-0050 §residual). tmp/tombstone are unique per acquire and are
+        // always cleaned or inert.
+        const tmp = `${lockPath}.tmp-${pid}-${token}`;
+        const tombstone = `${lockPath}.tomb-${pid}-${token}`;
+        // Test-only affordances (ADR-0050 §test affordances): the cascade
+        // gate freezes a contender at the two decision points.
+        const readyDir = process.env.KISO_LOCK_TEST_READY_DIR;
+        const readPause = Number(process.env.KISO_LOCK_TEST_PAUSE_READ_MS ?? 0) || 0;
+        const takeoverPause = Number(process.env.KISO_LOCK_TEST_PAUSE_TAKEOVER_MS ?? 0) || 0;
+        for (let attempt = 0;; attempt++) {
+            cancelled();
+            const staging = `${lockPath}.staging-${pid}-${token}-${attempt}`;
+            const seen = readLockIdentity(lockPath);
+            if (seen === null || seen.pid === undefined || !isAlive(seen.pid)) {
+                // Fresh path, dead holder, or stale residue — take it over
+                // by identity confirmation: rename-away → verify → link.
+                if (readyDir !== undefined)
+                    writeFileSync(join(readyDir, `read-${pid}`), "");
+                if (readPause > 0)
+                    await sleep(readPause);
+                let moved = false;
+                try {
+                    renameSync(lockPath, staging);
+                    moved = true;
+                }
+                catch (err) {
+                    if (err.code !== "ENOENT")
+                        throw unavailable(err);
+                    // ENOENT — the path is already absent; proceed to the link.
+                }
+                if (moved) {
+                    if (readyDir !== undefined)
+                        writeFileSync(join(readyDir, `takeover-${pid}`), "");
+                    if (takeoverPause > 0)
+                        await sleep(takeoverPause);
+                    const s = readLockIdentity(staging);
+                    if (!sameIdentity(s, seen)) {
+                        // The path was replaced between my read and my rename
+                        // — a RIVAL'S LIVE file was moved. Abort the takeover:
+                        // restore-or-keep (link back only-if-absent; on EEXIST
+                        // the moved file is abandoned — inert residue at its
+                        // distinct name, ADR-0050 §residual).
+                        try {
+                            linkSync(staging, lockPath);
+                        }
+                        catch (err) {
+                            if (err.code !== "EEXIST")
+                                throw unavailable(err);
+                        }
+                        continue;
+                    }
+                }
+                // Write my identity fully, fsync it, THEN link — the
+                // load-bearing order (ADR-0050 §crash-durability): the final
+                // path can never exist empty or half-written, even across a
+                // power loss.
+                try {
+                    const fd = openSync(tmp, "w");
+                    try {
+                        writeFileSync(fd, JSON.stringify({ pid, token }), "utf8");
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                    linkSync(tmp, lockPath);
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code === "EEXIST") {
+                        // A rival linked first — retry from a fresh read.
+                        try {
+                            unlinkSync(tmp);
+                        }
+                        catch {
+                            // the stray is inert
+                        }
+                        continue;
+                    }
+                    throw unavailable(err);
+                }
+                try {
+                    unlinkSync(tmp);
+                }
+                catch {
+                    // the stray is inert
+                }
+                // The takeover succeeded — our identity owns the path, and the
+                // verified-dead file we moved away may be cleaned up (its
+                // name is distinct; unlinking it can never touch the lock
+                // path). Only the EEXIST-abandoned staging of a FAILED
+                // takeover lingers — the displacement fingerprint.
+                if (moved) {
+                    try {
+                        unlinkSync(staging);
+                    }
+                    catch {
+                        // the stray is inert
+                    }
+                }
+                return new NativeLockHandle(lockPath, tombstone, { pid, token });
+            }
+            if (seen.pid === pid && seen.token !== undefined) {
+                // Same-process writer's residue (round 5): another store in
+                // THIS process holds the lock — it will release; retry until
+                // it does (never a spurious self-conflict). A legacy
+                // bare-pid lock naming our own process is refused like any
+                // live foreign owner.
+                if (attempt >= 25)
+                    throw new LockedError(`session ${sessionId} is locked by another writer`);
+                await sleep(20);
+                continue;
+            }
+            throw new LockedError(`session ${sessionId} is locked by another writer (pid ${seen.pid})`);
+        }
+    }
+}
+/** The default adapter: the identity-confirmed link lock (ADR-0050). */
+export const nativeLockAdapter = new NativeLock();

package/dist/store.d.ts

@@ -3,24 +3,32 @@
  *
  * One file per session: `<root>/<id>.jsonl`, lines of
  * `{"runId": string, "ts": number, "event": Event}`. The single-writer
- * lock (round 4) is an EXCLUSIVE KERNEL flock on `<id>.lock`, held by a
- * dedicated helper process:
+ * lock (R-G 0.1.47, ADR-0050) is the native identity-confirmed LINK LOCK
+ * on `<id>.lock` — no helper process, no python3. Possession is decided by
+ * atomic filesystem operations (see lock-adapter.ts for the full protocol
+ * and the residual family):
  *
- * - the kernel arbitrates every race — a contender can never remove or
- *   overwrite a live holder's lock, because there is nothing to remove;
- *   the lock simply exists while the helper lives and vanishes with it;
- * - the lock file ALSO carries `{"pid": number, "token": string}` written
- *   by the holder, as a best-effort guard for OLD-format writers (whose
- *   O_EXCL pidfile scheme does not honor flock). round 5(P1-4): this guard
- *   is NOT a seamless rolling upgrade — an old writer that created an
- *   empty lock file before writing its pid creates a split-brain window
- *   that a pidfile read cannot close. The documented upgrade contract is
- *   QUARANTINE: stop every old-format process, THEN start the new
- *   version. A dead/empty/unreadable legacy lock is otherwise harmless —
- *   flock ignores content, and the kernel lock is what matters;
- * - `close()` releases only THIS instance's helper; `closeAll()` every
- *   held helper — a foreign close can never release another writer's
- *   kernel lock (flock is tied to the helper's open file description).
+ * - the final path exists ONLY by linking a fully-written and fsynced
+ *   identity file (atomic create-if-absent) — a kill can never leave an
+ *   empty or half-written lock; dead holders are taken over by identity
+ *   confirmation (rename-away → verify → link), never by deletion;
+ * - the file carries `{"pid": number, "token": string}`; the holder's
+ *   possession is RE-CHECKED at every append (the file must still name its
+ *   pid AND token) and a failure is a strict refusal — no retry, no wait
+ *   heuristic: a displaced holder fails honestly and the session resumes
+ *   from a fresh store, never two writers (ADR-0050 §residual);
+ * - the identity format is the cross-version channel (round 4 formats
+ *   unchanged). A dead/empty/unreadable legacy lock is residue and is
+ *   taken over — the documented upgrade contract is QUARANTINE (round 5
+ *   P1-4): stop every old-format process, THEN start the new version
+ *   (ADR-0050 §migration);
+ * - the mechanism is an injection point: `new SessionStore(root, {
+ *   lockAdapter })` — the interface is the extension point, and the
+ *   default adapter is `nativeLockAdapter` (ADR-0050);
+ * - `close()` releases only THIS instance's handle; `closeAll()` every
+ *   held handle — a foreign close can never release another writer's
+ *   lock. Release leaves the EMPTY released marker; the path is never
+ *   deleted.
  *
  * Consistency contract (A group):
  * - every id is validated BEFORE any file side effect (append, close,
@@ -35,6 +43,7 @@
  *   tolerated damage; everything else throws StoreCorruptionError.
  */
 import { type Event } from "@vincemakes/kiso-core";
+import { type LockAdapter } from "./lock-adapter.js";
 /** History that does not parse as a contiguous kiso trajectory. */
 export declare class StoreCorruptionError extends Error {
     constructor(message: string);
@@ -60,29 +69,28 @@ export interface SessionMeta {
 export declare class SessionStore {
     #private;
     readonly root: string;
-    constructor(root: string);
+    constructor(root: string, opts?: {
+        lockAdapter?: LockAdapter;
+    });
     private pathFor;
     private lockPathFor;
     /**
-     * Take the single-writer lock (round 4): an EXCLUSIVE kernel flock held
-     * by a dedicated helper process. The KERNEL arbitrates every race —
-     * there is no stale lock to delete and no takeover to race: a
-     * contender either gets the flock (the previous holder is gone) or it
-     * fails. The lock file also carries the holder's identity so an OLD-format
-     * writer (which does not honor flock) still sees a live owner and
-     * refuses to take over — a best-effort guard, NOT a seamless rolling
-     * upgrade (round 5 P1-4): the documented upgrade contract is quarantine —
-     * stop every old-format process, then start the new version.
-     * No recursion, no deletion, no window between NEW-format writers.
+     * Take the single-writer lock (R-G 0.1.47, ADR-0050): the identity-
+     * confirmed link lock (see lock-adapter.ts). The adapter decides
+     * possession by atomic filesystem operations; a dead holder is taken
+     * over by identity confirmation (rename-away → verify → link), a live
+     * foreign writer refuses. No recursion, no deletion, no window between
+     * writers. The adapter's `cancelled` callback throws the store's closed
+     * message so a close() that landed mid-acquisition aborts it
+     * immediately (round 5 P1-3).
      */
     private acquireLock;
-    /** round 5(P1-2): true only while the helper process is alive. */
+    /** round 5(P1-2): true only while THIS instance holds its handle. */
     private lockHeld;
     /**
-     * Release OUR lock only: kill OUR helper. The kernel releases the
-     * flock with the helper's death; the identity file is CLEARED so a
-     * same-process successor is never mistaken for a live legacy owner —
-     * the flock is the authority, the file is advisory (round 4).
+     * Release OUR lock only: release OUR handle (the adapter leaves the
+     * empty released marker at the path — never a deletion). A foreign
+     * close can never release another writer's lock (ADR-0050).
      */
     private releaseLock;
     /** Write-ahead: durable (written + fsynced) before returning. */

package/dist/store.js

@@ -3,24 +3,32 @@
  *
  * One file per session: `<root>/<id>.jsonl`, lines of
  * `{"runId": string, "ts": number, "event": Event}`. The single-writer
- * lock (round 4) is an EXCLUSIVE KERNEL flock on `<id>.lock`, held by a
- * dedicated helper process:
+ * lock (R-G 0.1.47, ADR-0050) is the native identity-confirmed LINK LOCK
+ * on `<id>.lock` — no helper process, no python3. Possession is decided by
+ * atomic filesystem operations (see lock-adapter.ts for the full protocol
+ * and the residual family):
  *
- * - the kernel arbitrates every race — a contender can never remove or
- *   overwrite a live holder's lock, because there is nothing to remove;
- *   the lock simply exists while the helper lives and vanishes with it;
- * - the lock file ALSO carries `{"pid": number, "token": string}` written
- *   by the holder, as a best-effort guard for OLD-format writers (whose
- *   O_EXCL pidfile scheme does not honor flock). round 5(P1-4): this guard
- *   is NOT a seamless rolling upgrade — an old writer that created an
- *   empty lock file before writing its pid creates a split-brain window
- *   that a pidfile read cannot close. The documented upgrade contract is
- *   QUARANTINE: stop every old-format process, THEN start the new
- *   version. A dead/empty/unreadable legacy lock is otherwise harmless —
- *   flock ignores content, and the kernel lock is what matters;
- * - `close()` releases only THIS instance's helper; `closeAll()` every
- *   held helper — a foreign close can never release another writer's
- *   kernel lock (flock is tied to the helper's open file description).
+ * - the final path exists ONLY by linking a fully-written and fsynced
+ *   identity file (atomic create-if-absent) — a kill can never leave an
+ *   empty or half-written lock; dead holders are taken over by identity
+ *   confirmation (rename-away → verify → link), never by deletion;
+ * - the file carries `{"pid": number, "token": string}`; the holder's
+ *   possession is RE-CHECKED at every append (the file must still name its
+ *   pid AND token) and a failure is a strict refusal — no retry, no wait
+ *   heuristic: a displaced holder fails honestly and the session resumes
+ *   from a fresh store, never two writers (ADR-0050 §residual);
+ * - the identity format is the cross-version channel (round 4 formats
+ *   unchanged). A dead/empty/unreadable legacy lock is residue and is
+ *   taken over — the documented upgrade contract is QUARANTINE (round 5
+ *   P1-4): stop every old-format process, THEN start the new version
+ *   (ADR-0050 §migration);
+ * - the mechanism is an injection point: `new SessionStore(root, {
+ *   lockAdapter })` — the interface is the extension point, and the
+ *   default adapter is `nativeLockAdapter` (ADR-0050);
+ * - `close()` releases only THIS instance's handle; `closeAll()` every
+ *   held handle — a foreign close can never release another writer's
+ *   lock. Release leaves the EMPTY released marker; the path is never
+ *   deleted.
  *
  * Consistency contract (A group):
  * - every id is validated BEFORE any file side effect (append, close,
@@ -34,10 +42,10 @@
  * - load is strict (A group round 1): a partial final line is the only
  *   tolerated damage; everything else throws StoreCorruptionError.
  */
-import { spawn } from "node:child_process";
-import { appendFileSync, closeSync, existsSync, fsyncSync, fstatSync, ftruncateSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, readSync, unlinkSync, writeFileSync, } from "node:fs";
+import { appendFileSync, closeSync, existsSync, fsyncSync, fstatSync, ftruncateSync, mkdirSync, openSync, readFileSync, readdirSync, readSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { isKisoEvent } from "@vincemakes/kiso-core";
+import { LockedError, nativeLockAdapter, } from "./lock-adapter.js";
 /** History that does not parse as a contiguous kiso trajectory. */
 export class StoreCorruptionError extends Error {
     constructor(message) {
@@ -57,10 +65,11 @@ const ID_PATTERN = /^[A-Za-z0-9._-]+$/;
 export class SessionStore {
     root;
     #fds = new Map();
-    /** sessionId → the lock helper process THIS instance spawned. */
-    #lockHelpers = new Map();
+    /** sessionId → the lock handle THIS instance holds (ADR-0050). */
+    #lockHandles = new Map();
+    #lockAdapter;
     /** round 4 (adversarial): serialize concurrent acquireLock calls ON this instance —
-     *  two racing appends must not spawn two helpers and fight each other. */
+     *  two racing appends must not issue two acquisitions and fight each other. */
     #lockAcquiring = new Map();
     /** round 5(P1-1): serialize the WHOLE append critical section per session on
      *  this instance — lock check → CAS → write → fsync. A rejected write
@@ -68,8 +77,9 @@ export class SessionStore {
      *  never land after a stale failure (which would fork memory and disk). */
     #appendQueues = new Map();
     #closed = new Set();
-    constructor(root) {
+    constructor(root, opts) {
         this.root = root;
+        this.#lockAdapter = opts?.lockAdapter ?? nativeLockAdapter;
         mkdirSync(root, { recursive: true });
         fsyncDir(root);
     }
@@ -84,21 +94,18 @@ export class SessionStore {
         return join(this.root, `${sessionId}.lock`);
     }
     /**
-     * Take the single-writer lock (round 4): an EXCLUSIVE kernel flock held
-     * by a dedicated helper process. The KERNEL arbitrates every race —
-     * there is no stale lock to delete and no takeover to race: a
-     * contender either gets the flock (the previous holder is gone) or it
-     * fails. The lock file also carries the holder's identity so an OLD-format
-     * writer (which does not honor flock) still sees a live owner and
-     * refuses to take over — a best-effort guard, NOT a seamless rolling
-     * upgrade (round 5 P1-4): the documented upgrade contract is quarantine —
-     * stop every old-format process, then start the new version.
-     * No recursion, no deletion, no window between NEW-format writers.
+     * Take the single-writer lock (R-G 0.1.47, ADR-0050): the identity-
+     * confirmed link lock (see lock-adapter.ts). The adapter decides
+     * possession by atomic filesystem operations; a dead holder is taken
+     * over by identity confirmation (rename-away → verify → link), a live
+     * foreign writer refuses. No recursion, no deletion, no window between
+     * writers. The adapter's `cancelled` callback throws the store's closed
+     * message so a close() that landed mid-acquisition aborts it
+     * immediately (round 5 P1-3).
      */
     async acquireLock(sessionId) {
-        // round 5(P1-2): the lock is held only while the helper PROCESS is
-        // alive — flock is bound to the helper's lifetime. A dead helper's
-        // entry must never be trusted as "locked".
+        // round 5(P1-2): a lock is held only while THIS instance's handle is
+        // held — a displaced/dead lock must never be trusted as "locked".
         if (this.lockHeld(sessionId))
             return;
         const inFlight = this.#lockAcquiring.get(sessionId);
@@ -108,102 +115,36 @@ export class SessionStore {
         this.#lockAcquiring.set(sessionId, attempt);
         return attempt;
     }
-    /** round 5(P1-2): true only while the helper process is alive. */
+    /** round 5(P1-2): true only while THIS instance holds its handle. */
     lockHeld(sessionId) {
-        const child = this.#lockHelpers.get(sessionId);
-        if (child === undefined || child.pid === undefined || child.pid <= 0)
-            return false;
-        return isAlive(child.pid);
+        return this.#lockHandles.has(sessionId);
     }
     async #acquireLockOnce(sessionId) {
         const lockPath = this.lockPathFor(sessionId);
-        for (let attempt = 0;; attempt++) {
-            const child = spawn("python3", ["-c", LOCK_HELPER_SCRIPT, lockPath], {
-                stdio: ["pipe", "pipe", "ignore"],
-            });
-            const verdict = await helperVerdict(child);
-            if (verdict === "LOCKED") {
-                // The kernel flock is ours. One last compatibility gate: an
-                // OLD-format writer (which does not honor flock) may still
-                // be alive — its lock file names it. Refuse, and release
-                // the flock (the helper dies). A MODERN lock (with a token)
-                // naming OUR OWN process is a same-process writer's residue
-                // (round 4: the file is advisory; the flock is the authority).
-                const legacy = readLockIdentity(lockPath);
-                if (legacy?.pid !== undefined && isAlive(legacy.pid) && (legacy.token === undefined || legacy.pid !== process.pid)) {
-                    child.kill();
-                    throw new Error(`session ${sessionId} is locked by another writer (pid ${legacy.pid})`);
-                }
-                // Record our identity in the file: irrelevant to flock, but
-                // an OLD-format contender reads it and refuses to take over
-                // a live writer's lock.
-                try {
-                    writeFileSync(lockPath, JSON.stringify({ pid: process.pid, token: crypto.randomUUID() }));
-                }
-                catch {
-                    // the file itself is advisory — the kernel lock holds
-                }
-                this.#lockHelpers.set(sessionId, child);
-                // round 5(P1-2): the helper's death removes the entry — the
-                // flock dies with the process; a later append re-acquires
-                // (and fails honestly if a rival holds the flock now).
-                child.on("exit", () => {
-                    if (this.#lockHelpers.get(sessionId) === child) {
-                        this.#lockHelpers.delete(sessionId);
-                    }
-                });
-                return;
-            }
-            child.kill();
-            if (verdict === "SPAWN_FAILED") {
-                // round 4 (adversarial): the helper could not start (python3 missing) —
-                // an HONEST error, never a fake lock conflict.
-                throw new Error(`session locking unavailable: the flock helper (python3) failed to start for ${sessionId}`);
-            }
-            // BUSY: either a live modern writer, or a holder that is just
-            // exiting (its helper is dying). A FOREIGN live writer's identity
-            // is in the file — refuse at once. A MODERN lock (with a token)
-            // naming OUR OWN process is a same-process writer — it will
-            // release its helper; retry until it does (round 4: never a
-            // spurious self-conflict). A legacy bare-pid lock naming our own
-            // process is still a live foreign owner and is refused.
-            const legacy = readLockIdentity(lockPath);
-            if (legacy?.pid !== undefined && isAlive(legacy.pid) && (legacy.token === undefined || legacy.pid !== process.pid)) {
-                throw new Error(`session ${sessionId} is locked by another writer (pid ${legacy.pid})`);
-            }
-            if (attempt >= 25) {
-                throw new Error(`session ${sessionId} is locked by another writer`);
-            }
-            // round 5(P1-3): a close() that landed while we waited ends the
-            // acquisition immediately — no 500ms wait, no lock at all.
+        const handle = await this.#lockAdapter.acquire(lockPath, sessionId, () => {
             if (this.#closed.has(sessionId)) {
                 throw new Error(`session store is closed for ${sessionId}`);
             }
-            await new Promise((resolve) => setTimeout(resolve, 20));
+        });
+        // round 5(P1-3): a close() that landed while we waited ends the
+        // acquisition immediately — no lock outlives the instance.
+        if (this.#closed.has(sessionId)) {
+            handle.release();
+            throw new Error(`session store is closed for ${sessionId}`);
         }
+        this.#lockHandles.set(sessionId, handle);
     }
     /**
-     * Release OUR lock only: kill OUR helper. The kernel releases the
-     * flock with the helper's death; the identity file is CLEARED so a
-     * same-process successor is never mistaken for a live legacy owner —
-     * the flock is the authority, the file is advisory (round 4).
+     * Release OUR lock only: release OUR handle (the adapter leaves the
+     * empty released marker at the path — never a deletion). A foreign
+     * close can never release another writer's lock (ADR-0050).
      */
     releaseLock(sessionId) {
-        const child = this.#lockHelpers.get(sessionId);
-        if (child === undefined)
+        const handle = this.#lockHandles.get(sessionId);
+        if (handle === undefined)
             return;
-        this.#lockHelpers.delete(sessionId);
-        // round 4 (adversarial): the identity is cleared BEFORE the helper dies — a
-        // contender that acquires the flock in the release gap writes its
-        // own identity AFTER our clear, so it is never wiped by us (the
-        // file is advisory; the kernel flock is the authority).
-        try {
-            writeFileSync(this.lockPathFor(sessionId), "");
-        }
-        catch {
-            // advisory only
-        }
-        child.kill();
+        this.#lockHandles.delete(sessionId);
+        handle.release();
     }
     // ── append: lock, open, repair, CAS, write, fsync ────────────────────
     /** Write-ahead: durable (written + fsynced) before returning. */
@@ -241,6 +182,14 @@ export class SessionStore {
             this.releaseLock(sessionId);
             throw new Error(`session store is closed for ${sessionId}`);
         }
+        // R-G 0.1.47 (ADR-0050): possession is RE-CHECKED at every append —
+        // the file must still name this handle's pid AND token. A displaced
+        // holder's next append SELF-REFUSES honestly (strict refusal, no
+        // retry): never a lockless write, never a second writer.
+        const handle = this.#lockHandles.get(sessionId);
+        if (handle === undefined || !handle.verify()) {
+            throw new LockedError(`session ${sessionId} is locked by another writer`);
+        }
         let fd;
         try {
             fd = this.fd(sessionId);
@@ -372,7 +321,7 @@ export class SessionStore {
     }
     /** Release every held fd and lock, including locks whose JSONL open failed. */
     closeAll() {
-        for (const id of new Set([...this.#fds.keys(), ...this.#lockHelpers.keys()])) {
+        for (const id of new Set([...this.#fds.keys(), ...this.#lockHandles.keys()])) {
             this.close(id);
         }
     }
@@ -383,122 +332,6 @@ function isRecord(value) {
     const v = value;
     return typeof v.runId === "string" && typeof v.ts === "number" && isKisoEvent(v.event);
 }
-/**
- * Read a lock file's holder identity (round 4). Formats:
- *   modern:  {"pid": 123, "token": "..."}
- *   legacy:  a bare pid — either the STRING "123" or, because
- *            JSON.parse("123") yields the NUMBER 123, the number itself.
- *            Neither may be mistaken for an object without a pid.
- * Empty, unreadable, or half-written locks have no identity — the kernel
- * flock supersedes them (there is nothing to refuse, and nothing to
- * delete).
- */
-function readLockIdentity(lockPath) {
-    let raw;
-    try {
-        raw = readFileSync(lockPath, "utf8");
-    }
-    catch {
-        return null;
-    }
-    const trimmed = raw.trim();
-    if (trimmed === "")
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(trimmed);
-    }
-    catch {
-        parsed = trimmed; // half-written JSON — try as a bare pid
-    }
-    if (typeof parsed === "number" && Number.isInteger(parsed)) {
-        return { pid: parsed }; // JSON.parse("123") — a legacy bare pid
-    }
-    if (typeof parsed === "string") {
-        const pid = Number.parseInt(parsed, 10);
-        return Number.isFinite(pid) ? { pid } : null;
-    }
-    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-        const v = parsed;
-        return {
-            ...(typeof v.pid === "number" ? { pid: v.pid } : {}),
-            ...(typeof v.token === "string" ? { token: v.token } : {}),
-        };
-    }
-    return null;
-}
-/**
- * The lock helper: a python3 process that takes an EXCLUSIVE flock on the
- * lock path and HOLDS it until it dies (its stdin is closed / it is
- * killed). The kernel releases the flock with the helper — the lock is
- * tied to the open file description, so a dead helper can never leave a
- * stale lock behind, and no contender can ever remove a live one.
- * python3's `fcntl` module provides flock on both macOS and Linux.
- */
-const LOCK_HELPER_SCRIPT = [
-    "import fcntl, os, sys",
-    "fd = os.open(sys.argv[1], os.O_RDWR | os.O_CREAT, 0o644)",
-    "try:",
-    "    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)",
-    "except OSError:",
-    "    print('BUSY', flush=True)",
-    "    sys.exit(0)",
-    "print('LOCKED', flush=True)",
-    "try:",
-    "    while sys.stdin.buffer.read(1):",
-    "        pass",
-    "except Exception:",
-    "    pass",
-].join("\n");
-/** The helper's first stdout line: "LOCKED" or anything else = busy/dead. */
-function helperVerdict(child) {
-    return new Promise((resolve) => {
-        let buf = "";
-        let settled = false;
-        const done = (verdict) => {
-            if (settled)
-                return;
-            settled = true;
-            child.stdout?.removeAllListeners();
-            // The helper is a LOCK DAEMON: it must never keep the parent's
-            // event loop alive (a finished store exits cleanly), and when the
-            // parent DOES exit the pipes close, the helper's read hits EOF,
-            // the helper exits, and the kernel releases the flock. The child
-            // process handle, its stdin hold, and its verdict channel are all
-            // unref'd — the lock outlives nothing the parent does not.
-            const unref = (s) => s?.unref?.();
-            unref(child);
-            unref(child.stdin);
-            unref(child.stdout);
-            resolve(verdict);
-        };
-        child.stdout?.on("data", (d) => {
-            buf += d.toString();
-            const nl = buf.indexOf("\n");
-            if (nl !== -1)
-                done(buf.slice(0, nl).trim());
-        });
-        child.stdout?.on("end", () => done(buf.trim()));
-        child.stdout?.on("error", () => done("FAILED"));
-        // round 5(P2-1): a spawn failure (python3 missing, exec denied) is
-        // DISTINCT from a busy lock — the caller must not report "locked by
-        // another writer" for a missing helper. The verdict is SPAWN_FAILED
-        // and the acquire path checks exactly that string.
-        child.on("error", (err) => {
-            void err;
-            done("SPAWN_FAILED");
-        });
-    });
-}
-function isAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === "EPERM";
-    }
-}
 /**
  * If the file does not end with a newline, truncate to the last complete
  * line (or 0) — the torn-tail repair. Runs on open AND before every append,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-runtime",
-  "version": "0.1.37",
+  "version": "1.0.0",
   "description": "kiso runtime — durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
   "type": "module",
   "license": "MIT",
@@ -21,11 +21,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-core": "0.1.35"
+    "@vincemakes/kiso-core": "1.0.0"
   },
   "peerDependencies": {
-    "@vincemakes/kiso-provider-anthropic": "0.1.36",
-    "@vincemakes/kiso-provider-openai": "0.1.36"
+    "@vincemakes/kiso-provider-anthropic": "1.0.0",
+    "@vincemakes/kiso-provider-openai": "1.0.0"
   },
   "peerDependenciesMeta": {
     "@vincemakes/kiso-provider-anthropic": {
@@ -36,7 +36,7 @@
     }
   },
   "devDependencies": {
-    "@vincemakes/kiso-evals": "0.1.36",
+    "@vincemakes/kiso-evals": "1.0.0",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"