@namzu/sdk 20.2.0 → 20.4.0

package/dist/store/run/checkpoint-memory.d.ts

@@ -1,5 +1,5 @@
 import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js';
-import type { CheckpointListingScope, CheckpointRunScope, CheckpointStore, DurableRunPage, ListDurableRunsOptions } from '../../types/run/checkpoint-store.js';
+import type { CheckpointListingScope, CheckpointRunScope, CheckpointStore, ClaimFence, ClaimRunOptions, DurableRunPage, ListDurableRunsOptions, RunClaim } from '../../types/run/checkpoint-store.js';
 /**
  * Process-local {@link CheckpointStore}, keyed by the full five-layer scope.
  *
@@ -22,7 +22,27 @@ export declare class InMemoryCheckpointStore implements CheckpointStore {
     /** Same key → the run's scope, so a listing can rebuild an addressable entry. */
     private readonly scopes;
     private key;
-    writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void>;
+    /** `tenant/project/session/run` → the run's current holding, if any. */
+    private readonly claims;
+    /**
+     * The highest fence ever issued per run, kept separately from the claim.
+     *
+     * The claim is removed on release; this is not. That separation is the
+     * whole point: the first version deleted the claim and then computed the
+     * next fence from it, so releasing rewound the counter to 1 and a worker
+     * stalled at fence 1 could write beside a new holder also at fence 1 —
+     * and the documented `finally { releaseRun() }` did it on every pass.
+     *
+     * The disk store gets this property from file names that persist. In
+     * memory the equivalent is a high-water mark nothing clears, and the two
+     * must agree, because this class is what a host reads when writing a
+     * backend of its own.
+     */
+    private readonly highWater;
+    claimRun(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null>;
+    releaseRun(scope: CheckpointRunScope, fence: ClaimFence): Promise<void>;
+    writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint, fence?: ClaimFence): Promise<void>;
+    private writeUnchecked;
     readCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<IterationCheckpoint | null>;
     listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]>;
     deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void>;

