@demlik/tea 0.20.0 → 0.22.0

package/dist/loop-DReKGV1X.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The core loop both engines run (#280, spike #264). It does five things and
+ * nothing else: it keeps one serial tail, folds a Msg into a transition, saves
+ * before any effect, reconciles the running Subs, and runs the transition's
+ * Cmds, dispatching what they return. It has no special case for any built-in.
+ *
+ * One loop, not one per engine (#283). The loop calls a handler and a runner
+ * through erased signatures and awaits a Promise either way, so an engine's
+ * own types never pass through it. The Effect engine turns each handler and
+ * runner into a fiber at its own edge, run with the services the caller
+ * provided, so Effect services (`R`) reach every handler without the loop
+ * carrying a type slot for them — the gap spike #260's generic loop left open.
+ * Sharing the loop is also what makes the two engines' traces identical: the
+ * fold, the save order and the built-ins are the same code.
+ *
+ * Everything else `run` offers is an {@link Extension} built on ten points:
+ *
+ *   1. `update`    — middleware over the fold. Returning `null` means "no
+ *                    transition": no save, no effects, no commit.
+ *   2. `interpret` — middleware over one Cmd's handler call; it maps what the
+ *                    handler returned to the Msgs to dispatch, if any.
+ *   3. `store`     — a wrapper over the store the caller handed `run`.
+ *   4. `installed` — called once a transition's State is past its save and its
+ *                    Subs are reconciled, before its first Cmd's handler starts.
+ *                    This is Elm's `view`: it never waits on a Cmd (#695).
+ *   5. `commit`    — called after a transition's effects, with the Msg and the
+ *                    committed State, even when a Cmd handler threw. Boot
+ *                    passes `undefined` for the Msg.
+ *   6. `saveFailed` — called when a transition's save rejects, before that
+ *                    rejection reaches the dispatch caller.
+ *   7. `subFailed` — called when a Sub's failure stops the run, before the
+ *                    engine is told to stop it.
+ *   8. `halted`    — called when an extension halts the run with an error.
+ *   9. `drained`   — called once no Msg can fold any more, so the State is the
+ *                    run's last: `stop()` has finished with the queue, the
+ *                    host's or the one a failure started.
+ *  10. `ctx`       — keys added to the ctx every Cmd handler receives, so a
+ *                    handler that runs another handler inside its own can reach
+ *                    the same machinery the loop applies to it.
+ *
+ * An extension may also add methods to the run handle (`handle`). Array order
+ * is nesting order: the first extension's middleware is the outermost, and
+ * `installed` and commit callbacks run first to last. `builtinExtensions`
+ * (`./builtins`) fixes that order for every engine; it is not a user-facing
+ * plugin API (#268).
+ *
+ * `stop()` is the core's own lifecycle, because the gate it drives is what every
+ * dispatch passes through: open → draining → closed, or → abandoned when
+ * `stop()` gives up on the queue (ADR 0025), never backwards.
+ */
+
+declare const post: unique symbol;
+/**
+ * What `tell` answers, at once, about the Msg it was handed. It says where the
+ * Msg stands at that moment and nothing about how it ends.
+ *
+ *   - `"queued"`: the Msg is on the receiver's line. It has not been handled.
+ *   - `"stopped"`: the receiver is stopping or has stopped, so the Msg is not on
+ *     its line and never will be.
+ *   - `"no_cell"`: the receiver's current State has no cell for the Msg, so the
+ *     Msg is not on its line. That reads the State as it is now, not the State
+ *     the Msgs already in line will leave.
+ */
+type TellAnswer = "queued" | "stopped" | "no_cell";
+/** A run handle `tell` can reach the line of. */
+interface Postable<S, M> {
+    readonly [post]: (msg: M, takes: (state: S) => boolean) => TellAnswer;
+}
+
+export type { Postable as P, TellAnswer as T };

package/dist/{machine-Dtre2TmN.d.ts → machine-C0WhOAyB.d.ts}

@@ -1,9 +1,9 @@
-import { C as Cmd, r as Tagged, I as Interpret, A as AnyCmdDef, a as CmdOf, b as CmdDef, h as Settled, s as OkOf, t as ErrOf, n as MalformedResult, O as Outcome, u as CmdValue, H as HandlerCtx, f as TaggedError, M as Machine, c as Subscribe } from './core-CtvAyPpH.js';
-import { b as MonitoredRunState, R as RunFailure, M as MonitoredRunCmd } from './index-CZZ3HI-Z.js';
-import { R as RunCmd, S as SucceedMsg, F as FailMsg, b as ResilientState, r as RunCmdDef } from './index-CKtEKGyp.js';
-import { D as DeadlineExceeded, a as DeadlineSub, b as DeadlinesSub } from './index-CVU7SK3a.js';
+import { C as Cmd, s as Tagged, I as Interpret, A as AnyCmdDef, a as CmdOf, b as CmdDef, h as Settled, t as OkOf, u as ErrOf, o as MalformedResult, O as Outcome, v as CmdValue, H as HandlerCtx, f as TaggedError, M as Machine, S as Subscribe } from './core-DNDAEhO2.js';
+import { b as MonitoredRunState, R as RunFailure, M as MonitoredRunCmd } from './index-CAsUE_d1.js';
+import { R as RunCmd, S as SucceedMsg, F as FailMsg, b as ResilientState, r as RunCmdDef } from './index-C92SgNWz.js';
+import { D as DeadlineExceeded, a as DeadlineSub, b as DeadlinesSub } from './index-Cg0QXnzf.js';
 import { M as MsgType, a as MsgTypeValue } from './protocol-ClRZBhHQ.js';
-import { F as FanOutState } from './index-CrcoVfd_.js';
+import { F as FanOutState } from './index-9P1PaXIV.js';
 import { RetryPolicy, AnyRetryPolicy } from './retry-backoff/index.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
@@ -1197,7 +1197,7 @@ declare function omitMedia(parts: readonly ContentPart[]): readonly ContentPart[
  * @demlik/tea/agent — the one construction every tool definition goes through.
  *
  * NOT part of the public `./agent` barrel. `tool()` and `agentTool()` are two
- * doors onto the same `ToolDef`: `tool()` hands its handler the parsed `args`,
+ * constructors of the same `ToolDef`: `tool()` hands its handler the parsed `args`,
  * and `agentTool()` needs the whole Cmd — `callId` included — because the call's
  * identity is what keys the child run. Both are built here, so the reserved-name
  * refusal, the `thrown` channel and the resilience knob have one definition.
@@ -1227,7 +1227,7 @@ declare const SNAPSHOT_WRITE_TYPE = "snapshot_write";
  * `snapshot_write`, which `toMachine` merges under the consumer's key.
  */
 type ReservedToolName = MsgTypeValue | SettlePrefixOf<MsgTypeValue> | typeof REJECTED_TYPE | typeof SNAPSHOT_WRITE_TYPE;
-/** Whether `name` is one a tool door refuses — the set `ReservedToolName` types. */
+/** Whether `name` is one a tool constructor refuses — the set `ReservedToolName` types. */
 declare function isReservedToolName(name: string): name is ReservedToolName;
 /**
  * Widens to `unknown` for a name outside the reserved set and to `never`

package/dist/machine-viz/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-CtvAyPpH.js';
+import { C as Cmd, c as Sub, M as Machine } from '../core-DNDAEhO2.js';
 import '@standard-schema/spec';
 
 /**

package/dist/machine-viz/index.js

@@ -1,5 +1,5 @@
-import '../chunk-DVNXEB7V.js';
-import { formOf, subEntriesOf, desiredSub } from '../chunk-RKVUVALV.js';
+import '../chunk-BVFS3ICC.js';
+import { formOf, subEntriesOf, desiredSub } from '../chunk-A3QPMX5M.js';
 
 // src/machine-viz/mermaid-id.ts
 function safeId(raw) {

package/dist/mem/index.d.ts

@@ -1,5 +1,5 @@
-import { M as Migrated, D as DeletableStore, F as FencedStore } from '../runtime-types-DEluQgGO.js';
-import '../core-CtvAyPpH.js';
+import { M as Migrated, D as DeletableStore, F as FencedStore } from '../runtime-types-CP-ykwgf.js';
+import '../core-DNDAEhO2.js';
 import '@standard-schema/spec';
 
 /**
@@ -39,7 +39,8 @@ interface MemoryStoreOptions {
      * store is a `FencedStore<S>` whose version is an in-process counter — honest
      * for this adapter, since the cell it guards is in this process too. Two
      * `run`s handed the SAME `memoryStore` are the case it catches, and it is the
-     * cheapest way to exercise the fenced path in a test.
+     * cheapest way to exercise the fenced path in a test. A run on a fenced store
+     * must be given an `onError` (see `StoreAndOnError`).
      */
     readonly fenced?: true;
 }

package/dist/mem/index.js

@@ -1,5 +1,5 @@
-import '../chunk-DVNXEB7V.js';
-import { StoreConflictError } from '../chunk-RKVUVALV.js';
+import '../chunk-BVFS3ICC.js';
+import { StoreConflictError } from '../chunk-A3QPMX5M.js';
 
 // src/mem/index.ts
 function memoryStore(initial, parse = (raw) => raw, options = {}) {

package/dist/mem/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mem/index.ts"],"names":[],"mappings":";;;;AAsEO,SAAS,WAAA,CACd,SACA,KAAA,GAAuC,CAAC,QAAQ,GAAA,EAChD,OAAA,GAA8B,EAAC,EAC2B;AAG1D,EAAA,IAAI,OAAiB,OAAA,IAAW,IAAA;AAGhC,EAAA,IAAI,OAAA,GAAU,CAAA;AAEd,EAAA,MAAM,IAAA,GAA0B;AAAA,IAC9B,MAAM,IAAA,GAAyB;AAC7B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA;AAAA,IACA,MAAM,KAAK,KAAA,EAAyB;AAClC,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,OAAA,IAAW,CAAA;AAAA,IACb,CAAA;AAAA,IACA,QAAQ,GAAA,EAA2B;AACjC,MAAA,OAAO,MAAM,GAAG,CAAA;AAAA,IAClB,CAAA;AAAA,IACA,MAAM,MAAA,GAAwB;AAG5B,MAAA,IAAA,GAAO,IAAA;AACP,MAAA,OAAA,GAAU,CAAA;AAAA,IACZ;AAAA,GACF;AACA,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,IAAA,EAAM,OAAO,IAAA;AAEpC,EAAA,OAAO;AAAA,IACL,GAAG,IAAA;AAAA,IACH,MAAA,EAAQ,IAAA;AAAA,IACR,MAAM,UAAA,GAAyD;AAC7D,MAAA,OAAO,EAAE,GAAA,EAAK,IAAA,EAAM,OAAA,EAAQ;AAAA,IAC9B,CAAA;AAAA,IACA,MAAM,UAAA,CAAW,KAAA,EAAU,eAAA,EAA0C;AAInE,MAAA,IAAI,YAAY,eAAA,EAAiB;AAC/B,QAAA,MAAM,IAAI,kBAAA,CAAmB,eAAA,EAAiB,OAAO,CAAA;AAAA,MACvD;AACA,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,OAAA,IAAW,CAAA;AACX,MAAA,OAAO,OAAA;AAAA,IACT;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\n * @demlik/tea/mem — in-memory `Store<S>` adapter for `@demlik/tea`.\n *\n * The standard test adapter — used everywhere a Worker or DO would be\n * overkill. Mirrors the source-only convention from `packages/widget-engine`\n * and `packages/tea` (no build step).\n *\n * Reference semantics, NOT deep-clone semantics:\n *   - `save(state)` stores the reference; subsequent mutations to that\n *     reference by the caller are observable through later `load()` calls.\n *   - `load()` returns the stored reference; mutations made through it are\n *     observable on the next `load()`.\n *\n * This matches what a real KV/DO `get()` would NOT do (those serialize +\n * deserialize), but it also matches what an in-memory cache obviously does.\n * Adding a deep clone here would lie about the boundary and impose a JSON\n * round-trip on every test. Tests that need fresh copies should clone at the\n * call site.\n *\n * Boundary parse (invariant 8): `Store<S>` requires `migrate(raw)`. For\n * `memoryStore` we ship a permissive identity-default — `(raw) => raw as\n * S | null` — because this adapter is a degenerate same-process boundary:\n * there is no serialization, the reference we read is structurally the\n * reference we wrote. The `as` cast here is the documented exception to the\n * invariant-8 no-`as` rule, scoped to the parameter default. Callers that\n * want strict parsing (e.g. a test that hand-seeds the cell from outside)\n * may pass an explicit `parse` to override.\n */\n\nimport type { DeletableStore, FencedStore, Migrated } from \"../index\";\nimport { StoreConflictError } from \"../index\";\n\n/** Options for {@link memoryStore}. */\nexport interface MemoryStoreOptions {\n  /**\n   * Refuse a second live writer (#143). With `{ fenced: true }` the returned\n   * store is a `FencedStore<S>` whose version is an in-process counter — honest\n   * for this adapter, since the cell it guards is in this process too. Two\n   * `run`s handed the SAME `memoryStore` are the case it catches, and it is the\n   * cheapest way to exercise the fenced path in a test.\n   */\n  readonly fenced?: true;\n}\n\n/**\n * Build an in-memory `Store<S>`.\n *\n * @param initial - optional seed value. `undefined` and explicit `null` both\n *   mean \"no seed\"; `load()` resolves with `null` until the first `save()`.\n *   A concrete `S` seed is returned by `load()` until overwritten.\n * @param parse - optional boundary parse for the `Store<S>.migrate` contract.\n *   Defaults to identity (`(raw) => raw as S | null`) — honest for this\n *   adapter's degenerate same-process boundary. Pass an explicit parser when\n *   the test wants to reject seeded shapes that don't match `S`.\n */\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse?: (raw: unknown) => Migrated<S>,\n): DeletableStore<S>;\nexport function memoryStore<S>(\n  initial: S | null | undefined,\n  parse: ((raw: unknown) => Migrated<S>) | undefined,\n  options: MemoryStoreOptions & { readonly fenced: true },\n): FencedStore<S> & DeletableStore<S>;\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse?: (raw: unknown) => Migrated<S>,\n  options?: MemoryStoreOptions,\n): DeletableStore<S> | (FencedStore<S> & DeletableStore<S>);\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse: (raw: unknown) => Migrated<S> = (raw) => raw as S | null,\n  options: MemoryStoreOptions = {},\n): DeletableStore<S> | (FencedStore<S> & DeletableStore<S>) {\n  // Single internal cell — `undefined` and `null` collapse to one\n  // representation so the load site is branchless.\n  let cell: S | null = initial ?? null;\n  // The version the cell was last written at. A never-written cell reads `0`,\n  // matching `fileStore`'s absent stamp.\n  let version = 0;\n\n  const base: DeletableStore<S> = {\n    async load(): Promise<unknown> {\n      return cell;\n    },\n    async save(state: S): Promise<void> {\n      cell = state;\n      version += 1;\n    },\n    migrate(raw: unknown): Migrated<S> {\n      return parse(raw);\n    },\n    async delete(): Promise<void> {\n      // Back to never-written: an empty cell at version `0`. The seed is gone\n      // too — `load()` answers what an unseeded store answers.\n      cell = null;\n      version = 0;\n    },\n  };\n  if (options.fenced !== true) return base;\n\n  return {\n    ...base,\n    fenced: true,\n    async loadFenced(): Promise<{ raw: unknown; version: number }> {\n      return { raw: cell, version };\n    },\n    async saveFenced(state: S, expectedVersion: number): Promise<number> {\n      // No lock: the whole store is one process's memory, and this body has no\n      // await before the compare, so nothing can interleave between the check\n      // and the write.\n      if (version !== expectedVersion) {\n        throw new StoreConflictError(expectedVersion, version);\n      }\n      cell = state;\n      version += 1;\n      return version;\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../../src/mem/index.ts"],"names":[],"mappings":";;;;AAuEO,SAAS,WAAA,CACd,SACA,KAAA,GAAuC,CAAC,QAAQ,GAAA,EAChD,OAAA,GAA8B,EAAC,EAC2B;AAG1D,EAAA,IAAI,OAAiB,OAAA,IAAW,IAAA;AAGhC,EAAA,IAAI,OAAA,GAAU,CAAA;AAEd,EAAA,MAAM,IAAA,GAA0B;AAAA,IAC9B,MAAM,IAAA,GAAyB;AAC7B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA;AAAA,IACA,MAAM,KAAK,KAAA,EAAyB;AAClC,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,OAAA,IAAW,CAAA;AAAA,IACb,CAAA;AAAA,IACA,QAAQ,GAAA,EAA2B;AACjC,MAAA,OAAO,MAAM,GAAG,CAAA;AAAA,IAClB,CAAA;AAAA,IACA,MAAM,MAAA,GAAwB;AAG5B,MAAA,IAAA,GAAO,IAAA;AACP,MAAA,OAAA,GAAU,CAAA;AAAA,IACZ;AAAA,GACF;AACA,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,IAAA,EAAM,OAAO,IAAA;AAEpC,EAAA,OAAO;AAAA,IACL,GAAG,IAAA;AAAA,IACH,MAAA,EAAQ,IAAA;AAAA,IACR,MAAM,UAAA,GAAyD;AAC7D,MAAA,OAAO,EAAE,GAAA,EAAK,IAAA,EAAM,OAAA,EAAQ;AAAA,IAC9B,CAAA;AAAA,IACA,MAAM,UAAA,CAAW,KAAA,EAAU,eAAA,EAA0C;AAInE,MAAA,IAAI,YAAY,eAAA,EAAiB;AAC/B,QAAA,MAAM,IAAI,kBAAA,CAAmB,eAAA,EAAiB,OAAO,CAAA;AAAA,MACvD;AACA,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,OAAA,IAAW,CAAA;AACX,MAAA,OAAO,OAAA;AAAA,IACT;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\n * @demlik/tea/mem — in-memory `Store<S>` adapter for `@demlik/tea`.\n *\n * The standard test adapter — used everywhere a Worker or DO would be\n * overkill. Mirrors the source-only convention from `packages/widget-engine`\n * and `packages/tea` (no build step).\n *\n * Reference semantics, NOT deep-clone semantics:\n *   - `save(state)` stores the reference; subsequent mutations to that\n *     reference by the caller are observable through later `load()` calls.\n *   - `load()` returns the stored reference; mutations made through it are\n *     observable on the next `load()`.\n *\n * This matches what a real KV/DO `get()` would NOT do (those serialize +\n * deserialize), but it also matches what an in-memory cache obviously does.\n * Adding a deep clone here would lie about the boundary and impose a JSON\n * round-trip on every test. Tests that need fresh copies should clone at the\n * call site.\n *\n * Boundary parse (invariant 8): `Store<S>` requires `migrate(raw)`. For\n * `memoryStore` we ship a permissive identity-default — `(raw) => raw as\n * S | null` — because this adapter is a degenerate same-process boundary:\n * there is no serialization, the reference we read is structurally the\n * reference we wrote. The `as` cast here is the documented exception to the\n * invariant-8 no-`as` rule, scoped to the parameter default. Callers that\n * want strict parsing (e.g. a test that hand-seeds the cell from outside)\n * may pass an explicit `parse` to override.\n */\n\nimport type { DeletableStore, FencedStore, Migrated } from \"../index\";\nimport { StoreConflictError } from \"../index\";\n\n/** Options for {@link memoryStore}. */\nexport interface MemoryStoreOptions {\n  /**\n   * Refuse a second live writer (#143). With `{ fenced: true }` the returned\n   * store is a `FencedStore<S>` whose version is an in-process counter — honest\n   * for this adapter, since the cell it guards is in this process too. Two\n   * `run`s handed the SAME `memoryStore` are the case it catches, and it is the\n   * cheapest way to exercise the fenced path in a test. A run on a fenced store\n   * must be given an `onError` (see `StoreAndOnError`).\n   */\n  readonly fenced?: true;\n}\n\n/**\n * Build an in-memory `Store<S>`.\n *\n * @param initial - optional seed value. `undefined` and explicit `null` both\n *   mean \"no seed\"; `load()` resolves with `null` until the first `save()`.\n *   A concrete `S` seed is returned by `load()` until overwritten.\n * @param parse - optional boundary parse for the `Store<S>.migrate` contract.\n *   Defaults to identity (`(raw) => raw as S | null`) — honest for this\n *   adapter's degenerate same-process boundary. Pass an explicit parser when\n *   the test wants to reject seeded shapes that don't match `S`.\n */\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse?: (raw: unknown) => Migrated<S>,\n): DeletableStore<S>;\nexport function memoryStore<S>(\n  initial: S | null | undefined,\n  parse: ((raw: unknown) => Migrated<S>) | undefined,\n  options: MemoryStoreOptions & { readonly fenced: true },\n): FencedStore<S> & DeletableStore<S>;\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse?: (raw: unknown) => Migrated<S>,\n  options?: MemoryStoreOptions,\n): DeletableStore<S> | (FencedStore<S> & DeletableStore<S>);\nexport function memoryStore<S>(\n  initial?: S | null,\n  parse: (raw: unknown) => Migrated<S> = (raw) => raw as S | null,\n  options: MemoryStoreOptions = {},\n): DeletableStore<S> | (FencedStore<S> & DeletableStore<S>) {\n  // Single internal cell — `undefined` and `null` collapse to one\n  // representation so the load site is branchless.\n  let cell: S | null = initial ?? null;\n  // The version the cell was last written at. A never-written cell reads `0`,\n  // matching `fileStore`'s absent stamp.\n  let version = 0;\n\n  const base: DeletableStore<S> = {\n    async load(): Promise<unknown> {\n      return cell;\n    },\n    async save(state: S): Promise<void> {\n      cell = state;\n      version += 1;\n    },\n    migrate(raw: unknown): Migrated<S> {\n      return parse(raw);\n    },\n    async delete(): Promise<void> {\n      // Back to never-written: an empty cell at version `0`. The seed is gone\n      // too — `load()` answers what an unseeded store answers.\n      cell = null;\n      version = 0;\n    },\n  };\n  if (options.fenced !== true) return base;\n\n  return {\n    ...base,\n    fenced: true,\n    async loadFenced(): Promise<{ raw: unknown; version: number }> {\n      return { raw: cell, version };\n    },\n    async saveFenced(state: S, expectedVersion: number): Promise<number> {\n      // No lock: the whole store is one process's memory, and this body has no\n      // await before the compare, so nothing can interleave between the check\n      // and the write.\n      if (version !== expectedVersion) {\n        throw new StoreConflictError(expectedVersion, version);\n      }\n      cell = state;\n      version += 1;\n      return version;\n    },\n  };\n}\n"]}

package/dist/node/index.d.ts

@@ -1,6 +1,6 @@
 import WebSocket from 'ws';
-import { M as Migrated, D as DeletableStore, F as FencedStore } from '../runtime-types-DEluQgGO.js';
-import { S as Sub, D as Dispose } from '../core-CtvAyPpH.js';
+import { M as Migrated, D as DeletableStore, F as FencedStore } from '../runtime-types-CP-ykwgf.js';
+import { c as Sub, D as Dispose } from '../core-DNDAEhO2.js';
 import '@standard-schema/spec';
 
 /**
@@ -79,6 +79,30 @@ interface Journal<R> {
     withLock<A>(stream: string, fx: () => Promise<A>): Promise<A>;
 }
 
+/**
+ * Why a writer could not take a lock:
+ *
+ * - `another-host`: the lock names another host, which may still be writing.
+ * - `live-holder`: its process is alive on this machine, or its old-format id
+ *   names a live process here.
+ * - `unwritten`: the lock is empty and too young to count as a crash.
+ * - `unreadable`: its contents are not a lock this version can read.
+ * - `contended`: no one holder was to blame; other writers kept taking it.
+ */
+type FileLockBlock = "another-host" | "live-holder" | "unwritten" | "unreadable" | "contended";
+/**
+ * A write gave up waiting for a lock file. `lockPath` names the file to clear
+ * and `blockedBy` says why it could not be taken. The write did not happen.
+ */
+declare class FileLockTimeoutError extends Error {
+    readonly lockPath: string;
+    readonly waitedMs: number;
+    readonly blockedBy: FileLockBlock;
+    readonly name = "FileLockTimeoutError";
+    readonly _tag: "file_lock_timeout";
+    constructor(lockPath: string, waitedMs: number, blockedBy: FileLockBlock);
+}
+
 /**
  * @packageDocumentation
  * @demlik/tea/node — Node host adapter for `@demlik/tea`.
@@ -158,6 +182,25 @@ interface FileStoreOptions {
      * that started from the same version is refused with a `StoreConflictError`
      * at its next save. Omit it and the store is exactly as it was — the last
      * writer wins, and single-writer is the caller's precondition to keep.
+     *
+     * A run on a fenced store must be given an `onError`, or it does not compile
+     * (see `StoreAndOnError`). A lost fence can surface with no caller to reject
+     * at, under `"stop-save"` or `"follow-up"`, and the default sink would rethrow
+     * it and end the process. Treat a `StoreConflictError` there as this run having
+     * moved to another process: stop that run, and leave the others alone.
+     *
+     * Each save and `delete()` takes a lock file, `<path>.fence.lock`, and a
+     * writer that dies holding it leaves it behind. The next write steals a lock
+     * whose holder is proven gone: an empty one older than a short grace period,
+     * one from an earlier boot of this machine, or one whose process is dead.
+     *
+     * Any other lock is waited on for up to 10 seconds, and then the write rejects
+     * with a {@link FileLockTimeoutError} naming the file. That includes a lock
+     * from another host, which is never stolen because that host may be live on a
+     * shared volume. So a folder restored onto a new machine can need one clear
+     * step: once the old machine is known to be gone, delete the file. Hosts are
+     * told apart by `os.hostname()`, so give two live hosts on one volume two
+     * names.
      */
     readonly fenced?: true;
 }
