@volter/world-core 3.0.154 → 3.0.156

package/dist/src/world-store.d.ts

@@ -7,6 +7,17 @@ export type WorldStat = {
     isDirectory: boolean;
     isSymbolicLink?: boolean;
 };
+/** Diagnostic context only; it does not change lock acquisition or stale-owner policy. */
+export type WorldLockOptions = {
+    retainLiveOwner?: boolean;
+    operation?: string;
+    caller?: string;
+};
+/** Capture at the outermost lock helper, then carry the same caller through nested helpers. */
+export declare function storageLockScope(options?: WorldLockOptions): WorldLockOptions & {
+    operation: string;
+    caller: string;
+};
 /**
  * The synchronous persistence seam. Every path is an ABSOLUTE key the caller already
  * computed (via `worldPaths`/`worldStateRoot`); the store treats it as an opaque key,
@@ -51,13 +62,57 @@ export interface WorldStore {
     readRange?(path: string, start: number): string | null;
     /** Resolve filesystem aliases for durable ownership; absent on opaque-key stores. */
     canonicalPath?(path: string): string;
+    /** `read`, for a small file every operation needs and few change (a branch's pointer, the World's clock): the text
+     *  kept from the last read while the path's own facts stand, so an unchanged file costs one check and no read.
+     *  Optional: a store without it is read. */
+    readKept?(path: string): string | null;
+    /** The facts of the generation kept beside a tree's files in `dirPath` (TREE_FILES): one string that differs after
+     *  any write of one of them through a store, by this process or another; `null` where the directory has none yet,
+     *  which says nothing. Optional: a store without it is asked for each file's own facts. */
+    generation?(dirPath: string): string | null;
+    /** The generation in `dirPath` now, when exactly one write of a tree's file through a store has moved it since
+     *  `before` (a generation this store answered for it); `null` when it cannot say so. A writer that read `before` just
+     *  ahead of its own write, holding the directory's history lock, learns that its write was the only one (log.ts
+     *  appendToBranchLog). Optional, beside `generation`. */
+    generationAfterOwnWrite?(dirPath: string, before: string): string | null;
     /** Run `fn` holding an exclusive lock on `lockPath`, releasing it afterwards. The fs
      *  backend uses the historical cross-process reclaimable file lock; an in-memory,
      *  single-instance backend is a synchronous pass-through. */
-    withLock<T>(lockPath: string, fn: () => T, options?: {
-        retainLiveOwner?: boolean;
-    }): T;
+    withLock<T>(lockPath: string, fn: () => T, options?: WorldLockOptions): T;
 }
