@demlik/tea 0.13.0 → 0.15.0

package/dist/do/index.d.ts

@@ -1,23 +1,19 @@
-import { S as Store, R as Runtime, B as BootingRuntime } from '../runtime-types-CNLmhWif.js';
-import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-C6uwzjb5.js';
-export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, c as PendingEffectsLedger, d as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-C6uwzjb5.js';
+import { S as Store, R as Runtime, B as BootingRuntime, F as FencedStore } from '../runtime-types-CMF13BBh.js';
+import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-CWzA-o2B.js';
+export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, c as PendingEffectsLedger, d as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-CWzA-o2B.js';
 import { RetryPolicy, Rng } from '../retry-backoff/index.js';
-import { C as Cmd, S as Sub, M as Machine, R as RequiredCtx } from '../core-Co0LWkIA.js';
-import { k as AgentEvent, A as AgentTurn, s as AgentState, p as AgentMachineMsg, t as AgentStatus } from '../machine-BtFWQmmq.js';
+import { C as Cmd, S as Sub, M as Machine, R as RequiredCtx } from '../core-DnzqWy6u.js';
+import { g as AgentEvent, b as AgentTurn, c as AgentState, i as AgentMachineMsg, D as AgentStatus } from '../machine-DGlPWCWI.js';
 import 'better-result';
 import 'zod';
-import '../llm-call/index.js';
-import '../resilient-call/index.js';
-import '../cache/index.js';
-import '../types-XS_miRnB.js';
-import '../circuit-breaker/index.js';
-import '../deadline/index.js';
-import '../protocol-B5YmJr0d.js';
-import '../rate-limit/index.js';
-import '../monitored-run/index.js';
-import '../snapshot/index.js';
-import '../work-queue/index.js';
-import '../fan-out/index.js';
+import '../index-KXqTRJyb.js';
+import '../index-ZCMhnVKN.js';
+import '../index-HSYgG2Yt.js';
+import '../types-BseNPIhr.js';
+import '../index-CSyMYDAB.js';
+import '../index-CA_7I5g9.js';
+import '../protocol-D8VbH-VH.js';
+import '../index-CuNO9m8i.js';
 
 /**
  * @demlik/tea/do — `stepHost`, the HTTP-PULL control carrier (#92).
@@ -1016,7 +1012,7 @@ declare function sseProjection<Model, Msg extends {
     key?: string;
 }): Projection<Model, Msg, E | null>;
 /**
- * Wire an {@link SseHub} to a runtime's semantic {@link AgentEvent} stream (#47).
+ * Wire an {@link SseHub} to a runtime's semantic {@link AgentEvent} stream.
  * For each event `type` the runtime can emit, subscribes via `runtime.on` and
  * pushes `toFrame(event)` at the hub (returning `null` skips that event). The
  * runtime MUST have been built with `run(machine, { events: agentEvents() })`,
@@ -1088,7 +1084,7 @@ interface AgentHostConfig<Stage, P extends string, O extends Record<P, AgentTurn
     readonly now?: () => number;
 }
 /**
- * The assembled host: the runtime cell + the SSE hub + the framework test seam,
+ * The assembled host: the runtime handle + the SSE hub + the framework test seam,
  * owned ONCE. A DO holds one `AgentHost` and delegates to it; its own surface
  * shrinks to the domain (the gateway, the WS bridge, the command-send mapping).
  *
@@ -1111,7 +1107,9 @@ interface AgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R,
      * The agent's lifecycle status (#49) — the ONE typed channel a consumer reads
      * instead of re-deriving `run.phase` / `awaiting` by hand. Ensures the runtime
      * is built + boot-reconciled first. Replaces the per-consumer `isSuspended` /
-     * `runPhase` test methods (read `status().kind`).
+     * `runPhase` test methods (read `status().kind`: `idle` / `running` /
+     * `suspended` / `done` / `failed`). A hydrated DO that has not yet seen
+     * `agent_start` reads `idle`, not `running` (#92).
      */
     status(): Promise<AgentStatus<Stage>>;
     /**
@@ -1352,7 +1350,7 @@ declare function durableCommandCarrier<R>(inner: DeferredGateway<R>, recorder: P
 
 /**
  * The typed cold-wake resume port `bootResume` fires through — the agent's
- * `AgentBootPort` (issue #60) generalized to any DO-hosted machine (issue #231).
+ * `AgentBootPort`, generalized to any DO-hosted machine.
  *
  * - `isResumable(state)` — true iff the rehydrated State is mid-loop and needs a
  *   resume dispatch. False on a fresh boot, which makes `bootResume` a no-op.
@@ -1395,10 +1393,10 @@ declare function bootResume<S, M extends {
  */
 declare function agentIsResumable<Stage, P extends string, O extends Record<P, unknown>, R>(state: AgentState<Stage, P, O, R>): boolean;
 /**
- * The AGENT specialization of {@link bootResume} (issue #231): after
+ * The AGENT specialization of {@link bootResume}: after
  * `runtime.ready`, self-dispatch `agent_boot` iff the rehydrated slice is
  * resumable, a no-op on a fresh DO. Wires the agent slice's `agentIsResumable`
- * predicate + the agent-owned `agentBootMsg` typed port (issue #60) into the
+ * predicate + the agent-owned `agentBootMsg` typed port into the
  * generalized helper, so the resume dispatch lives in ONE place — see
  * `bootResume`'s docblock for the boot-gate / init-purity rationale.
  *
@@ -1408,8 +1406,9 @@ declare function autoBoot<Stage, P extends string, O extends Record<P, unknown>,
     type: string;
 } = never>(booting: BootingRuntime<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, E>, now?: () => number): Promise<void>;
 /**
- * RE-EMIT ON ACTIVATION (the #91 wake path). Given a durable carrier whose
- * recorder was rehydrated from the persisted ledger events (e.g.
+ * Re-fire every round-trip a rehydrated actor still owes, on wake. Given a
+ * durable carrier whose recorder was rehydrated from the persisted ledger
+ * events (e.g.
  * `durableCommandCarrier(deferredGateway(), pendingEffectsLedger({ events }),
  * …)` on a wake), re-fire every owed-but-unconfirmed round-trip via
  * `reissue(callId)` — the consumer's "re-send the command frame for this
@@ -1531,7 +1530,8 @@ interface EffectForgotten extends Cmd<"effect_forgotten"> {
 type AppliedEffectsEvent = EffectApplied | EffectForgotten;
 /** The set of keys whose effect has been applied. A pure fold result. */
 type AppliedEffects = ReadonlySet<EffectKey>;