@@ -176,12 +219,17 @@ interface FileStoreOptions {
  * O(n) in the stream's length; a durable record log a machine replays is read
  * whole anyway, so the atomic-rewrite guarantee is worth the cost.
  *
- * The ordering key is taken under a `wx` lock file (`<file>.lock`) holding the
- * writer's PID: a second writer racing the same stream blocks on the lock, so
- * `seq` is a single total order across processes. A crashed writer's lock is
- * stolen once its PID proves dead (`process.kill(pid, 0)` → `ESRCH`), so a
- * crash never wedges the stream. This is the lock phoenix spike #6673 proved:
- * its only job is an honest order key, not the win.
+ * The ordering key is taken under a `wx` lock file (`<file>.lock`) naming the
+ * writer's host, boot and PID: a second writer racing the same stream blocks on
+ * the lock, so `seq` is a single total order across processes. This is the lock
+ * phoenix spike #6673 proved: its only job is an honest order key, not the win.
+ *
+ * A leftover lock behaves as it does on a fenced {@link fileStore}: one whose
+ * holder is proven gone is stolen, so a crash on this machine does not wedge the
+ * stream. Any other lock, including one from another host, is waited on for up
+ * to 10 seconds, and then the append rejects with a
+ * {@link FileLockTimeoutError} naming the file. See
+ * {@link FileStoreOptions.fenced} for the cases and the clear step.
  *
  * `changes` fires for appends made through THIS instance; a cross-process
  * append lands on disk but is not broadcast here (that is a polling concern the
@@ -315,4 +363,4 @@ interface NodeSubscribeWithWs<M, Ctx extends NodeSubscribeCtx> extends NodeSubsc
 declare function nodeSubscribe<M>(): NodeSubscribeBase<M>;
 declare function nodeSubscribe<M, Ctx extends NodeSubscribeCtx>(opts: NodeSubscribeOpts<M>): NodeSubscribeWithWs<M, Ctx>;
 
-export { type FileStoreOptions, type NodeSignalDeps, type NodeSignalSub, type NodeSub, type NodeSubscribeBase, type NodeSubscribeCtx, type NodeSubscribeOpts, type NodeSubscribeWithWs, type NodeTimerDeps, type NodeTimerSub, type NodeWsDeps, type NodeWsHandlers, type NodeWsRegistry, type NodeWsSub, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };
+export { type FileLockBlock, FileLockTimeoutError, type FileStoreOptions, type NodeSignalDeps, type NodeSignalSub, type NodeSub, type NodeSubscribeBase, type NodeSubscribeCtx, type NodeSubscribeOpts, type NodeSubscribeWithWs, type NodeTimerDeps, type NodeTimerSub, type NodeWsDeps, type NodeWsHandlers, type NodeWsRegistry, type NodeWsSub, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };

package/dist/node/index.js

@@ -1,9 +1,10 @@
-import { dispatchIfPresent } from '../chunk-DVNXEB7V.js';
-import { StoreConflictError } from '../chunk-RKVUVALV.js';
-import { unlink, mkdir, writeFile, rename, open, readFile } from 'fs/promises';
+import { dispatchIfPresent } from '../chunk-BVFS3ICC.js';
+import { StoreConflictError } from '../chunk-A3QPMX5M.js';
+import { mkdir, writeFile, rename, readFile, unlink, open, stat } from 'fs/promises';
 import { createRequire } from 'module';
 import { dirname, join } from 'path';
 import { AsyncLocalStorage } from 'async_hooks';
+import { uptime, hostname } from 'os';
 
 var AsyncLock = class {
   tail = Promise.resolve();
@@ -60,6 +61,172 @@ function makeJournal(backend) {
     }
   };
 }
+var DEFAULT_LIMITS = { waitMs: 1e4, graceMs: 2e3 };
+var SPIN_MS = 10;
+var BOOT_TOLERANCE_MS = 6e4;
+var BLOCK_EXPLAINED = {
+  "another-host": "it was written on another host, which may still be writing, so it is not stolen. If that host is gone, delete the file and try again.",
+  "live-holder": "the process it names is alive. If that process is not a writer here, delete the file and try again.",
+  unwritten: "it is empty and too young to count as a crash.",
+  unreadable: "its contents are not a lock this version can read. If no writer holds it, delete the file and try again.",
+  contended: "other writers kept taking it."
+};
+var FileLockTimeoutError = class extends Error {
+  constructor(lockPath, waitedMs, blockedBy) {
+    super(
+      `@demlik/tea: gave up on lock "${lockPath}" after ${Math.round(waitedMs)} ms: ${BLOCK_EXPLAINED[blockedBy]}`
+    );
+    this.lockPath = lockPath;
+    this.waitedMs = waitedMs;
+    this.blockedBy = blockedBy;
+  }
+  lockPath;
+  waitedMs;
+  blockedBy;
+  name = "FileLockTimeoutError";
+  _tag = "file_lock_timeout";
+};
+function thisMachine() {
+  return {
+    host: hostname(),
+    bootedAtMs: Math.round(Date.now() - uptime() * 1e3)
+  };
+}
+function isValidPid(pid) {
+  return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0;
+}
+function parseStamp(body) {
+  let raw;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (typeof raw !== "object" || raw === null) return { kind: "unreadable" };
+  const { host, bootedAtMs, pid } = raw;
+  if (typeof host !== "string" || typeof bootedAtMs !== "number" || !Number.isFinite(bootedAtMs) || !isValidPid(pid)) {
+    return { kind: "unreadable" };
+  }
+  return { kind: "stamped", host, bootedAtMs, pid };
+}
+function parseHolder(text) {
+  const body = text.trim();
+  if (body === "") return { kind: "unwritten" };
+  if (/^\d+$/.test(body)) {
+    const pid = Number(body);
+    return isValidPid(pid) ? { kind: "pid-only", pid } : { kind: "unreadable" };
+  }
+  return parseStamp(body);
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function judgeHolder(holder, ageMs, here, graceMs) {
+  switch (holder.kind) {
+    case "unwritten":
+      return ageMs > graceMs ? "stale" : "unwritten";
+    case "unreadable":
+      return "unreadable";
+    case "pid-only":
+      return isProcessAlive(holder.pid) ? "live-holder" : "stale";
+    case "stamped":
+      if (holder.host !== here.host) return "another-host";
+      if (Math.abs(holder.bootedAtMs - here.bootedAtMs) > BOOT_TOLERANCE_MS) {
+        return "stale";
+      }
+      return isProcessAlive(holder.pid) ? "live-holder" : "stale";
+  }
+}
+async function ageOf(path) {
+  try {
+    return Date.now() - (await stat(path)).mtimeMs;
+  } catch (err) {
+    if (err.code === "ENOENT") return "vanished";
+    throw err;
+  }
+}
+async function inspectLock(lockPath, limits) {
+  let text;
+  try {
+    text = await readFile(lockPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return "vanished";
+    throw err;
+  }
+  const ageMs = await ageOf(lockPath);
+  if (ageMs === "vanished") return "vanished";
+  return judgeHolder(parseHolder(text), ageMs, thisMachine(), limits.graceMs);
+}
+async function createExclusive(path, body) {
+  try {
+    const handle = await open(path, "wx");
+    try {
+      if (body !== "") await handle.writeFile(body);
+    } finally {
+      await handle.close();
+    }
+    return true;
+  } catch (err) {
+    if (err.code === "EEXIST") return false;
+    throw err;
+  }
+}
+var removeIfPresent = (path) => unlink(path).catch((err) => {
+  if (err.code !== "ENOENT") throw err;
+});
+async function stealIfStillStale(lockPath, limits) {
+  const guardPath = `${lockPath}.steal`;
+  if (!await createExclusive(guardPath, "")) {
+    const age = await ageOf(guardPath);
+    if (age !== "vanished" && age > limits.graceMs) {
+      await removeIfPresent(guardPath);
+    }
+    return false;
+  }
+  try {
+    const verdict = await inspectLock(lockPath, limits);
+    if (verdict === "stale") await removeIfPresent(lockPath);
+    return verdict === "stale" || verdict === "vanished";
+  } finally {
+    await removeIfPresent(guardPath);
+  }
+}
+async function acquireFileLock(dir, lockPath, limits) {
+  await mkdir(dir, { recursive: true });
+  const startedAt = performance.now();
+  let blockedBy = "contended";
+  for (; ; ) {
+    const here = thisMachine();
+    const stamp = JSON.stringify({
+      host: here.host,
+      bootedAtMs: here.bootedAtMs,
+      pid: process.pid
+    });
+    if (await createExclusive(lockPath, stamp)) return;
+    const verdict = await inspectLock(lockPath, limits);
+    if (verdict !== "stale" && verdict !== "vanished") blockedBy = verdict;
+    const freed = verdict === "vanished" || verdict === "stale" && await stealIfStillStale(lockPath, limits);
+    const waitedMs = performance.now() - startedAt;
+    if (waitedMs >= limits.waitMs) {
+      throw new FileLockTimeoutError(lockPath, waitedMs, blockedBy);
+    }
+    if (!freed) await new Promise((resolve) => setTimeout(resolve, SPIN_MS));
+  }
+}
+async function withFileLock(dir, lockPath, fx, limits = DEFAULT_LIMITS) {
+  await acquireFileLock(dir, lockPath, limits);
+  try {
+    return await fx();
+  } finally {
+    await unlink(lockPath).catch(() => {
+    });
+  }
+}
 
 // src/node/index.ts
 function fileStore(path, parse, options = {}) {
@@ -123,9 +290,7 @@ function fenceFileStore(base, path) {
       return { raw: await base.load(), version };
     },
     async saveFenced(state, expectedVersion) {
-      await mkdir(dirname(path), { recursive: true });
-      await acquireFileLock(dirname(path), lockPath);
-      try {
+      return withFileLock(dirname(path), lockPath, async () => {
         const actual = await readVersion();
         if (actual !== expectedVersion) {
           throw new StoreConflictError(expectedVersion, actual);
@@ -136,23 +301,13 @@ function fenceFileStore(base, path) {
         await writeFile(tmp, String(next), "utf8");
         await rename(tmp, fencePath);
         return next;
-      } finally {
-        await unlink(lockPath).catch(() => {
-        });
-      }
+      });
     },
     async delete() {
-      await acquireFileLock(dirname(path), lockPath);
-      try {
-        await base.delete();
-      } finally {
-        await unlink(lockPath).catch(() => {
-        });
-      }
+      await withFileLock(dirname(path), lockPath, () => base.delete());
     }
   };
 }
-var LOCK_SPIN_MS = 10;
 function fileJournal(dir, parse) {
   const streamPath = (stream) => join(dir, `${encodeURIComponent(stream)}.jsonl`);
   const readEntries = async (stream) => {
@@ -188,58 +343,10 @@ function fileJournal(dir, parse) {
       return entry;
     },
     async lock(stream, fx) {
-      const lockPath = `${streamPath(stream)}.lock`;
-      await acquireFileLock(dir, lockPath);
-      try {
-        return await fx();
-      } finally {
-        await unlink(lockPath).catch(() => {
-        });
-      }
+      return withFileLock(dir, `${streamPath(stream)}.lock`, fx);
     }
   });
 }
-async function acquireFileLock(dir, lockPath) {
-  await mkdir(dir, { recursive: true });
-  for (; ; ) {
-    try {
-      const handle = await open(lockPath, "wx");
-      try {
-        await handle.writeFile(String(process.pid));
-      } finally {
-        await handle.close();
-      }
-      return;
-    } catch (err) {
-      if (err.code !== "EEXIST") throw err;
-      if (await stealIfStale(lockPath)) continue;
-      await new Promise((resolve) => setTimeout(resolve, LOCK_SPIN_MS));
-    }
-  }
-}
-async function stealIfStale(lockPath) {
-  let holder;
-  try {
-    holder = await readFile(lockPath, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return true;
-    throw err;
-  }
-  const pid = Number(holder.trim());
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  if (isProcessAlive(pid)) return false;
-  await unlink(lockPath).catch(() => {
-  });
-  return true;
-}
-function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === "EPERM";
-  }
-}
 var cachedWs;
 function loadWebSocket() {
   if (cachedWs) return cachedWs;
@@ -328,6 +435,6 @@ function nodeWsRunner(handlers) {
   };
 }
 
-export { fileJournal, fileStore, nodeSubscribe, sendToWebSocket };
+export { FileLockTimeoutError, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map