@namzu/sdk 20.3.0 → 20.4.0

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"}