-/** The empty applied set — the fold's seed (a fresh actor has applied nothing). */
+/** The empty applied set — the fold's starting value (a fresh actor has
+ * applied nothing). */
 declare function emptyApplied(): AppliedEffects;
 /**
  * Apply ONE event — the reducer at the heart of the fold.
@@ -1563,7 +1563,7 @@ interface IdempotentEffect<A> {
     readonly fn: () => Promise<A> | A;
 }
 /**
- * Pair a durable `key` with an external effect `fn` — the brick's primary
+ * Pair a durable `key` with an external effect `fn` — this module's primary
  * surface. Run it through {@link appliedEffects}'s guard; a re-fire whose key is
  * already applied is a proven no-op (`fn` is not invoked a second time).
  */
@@ -1703,7 +1703,7 @@ interface BroadcastReport {
     readonly sent: number;
     readonly skipped: number;
 }
-/** Optional knobs for {@link broadcastFrame}. */
+/** Optional settings for {@link broadcastFrame}. */
 interface BroadcastOptions<S extends PresenceSocket> {
     /**
      * A socket to exclude from the fan-out — typically the sender, so a collab /
@@ -1734,7 +1734,8 @@ interface BroadcastOptions<S extends PresenceSocket> {
  * not silence.
  */
 declare function broadcastFrame<S extends PresenceSocket>(sockets: Iterable<S>, frame: unknown, options?: BroadcastOptions<S>): BroadcastReport;
-/** Optional knobs for {@link registerHibernatableSocket} / {@link acceptPresenceSocket}. */
+/** Optional settings for {@link registerHibernatableSocket} /
+ * {@link acceptPresenceSocket}. */
 interface RegisterOptions<A> {
     /**
      * Hibernation tags for the socket — the same strings `ctx.getWebSockets(tag)`
@@ -1870,6 +1871,16 @@ interface DoStoreOptions<S> {
      * accept whatever `serialize` produces.
      */
     readonly serialize?: (state: S) => unknown;
+    /**
+     * Refuse a second live writer (#143). With `{ fenced: true }` the returned
+     * store is a `FencedStore<S>`: the version lives in its own storage cell
+     * (`<key>@@version`) and the compare-and-swap runs inside
+     * `storage.transaction`, so the read, the compare and the two writes are one
+     * atomic unit. Inside a single DO the platform already guarantees one writer;
+     * fencing is what refuses a SECOND grain — a stale zombie isolate mid-migration,
+     * or a second DO id pointed at the same state by a routing bug.
+     */
+    readonly fenced?: true;
 }
 /**
  * `Store<S>` over `DurableObjectStorage`.
@@ -1910,6 +1921,9 @@ interface DoStoreOptions<S> {
  *   defaults to `@@state`) or a {@link DoStoreOptions} bag carrying `key`
  *   and/or the `serialize` hook. A bare string is treated as `{ key }`.
  */
+declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => S | null, keyOrOptions: DoStoreOptions<S> & {
+    readonly fenced: true;
+}): FencedStore<S>;
 declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => S | null, keyOrOptions?: string | DoStoreOptions<S>): Store<S>;
 
 export { type AgentHost, type AgentHostConfig, type AlarmStorage, type AppliedEffects, type AppliedEffectsEvent, type AppliedEffectsGuard, type AttachableSocket, type BroadcastOptions, type BroadcastReport, type DeferResumeHook, type DeferStepHostConfig, type DeferredGateway, type DeferredStepOutcome, type DeferredStepResponse, type DoStoreOptions, type DurableCommandCarrier, type DurableTimer, type DurableTimerConfig, type EffectApplied, EffectConfirmed, type EffectForgotten, type EffectKey, EffectOwed, type EventLogRange, type EventSourcedOptions, type EventSourcedStore, type ExecuteStep, type HibernatableCtx, type IdempotentEffect, type IdempotentOutcome, type NextStep, PendingEffectsRecorder, type PersistedEvent, type PresenceCtx, type PresenceSocket, type PresenceUpgrade, type Projection, type ProjectionErrorContext, type ProjectionId, type ProjectionOnError, type ProjectionRegistry, type ProjectionRunner, type ProjectionUpdate, type RegisterOptions, type ResumePort, type RunStepLoopConfig, type SseHub, type StepCtx, type StepEngine, type StepHostConfig, type StepLoopOutcome, type StepOutcome, type StepRequest, type StepResponse, type StepResult, type StepTransport, type StepWorking, WS_READY_STATE_OPEN, acceptCommandSocket, acceptDurableCommandSocket, acceptPresenceSocket, agentIsResumable, appliedEffects, applyAppliedEvent, autoBoot, bootResume, broadcast, broadcastFrame, broadcastHibernatable, constantTimeEqual, createAgentHost, deferredGateway, doEventSourcedStore, doStore, driveProjections, durableCommandCarrier, durableDeferredGateway, durableTimer, emptyApplied, foldApplied, idempotentEffect, isApplied, mintRunToken, presenceCount, projectionIdString, projectionRegistry, rebuildProjection, registerHibernatableSocket, reissueSurvivingEffects, runProjection, runStepLoop, sseFromAgentEvents, sseHub, sseProjection, stepHost };

