@vincemakes/kiso-runtime 0.1.36 → 0.1.38

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/recovery-plan.d.ts

@@ -0,0 +1,74 @@
+/**
+ * R-F 0.1.46 — the recovery plan: recovery as pure projection. From the
+ * durable event prefix the plan derives THE unique safe next step — never
+ * the adjudication itself (the approval pipeline stays in the runtime driver
+ * layer, run.ts). Purity: no I/O, no ID generation, no time — the same
+ * prefix always derives the same plan. The driver consumes one action at a
+ * time and re-derives after every append: the recovery is a loop over this
+ * projection, not a second state machine (the R-F thesis — fresh execution
+ * and resume walk the same ordinary program).
+ *
+ * The action vocabulary (the R-F directive):
+ *   COMPLETED              — no open run: nothing to recover
+ *   TERMINAL               — the open run reached its terminal
+ *   WAIT_PERMISSION(seq)   — a stored request awaits the human
+ *   DECIDE_PERMISSION(seq) — a committed call re-enters the approval pipeline
+ *   EXECUTE(seq)           — a durable approval authorizes the persisted call
+ *   RESOLVE_UNCERTAIN(id)  — a started execution with no receipt: the crash
+ *                            window — the human decides (never auto-rerun)
+ *   REPAIR_RESULT(id|seq)  — the model-facing result is missing: complete it
+ *                            from the durable fact (the receipt or the denial)
+ *   FILL_RESOLUTION(id)    — a resolution's model-facing fill is missing
+ *   ABANDON_DRAFT(from)    — a text-bearing no-stop suffix: void it (the
+ *                            driver appends the marker AND expires the voided
+ *                            requests — one deterministic step, sentence 3)
+ *   CONTINUE_MODEL         — nothing left to repair: drive the loop
+ *
+ * The derivation order is the R-E recovery's phase order (the zero-behavior
+ * proof: the prefix-table gate and the healing fixtures run unchanged):
+ * terminal > completed > uncertain > draft > invocations (the Gap A calls,
+ * then the stored requests) > receipt repairs > resolution fills > continue.
+ *
+ * Inputs: `events` — the session's full event prefix (the log); `scope` —
+ * the open run's stored events at resume start (the run boundaries). Both
+ * are pure inputs; the caller loads them.
+ */
+import type { Event } from "@vincemakes/kiso-core";
+export type RecoveryAction = {
+    readonly kind: "COMPLETED";
+} | {
+    readonly kind: "TERMINAL";
+} | {
+    readonly kind: "WAIT_PERMISSION";
+    readonly invocationSeq: number;
+} | {
+    readonly kind: "DECIDE_PERMISSION";
+    readonly invocationSeq: number;
+} | {
+    readonly kind: "EXECUTE";
+    readonly invocationSeq: number;
+}
+/** The receipt repair (executionId) or the durable-denial repair (invocationSeq). */
+ | {
+    readonly kind: "REPAIR_RESULT";
+    readonly executionId?: string;
+    readonly invocationSeq?: number;
+} | {
+    readonly kind: "RESOLVE_UNCERTAIN";
+    readonly executionId: string;
+} | {
+    readonly kind: "FILL_RESOLUTION";
+    readonly executionId: string;
+} | {
+    readonly kind: "ABANDON_DRAFT";
+    readonly voidFromSeq: number;
+} | {
+    readonly kind: "CONTINUE_MODEL";
+};
+/** A request's framework identity: its own invocationSeq, or the old-log
+ *  fallback (the last same-callId call before the request, in the scope). */
+export declare function invocationSeqOf(request: Event & {
+    type: "permission_requested";
+}, scope: readonly Event[]): number | undefined;
+/** The one safe next step for the durable prefix (derivation order above). */
+export declare function deriveRecoveryPlan(events: readonly Event[], scope: readonly Event[]): RecoveryAction;