+/** The files a service's tree is folded from, by name in its state directory (log.ts: the parent log, the branch log,
+ *  the branch's pointer), and the generation a store keeps beside them. */
+export declare const TREE_FILES: {
+    readonly parent: "events.jsonl";
+    readonly branch: "actions.jsonl";
+    readonly pointer: "branch.json";
+};
+export declare const TREE_GENERATION = "tree.generation";
+/**
+ * A WORLD'S CARRIED LOCKS, REMOVED AT ITS OPEN (S2 K4). A World booted over its kept state (`up --keep-state`, a
+ * tab's restored archive) carries whatever lock files its last life left in its services' state directories. One whose
+ * holder record cannot be read is no holder's once its taker has gone, and a restore gives it the restore's file time,
+ * so the empty-record grace and the 60 s age ran from the restore: every waiter waited them, or gave up at 10 s (Twenty
+ * e946aa4c run 2: anthropic's projection.lock, "holder record unreadable", 10,086 ms, then its credentials 500 and the
+ * server 10 s late). A carried `.recovery` that is not empty and does not parse was never ended by R13's rule at all.
+ *
+ * A file is carried only when all of these hold: it is a world-core lock or its reclaim record (`*.lock`,
+ * `*.lock.recovery`) in a service's state directory (`<root>/<service>/<stateDir>/world`, never a yarn.lock or any
+ * project file); its text is empty or a holder record's beginning (`{"pid"`) that does not parse; and its file time is
+ * before `before`, the start of this boot's claim. A restore sets the time before the claim; a taker that is live now
+ * (a CLI's changeset rebase, a branch World keeping this one as its parent's storage, a two-call taker between its
+ * create and its record) made its file after it. Each removal is still a reclaimer's: a lock's under its `.recovery`,
+ * taken with its record (createRecorded), a held `.recovery` skipped; the file read again, renamed aside, the aside copy
+ * read again and linked back where it now holds a record (EEXIST there is the path taken since, left to its holder).
+ * A record that parses is kept, under its rules (a dead holder's, our own pid's, the 60 s age, which a restore resets:
+ * not this rule's). Answers the paths removed.
+ */
+export declare function removeCarriedLocks(roots: readonly string[], options: {
+    stateDir: string;
+    before: number;
+}): string[];
+/** Name a bookkeeping phase within an existing acquisition; never acquire another lock. */
+export declare function withStorageLockOperation<T>(path: string, operation: string, fn: () => T): T;
 /**
  * The default store: a thin, faithful pass-through to `node:fs`. Every method preserves
  * the exact behavior the kernel had before the seam existed — the durable append
@@ -66,6 +121,51 @@ export interface WorldStore {
  */
 export declare class FsWorldStore implements WorldStore {
     read(path: string): string | null;
+    /**
+     * A small file's text, kept while its own facts stand. THE GUARANTEE: the key is the path's own lstat (device,
+     * inode, size, modification and change times); this process's own writes through the store drop what is kept at
+     * once; another process's write is seen when any of those facts moves. That is the guarantee a tree's stamp
+     * already rests on for its logs (their size and modification time), with the inode and change time added: a
+     * replaced file (writeAtomic) is another inode, a file written in place has another time. What it cannot see is a
+     * rewrite to the same size on the same or a reused inode within one tick of the file system's clock, with no check
+     * between; the logs' stamp has the same limit. A link is read through, and not kept.
+     * A text read after a write that came between the lstat and the read is kept under the OLDER key, so the next
+     * check finds the facts moved and reads again: what is kept is never newer than its key, and never served past it.
+     */
+    private readonly kept;
+    readKept(path: string): string | null;
+    /**
+     * A TREE'S GENERATION: one file beside a tree's three files, a byte longer after every write of any of them, so a
+     * reader that has the tree's stamp asks ONE question to know it still stands (log.ts treeFacts), where it asked
+     * three, two of them of files a World with no parent does not have.
+     *
+     * WHAT MAKES IT SOUND. A writer appends a byte BEFORE its write and another AFTER it; a reader takes the
+     * generation's facts BEFORE it reads the files' own. The file only grows, so its size never repeats on one inode,
+     * and a replaced or removed file is another inode or none. So for any write W and any reader that kept a stamp S
+     * under generation G: if W's first byte is after G was read, the kept G is behind and S is not served; if it is
+     * before, then either W itself was before S's own reads (S holds it), or W's second byte is after G was read, and
+     * again G is behind. An append is one call the system orders among all writers: each byte is one append of its
+     * own, whole or not at all, on a POSIX filesystem and in a tab's one kernel (browser-substrate
+     * packages/node/src/kernel-virtual-filesystem.ts appendFileSync, an O_APPEND open and writeAll, which sends a write
+     * of at most DATA_BYTES as one SYS_write request the kernel serves whole; or, by a file step, its table's own
+     * O_APPEND open and write of the one byte, filesystem.ts appendFileBytes). The proof rests on that; log.ts
+     * appendToBranchLog's (`generationAfterOwnWrite`: one write is exactly two bytes) as well.
+     *
+     * WHERE THAT STOPS. (1) A writer that dies between its write and its second byte, with a reader's whole check
+     * between its first byte and its write: that reader keeps the older stamp until the next write of the tree. (2) A
+     * writer of these files that does not come through a store of this version (an older package, a copy made over a
+     * live directory by another program): the generation does not move. A directory made or removed whole has no
+     * generation or another's, which serves nothing kept. (3) A stamp that names files outside its own directory (a
+     * World with a parent: its view and its ancestors' logs) is never kept under a generation (log.ts).
+     */
+    generation(dirPath: string): string | null;
+    /** One write is `moved` twice, a byte each: the same file, those two bytes longer. */
+    generationAfterOwnWrite(dirPath: string, before: string): string | null;
+    /** One more byte on the generation beside `path`, where `path` is one of a tree's files. A directory that is not
+     *  there has no reader to tell: the write that makes it is followed by the byte that makes its generation. */
+    private moved;
+    /** A write of `path`, with the generation beside it moved before and after where it is one of a tree's files. */
+    private writing;
     readLines(path: string): string[];
     readRange(path: string, start: number): string | null;
     append(path: string, data: string): void;
@@ -79,17 +179,18 @@ export declare class FsWorldStore implements WorldStore {
     remove(path: string): void;
     mkdir(dirPath: string): void;
     list(dirPath: string): string[];
+    /** The real path of each path already resolved: a state directory's does not move under a running process, and
+     *  every history lock asked for it again. A path that does not exist yet is not kept. */
+    private readonly canonical;
     canonicalPath(path: string): string;
     stat(path: string): WorldStat | null;
     /** Run `fn` holding an exclusive cross-process file lock. The lockfile records
-     *  `{pid, hostname, at}`; a contender that finds a stale lock (dead pid or age >
+     *  identity, operation, caller and any nested wait; a contender that finds a stale lock (dead pid or age >
      *  LOCK_STALE_MS) reclaims it by atomically renaming it aside — so a crashed holder
      *  can't wedge the world forever. Reclaim is race-safe: only the process that wins
      *  the rename clears the stale inode, and the exclusive `wx` create still decides the
      *  winner. (Moved verbatim from storage.ts `withFileLock`.) */
-    withLock<T>(lockPath: string, fn: () => T, options?: {
-        retainLiveOwner?: boolean;
-    }): T;
+    withLock<T>(lockPath: string, fn: () => T, options?: WorldLockOptions): T;
 }
 /**
  * An in-memory store. Files are entries in a `Map<path, string>`; directories are