package/dist/store/run/checkpoint-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint-memory.d.ts","sourceRoot":"","sources":["../../../src/store/run/checkpoint-memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,eAAe,EAEf,cAAc,EACd,sBAAsB,EACtB,MAAM,qCAAqC,CAAA;AAG5C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAC9D,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4D;IACjF,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAE/D,OAAO,CAAC,GAAG;IAIL,eAAe,CAAC,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1F,cAAc,CACnB,KAAK,EAAE,kBAAkB,EACzB,YAAY,EAAE,YAAY,GACxB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAIhC,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAM1E,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAItF,eAAe,CACpB,KAAK,EAAE,sBAAsB,EAC7B,OAAO,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC;CAkB1B"}
+{"version":3,"file":"checkpoint-memory.d.ts","sourceRoot":"","sources":["../../../src/store/run/checkpoint-memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,eAAe,EAEf,cAAc,EACd,sBAAsB,EACtB,QAAQ,EACR,MAAM,qCAAqC,CAAA;AAS5C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAC9D,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4D;IACjF,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAE/D,OAAO,CAAC,GAAG;IAIX,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IAErD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAEpD,QAAQ,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAuBvF,UAAU,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBvE,eAAe,CACpB,KAAK,EAAE,kBAAkB,EACzB,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC;YAgCF,cAAc;IA4BtB,cAAc,CACnB,KAAK,EAAE,kBAAkB,EACzB,YAAY,EAAE,YAAY,GACxB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAIhC,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAM1E,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAItF,eAAe,CACpB,KAAK,EAAE,sBAAsB,EAC7B,OAAO,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC;CAoB1B"}

package/dist/store/run/checkpoint-memory.js

@@ -1,4 +1,4 @@
-import { assertContiguousListingScope, paginateDurableRuns, toDurableRunEntry } from './listing.js';
+import { assertContiguousListingScope, fencedOut, paginateDurableRuns, toClaimSummary, toDurableRunEntry, } from './listing.js';
 /**
  * Process-local {@link CheckpointStore}, keyed by the full five-layer scope.
  *
@@ -23,7 +23,100 @@ export class InMemoryCheckpointStore {
     key(scope) {
         return [scope.tenantId, scope.projectId, scope.sessionId, scope.runId].join('/');
     }
-    async writeCheckpoint(scope, checkpoint) {
+    /** `tenant/project/session/run` → the run's current holding, if any. */
+    claims = new Map();
+    /**
+     * The highest fence ever issued per run, kept separately from the claim.
+     *
+     * The claim is removed on release; this is not. That separation is the
+     * whole point: the first version deleted the claim and then computed the
+     * next fence from it, so releasing rewound the counter to 1 and a worker
+     * stalled at fence 1 could write beside a new holder also at fence 1 —
+     * and the documented `finally { releaseRun() }` did it on every pass.
+     *
+     * The disk store gets this property from file names that persist. In
+     * memory the equivalent is a high-water mark nothing clears, and the two
+     * must agree, because this class is what a host reads when writing a
+     * backend of its own.
+     */
+    highWater = new Map();
+    async claimRun(scope, options) {
+        const key = this.key(scope);
+        const now = options.now ?? Date.now();
+        const held = this.claims.get(key);
+        // Held by somebody else and still live. Not an error: two readers on
+        // one queue is the ordinary case.
+        if (held && now < held.expiresAt && held.holder !== options.holder)
+            return null;
+        // A reclaim of an expired holding and a renewal by the current holder
+        // are the same write. The fence advances either way, so a previous
+        // holder that wakes up is fenced out in both cases — a renewal that
+        // kept the fence would leave a stalled twin able to write.
+        // Counted from the high-water mark, never from the live claim. A
+        // released run has no claim, and computing from that absence is what
+        // rewound the counter to 1 on every release.
+        const fence = (this.highWater.get(key) ?? 0) + 1;
+        const claim = { holder: options.holder, fence, expiresAt: now + options.ttlMs };
+        this.highWater.set(key, fence);
+        this.claims.set(key, claim);
+        return claim;
+    }
+    async releaseRun(scope, fence) {
+        const key = this.key(scope);
+        const held = this.claims.get(key);
+        // A stale fence releases nothing. A worker that stalled past its lease
+        // must not be able to hand away a run somebody else now holds.
+        //
+        // The high-water mark deliberately survives this. Dropping the claim
+        // returns the run to the queue; forgetting the number it reached would
+        // re-issue a fence a stalled worker still believes it holds.
+        if (!held || held.fence !== fence)
+            return;
+        this.claims.delete(key);
+        // And the counter steps past the released holding, because the disk
+        // store's release does: it appends a TOMBSTONE at `fence + 1`, which
+        // raises the maximum name and therefore the fence every later write is
+        // checked against. Without this step a holder that released could still
+        // write with the fence it just gave up — refused on disk, accepted here.
+        //
+        // The consequence is visible in the numbering: a released run's next
+        // claim is `fence + 2` in both stores, because the tombstone consumed
+        // one. That is parity, not an off-by-one.
+        this.highWater.set(key, fence + 1);
+    }
+    async writeCheckpoint(scope, checkpoint, fence) {
+        const key = this.key(scope);
+        // An unfenced write is allowed even on a claimed run: a host adopting
+        // claims on one worker must not break the workers that have not
+        // adopted them. A fenced write is checked, and that check is what
+        // makes the lease real.
+        if (fence !== undefined) {
+            // Against the HIGH-WATER MARK, not the live claim, and the difference
+            // is a silent loss rather than a duplicate.
+            //
+            // `releaseRun` deletes the claim. Reading `claims` here meant that
+            // between a release and the next take there was no holding to
+            // compare against, so `held` was `undefined` and every fence was
+            // accepted however stale. w1 stalls at fence 1; w2 reclaims at 2,
+            // finishes the work, releases cleanly; w1 wakes and writes with
+            // fence 1 — accepted — and its checkpoint carries a fresh
+            // `createdAt`, so it sorts newest and the next resume restores w1's
+            // stale history. w2's completed work is gone, with no error
+            // anywhere.
+            //
+            // The disk store refuses that write, because `currentFence` reads
+            // file names and the release tombstone raised the maximum. The
+            // minting side here already counted from the high-water mark; only
+            // the enforcement side was left reading the claim, so the two
+            // shipped stores disagreed at the one point that decides whether a
+            // lease is real.
+            const current = this.highWater.get(key) ?? 0;
+            if (fence < current)
+                throw fencedOut(scope, fence, current);
+        }
+        return this.writeUnchecked(scope, checkpoint);
+    }
+    async writeUnchecked(scope, checkpoint) {
         const key = this.key(scope);
         let run = this.runs.get(key);
         if (!run) {
@@ -74,8 +167,10 @@ export class InMemoryCheckpointStore {
             if (scope.sessionId !== undefined && runScope.sessionId !== scope.sessionId)
                 continue;
             const entry = toDurableRunEntry(runScope, [...checkpoints.values()], now);
-            if (entry)
-                entries.push(entry);
+            if (!entry)
+                continue;
+            const claim = this.claims.get(key);
+            entries.push(claim ? { ...entry, claim: toClaimSummary(claim, now) } : entry);
         }
         return paginateDurableRuns(entries, options);
     }

package/dist/store/run/checkpoint-memory.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint-memory.js","sourceRoot":"","sources":["../../../src/store/run/checkpoint-memory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"checkpoint-memory.js","sourceRoot":"","sources":["../../../src/store/run/checkpoint-memory.ts"],"names":[],"mappings":"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"}

package/dist/store/run/claim-disk.d.ts

@@ -0,0 +1,130 @@
+/**
+ * A run claim on a filesystem, correct across PROCESSES.
+ *
+ * ## The fence is the filename
+ *
+ * A run's claims live at `{runDir}/claims/{fence}.json`. Taking the run means
+ * exclusively creating the next number; the kernel makes exactly one of any
+ * number of simultaneous callers the creator, and every other gets `EEXIST`.
+ * The current holding is the highest-numbered file.
+ *
+ * That single decision is the whole mechanism, and it is what the first
+ * version of this file got wrong. That version kept ONE mutable `claim.json`
+ * and protected it with a lock, which needed a stale-lock breaker, which was
+ * `unlink` followed by an exclusive create — two operations. An adversarial
+ * pass reproduced the consequence from separate processes: two workers both
+ * judge a stale guard breakable, the second unlinks the FIRST one's fresh
+ * guard, both end up inside the section believing they hold it, neither has
+ * written yet so neither can be the loser of a re-read, and both write the
+ * same fence. Twenty-six of three hundred runs went to two workers at an
+ * identical fence — and an identical fence fences nobody out, because the
+ * comparison is `<`.
+ *
+ * Numbering the files instead removes every one of those steps. There is no
+ * lock to go stale, so no breaker, so no window. Concurrency is decided by
+ * one `O_CREAT | O_EXCL`.
+ *
+ * ## Four properties this layout gives for free
+ *
+ * **Monotonic across release and deletion.** Fences are file names that stay,
+ * so releasing cannot rewind the counter. Deleting `claim.json` used to send
+ * the next caller down a fresh-claim path that minted fence 1 again — so a
+ * worker stalled at fence 1 could write alongside the new holder, and the
+ * documented `finally { releaseRun() }` did it on every pass. Releasing here
+ * appends a tombstone rather than removing anything.
+ *
+ * **Unreadable content cannot wedge the run.** The fence is in the name, so a
+ * damaged or half-written body never hides the ordering. A caller reads the
+ * highest number and takes the next one; the previous holder, alive or not,
+ * is fenced out by arithmetic. Refusing to take an unparseable claim was safe
+ * against double-writing and left the run permanently unclaimable, which is
+ * the failure a lease exists to prevent.
+ *
+ * **The write-time fence check needs no parsing at all.** It compares a
+ * number against a directory listing, so a corrupt body cannot make the check
+ * skip itself.
+ *
+ * **No `rename` and no `unlink` on the contended path.** Renaming over a path
+ * another process merely holds open for reading fails on non-POSIX
+ * filesystems — measured at 84% under two concurrent readers — and a listing
+ * sweep reads exactly these files. Creating a new name never collides with a
+ * reader.
+ *
+ * ## The name appears already complete, because `link` publishes it
+ *
+ * An exclusive create decides the winner, but `wx` is open-THEN-write: for an
+ * instant the winning name exists and is empty. A reader landing in it parses
+ * nothing, reports the holding expired, and a second worker takes the next
+ * fence. Their fences differ so the loser's first checkpoint is refused — and
+ * both have already restored the run and executed its tools by then, and tool
+ * side effects are fenced by nothing.
+ *
+ * So the body is written to a temporary name first and the fence name is
+ * created by `link`ing to it. `link` fails `EEXIST` when the destination
+ * exists, so it arbitrates exactly as `wx` did, and the destination it creates
+ * is a second name for a file that was already whole. There is no instant at
+ * which the fence name exists and its body does not.
+ *
+ * Measured from separate OS processes on both platform families:
+ *
+ * - `link` refused an existing destination 20,000/20,000 times. Six writers
+ *   over 6,000 fences produced no fence with two winners and none with none.
+ * - Paired identical fixtures: `wx` showed an empty destination in 15,985 of
+ *   16,000 first observations, `link` in 0 of 16,000. All 156,000 frontier
+ *   observations were `ENOENT` or a complete parseable body — none empty, none
+ *   torn.
+ * - `rename` is disqualified, and not for the reason first assumed. It never
+ *   reports `EEXIST`; it silently REPLACES, 20,000/20,000. It cannot arbitrate
+ *   a race at all — two workers publishing one fence would both succeed and
+ *   the second would erase the first. (Its `EPERM`-under-readers failure is
+ *   real too, at 93.7% on the non-POSIX family, but the exclusivity failure
+ *   disqualifies it first.)
+ *
+ * Cost: three syscalls rather than one, +1.0 ms per acquisition on the
+ * non-POSIX family and +0.04 ms on POSIX, for an operation that runs once per
+ * run plus renewals.
+ *
+ * ## What it still does not do
+ *
+ * It does not detect liveness. Nothing can from here: a stalled holder, a
+ * suspended container and a partitioned network are indistinguishable, and
+ * they are indistinguishable from the holder's own side too, which is why it
+ * keeps writing. The fence is the answer — the write is checked, not the
+ * writer.
+ */
+import type { ClaimFence, ClaimRunOptions, RunClaim } from '../../types/run/checkpoint-store.js';
+/**
+ * The highest fence ever issued for this run, or 0 when it has never been
+ * claimed.
+ *
+ * Reads names only. This is deliberately the one question the contended path
+ * asks, because a name cannot be half-written: a file either exists or does
+ * not, where a body can be observed mid-write.
+ */
+export declare function currentFence(runDir: string): Promise<ClaimFence>;
+/**
+ * The run's current holding, or `null` when it has never been claimed.
+ *
+ * Returns `null` for an unreadable body too, and that is safe HERE in a way
+ * it was not in the previous design: the fence is known from the name
+ * regardless, so an unreadable body means "somebody took this number and its
+ * details are unavailable", and the caller's response is to take the NEXT
+ * number rather than to give up. Nothing is inferred from the absence.
+ */
+export declare function readClaim(runDir: string): Promise<RunClaim | null>;
+/** Take or extend the run's claim. `null` when somebody else holds it. */
+export declare function acquireClaim(runDir: string, options: ClaimRunOptions): Promise<RunClaim | null>;
+/**
+ * Give up a holding early, so the run returns to the queue without waiting
+ * out its lease.
+ *
+ * Appends a tombstone at the next fence rather than deleting anything. The
+ * counter must never rewind: a worker stalled at an old fence has to stay
+ * fenced out forever, and removing the record would let a later claimer be
+ * issued a number that stalled worker already believes it holds.
+ *
+ * A stale fence releases nothing — a worker that stalled past its lease must
+ * not be able to hand away a run somebody else now holds.
+ */
+export declare function releaseClaim(runDir: string, fence: ClaimFence): Promise<void>;
+//# sourceMappingURL=claim-disk.d.ts.map

package/dist/store/run/claim-disk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim-disk.d.ts","sourceRoot":"","sources":["../../../src/store/run/claim-disk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAA;AAoRhG;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAGtE;AA8DD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA6DxE;AAED,0EAA0E;AAC1E,wBAAsB,YAAY,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAoC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnF"}