package/dist/do/index.js

@@ -1,27 +1,16 @@
-import { status, agentBootMsg, agentEvents } from '../chunk-3I52QZZ5.js';
-export { applyEffectEvent, emptyLedger, foldLedger, isOwed, pendingEffectsLedger, survivingEffects } from '../chunk-25LBDCBC.js';
-import '../chunk-DMYGQB4O.js';
-import '../chunk-COS5MSTO.js';
-import '../chunk-O4MVQTEJ.js';
-import '../chunk-4KLG43GY.js';
-import '../chunk-JELSZN25.js';
-import '../chunk-D736QUGF.js';
-import { createIntake } from '../chunk-ZVJZ72HY.js';
-import '../chunk-RH5EFRVJ.js';
-import '../chunk-DGE4PV4A.js';
-import { defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-Q2UM7BXU.js';
-import '../chunk-S2EGRPCM.js';
-import '../chunk-BYQUGDD3.js';
-import '../chunk-K575PT4S.js';
-import '../chunk-UF4MZSLT.js';
+import { status, agentBootMsg, agentEvents } from '../chunk-TCLBCERH.js';
+import { createIntake } from '../chunk-VTQI2NHP.js';
+export { applyEffectEvent, emptyLedger, foldLedger, isOwed, pendingEffectsLedger, survivingEffects } from '../chunk-6IQPODUF.js';
+import '../chunk-3B5X7SBB.js';
+import '../chunk-MYXFNWAJ.js';
+import '../chunk-PR6TB3BL.js';
+import '../chunk-TXN2KFHF.js';
+import '../chunk-L3TND7LA.js';
+import '../chunk-AYS5N6WY.js';
+import { defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-VBDU4JL6.js';
+import '../chunk-22POWGFA.js';
 import '../chunk-G5E74IJB.js';
-import '../chunk-MU6MCIAC.js';
-import '../chunk-FV3Z5MBE.js';
-import '../chunk-VYFAZN3F.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-ZJ5AOYBH.js';
-import { replay, run } from '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
+import { StoreConflictError, replay, run } from '../chunk-66PY5WYF.js';
 
 // src/do/durable-timer.ts
 function durableTimer(config) {
@@ -255,7 +244,7 @@ function sseFromAgentEvents(runtime, hub, toFrame) {
 function createAgentHost(config) {
   const sse = sseHub();
   const now = config.now ?? Date.now;
-  const isTerminal = config.terminal ?? ((s) => s.run.phase === "done" || s.run.phase === "failed");
+  const isTerminal = config.terminal ?? ((s) => s.run.phase === "done" || s.run.phase === "failed" || s.run.phase === "cancelled");
   let cached = null;
   async function build() {
     const booting = run(config.buildMachine(), {
@@ -706,7 +695,8 @@ function doStore(storage, parse, keyOrOptions = DEFAULT_STATE_KEY) {
   const options = typeof keyOrOptions === "string" ? { key: keyOrOptions } : keyOrOptions;
   const key = options.key ?? DEFAULT_STATE_KEY;
   const serialize = options.serialize ?? ((state) => state);
-  return {
+  const versionKey = `${key}@@version`;
+  const base = {
     async load() {
       const raw = await storage.get(key);
       if (raw === void 0 || raw === null) return null;
@@ -719,6 +709,27 @@ function doStore(storage, parse, keyOrOptions = DEFAULT_STATE_KEY) {
       return parse(raw);
     }
   };
+  if (options.fenced !== true) return base;
+  return {
+    ...base,
+    fenced: true,
+    async loadFenced() {
+      const stored = await storage.get(versionKey);
+      return { raw: await base.load(), version: stored ?? 0 };
+    },
+    async saveFenced(state, expectedVersion) {
+      return await storage.transaction(async (txn) => {
+        const actual = await txn.get(versionKey) ?? 0;
+        if (actual !== expectedVersion) {
+          throw new StoreConflictError(expectedVersion, actual);
+        }
+        const next = expectedVersion + 1;
+        await txn.put(key, JSON.stringify(serialize(state)));
+        await txn.put(versionKey, next);
+        return next;
+      });
+    }
+  };
 }
 
 export { WS_READY_STATE_OPEN, acceptCommandSocket, acceptDurableCommandSocket, acceptPresenceSocket, agentIsResumable, appliedEffects, applyAppliedEvent, autoBoot, bootResume, broadcast, broadcastFrame, broadcastHibernatable, constantTimeEqual, createAgentHost, deferredGateway, doEventSourcedStore, doStore, driveProjections, durableCommandCarrier, durableDeferredGateway, durableTimer, emptyApplied, foldApplied, idempotentEffect, isApplied, mintRunToken, presenceCount, projectionIdString, projectionRegistry, rebuildProjection, registerHibernatableSocket, reissueSurvivingEffects, runProjection, runStepLoop, sseFromAgentEvents, sseHub, sseProjection, stepHost };