@demlik/tea 0.2.0 → 0.3.0

package/dist/do/index.d.ts

@@ -1,21 +1,21 @@
-import { Store, Runtime, BootingRuntime } from '../index.js';
-import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-9LxFpmh3.js';
-export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, d as PendingEffectsLedger, c as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-9LxFpmh3.js';
+import { S as Store, R as Runtime, B as BootingRuntime } from '../runtime-types-gsog27b6.js';
+import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-CFRngTNA.js';
+export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, d as PendingEffectsLedger, c as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-CFRngTNA.js';
 import { RetryPolicy, Rng } from '../retry-backoff/index.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-BmlJOvxM.js';
-import { AgentEvent, AgentTurn, AgentState, AgentMachineMsg, AgentStatus } from '../agent/index.js';
-import '../fan-out/index.js';
-import '../work-queue/index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-42kapW0n.js';
+import { y as AgentEvent, A as AgentTurn, N as AgentState, x as AgentMachineMsg, P as AgentStatus } from '../machine-B_BF4jij.js';
 import '../llm-call/index.js';
 import '../resilient-call/index.js';
 import '../cache/index.js';
-import '../types-BoUWgwSm.js';
+import '../types-KbL3W1mj.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';
 
 /**
  * @demlik/tea/do — `stepHost`, the HTTP-PULL control carrier (#92).
@@ -275,7 +275,7 @@ interface DeferResumeHook<R> {
      * Optional advisory re-poll delay (ms) surfaced on the {@link StepWorking} arm
      * so the hands can back off to the host's expected step latency.
      */
-    retryAfterMs?: number;
+    readonly retryAfterMs?: number;
 }
 /**
  * `StepHostConfig` with the defer-resume hook engaged — the presence of
@@ -774,6 +774,18 @@ interface ProjectionId {
 }
 /** Render a `ProjectionId` to its canonical `name-key` string. */
 declare function projectionIdString(id: ProjectionId): string;
+/** Context handed to a {@link ProjectionOnError} sink alongside the throw. */
+interface ProjectionErrorContext {
+    /** The id of the projection whose `apply`/`emit` threw. */
+    readonly id: ProjectionId;
+}
+/**
+ * Sink for a projection `apply`/`emit` throw the driver isolated. Injected into
+ * {@link projectionRegistry}; called with the original error and the id of the
+ * failing projection so a broken projection surfaces instead of being silently
+ * discarded (errors-are-data). Should be total.
+ */
+type ProjectionOnError = (error: unknown, context: ProjectionErrorContext) => void;
 /**
  * One unit the projection driver presents to a projection's `apply`. Mirrors
  * the `(msg, model)` pair `runtime.observe` fans out, plus the exclusive
@@ -862,9 +874,11 @@ interface ProjectionRunner<Model, Msg extends {
  * `startOffset` (the driver's offset guard enforces exclusivity even if an
  * already-applied update is re-presented).
  *
- * `emitOnStart`/`emitOnReset` default false: a fresh runner holds `initial` but
- * does not push it at the sink until the first real update lands (an SSE client
- * that just connected wants the next event, not a replay of the seed).
+ * The runner never emits the seed: a fresh runner holds `initial` but does not
+ * push it at the sink until the first real update lands (an SSE client that just
+ * connected wants the next event, not a replay of the seed), and `reset()`
+ * likewise re-seeds `view`/`offset` silently — `emit` fires only from `present`
+ * when a strictly-newer update is folded.
  */
 declare function runProjection<Model, Msg extends {
     type: string;
@@ -883,7 +897,8 @@ interface ProjectionRegistry<Model, Msg extends {
      * Present one update to EVERY registered runner. Each folds independently; an
      * `apply`/`emit` throw in one runner is caught so it cannot strand the others
      * (errors-are-data: a broken projection is dropped from THIS update, not
-     * allowed to corrupt siblings). Returns the offset assigned to this update.
+     * allowed to corrupt siblings) and routed to the registry's `onError` sink so
+     * it surfaces rather than vanishing. Returns the offset assigned to this update.
      */
     dispatch(msg: Msg | null, model: Model): number;
     /** The current monotonic offset (the last dispatched update's position). */
@@ -891,10 +906,15 @@ interface ProjectionRegistry<Model, Msg extends {
     /** The registered runners (introspection / tests). */
     runners(): readonly ProjectionRunner<Model, Msg, unknown>[];
 }
-/** Build an empty {@link ProjectionRegistry}. */
+/**
+ * Build an empty {@link ProjectionRegistry}. Pass an `onError` sink to receive
+ * any `apply`/`emit` throw the driver isolates — without it a broken projection
+ * is still isolated from its siblings, but its failure is not surfaced (the
+ * substrate's `run(machine, { onError })` is the natural source to forward).
+ */
 declare function projectionRegistry<Model, Msg extends {
     type: string;
-}>(): ProjectionRegistry<Model, Msg>;
+}>(onError?: ProjectionOnError): ProjectionRegistry<Model, Msg>;
 /**
  * Wire a {@link ProjectionRegistry} to a runtime's transition stream. The boot
  * update (the initial state, offset 0) is presented via `onBoot`; every applied
@@ -1149,6 +1169,11 @@ declare function acceptCommandSocket(clients: Set<WebSocket>, onFrame: (data: st
  * Broadcast a JSON frame to every connected command-runner socket. A dead
  * socket is skipped (dropped on its own `close` event). Lifts the consumer's
  * fan-out loop in `sendCommand`.
+ *
+ * Thin delegation to {@link broadcastFrame} — the general fan-out (serialize
+ * once, send to every OPEN socket, skip a closed/errored one). The
+ * {@link BroadcastReport} it returns is discarded here to keep the `void`
+ * command-socket signature.
  */
 declare function broadcast(clients: Set<WebSocket>, frame: unknown): void;
 /**
@@ -1180,6 +1205,11 @@ declare function acceptDurableCommandSocket(ctx: HibernatableCtx): Response;
  * set is read from `ctx.getWebSockets()` (the runtime repopulates it after a
  * wake), NOT a resident `Set<WebSocket>` — so it is correct immediately after an
  * eviction, before any other lifecycle method has run. A dead socket is skipped.
+ *
+ * Thin delegation to {@link broadcastFrame} over `ctx.getWebSockets()` — the
+ * general fan-out (serialize once, send to every OPEN socket, skip a
+ * closed/errored one). The {@link BroadcastReport} it returns is discarded here
+ * to keep the `void` command-socket signature.
  */
 declare function broadcastHibernatable(ctx: HibernatableCtx, frame: unknown): void;
 
@@ -1274,16 +1304,13 @@ declare function durableDeferredGateway<R>(inner: DeferredGateway<R>, recorder:
  * the consumer reads its persisted ledger events back and calls
  * `reissueSurvivingEffects` (see `./resume`) to re-fire the survivors.
  *
- * It extends `DurableDeferredGateway` (so it is a drop-in for the gateway the
+ * It IS a `DurableDeferredGateway` (so it is a drop-in for the gateway the
  * interpret cell already awaits) and exposes the underlying `recorder` for a
- * host that wants to read `surviving()` directly.
+ * host that wants to read `surviving()` directly. The #91 "command carrier"
+ * concept is exactly the durable gateway under a domain name — a type alias, not
+ * a second byte-identical interface that could drift.
  */
-interface DurableCommandCarrier<R> extends DeferredGateway<R> {
-    /** The ledger recorder backing this carrier (for `surviving()` introspection). */
-    readonly recorder: PendingEffectsRecorder<{
-        callId: string;
-    }>;
-}
+type DurableCommandCarrier<R> = DurableDeferredGateway<R>;
 /**
  * Build a durable command carrier over a (volatile) `DeferredGateway<R>` and a
  * `PendingEffectsRecorder`. Thin assembly over {@link durableDeferredGateway}:
@@ -1784,6 +1811,7 @@ declare function acceptPresenceSocket<A>(ctx: PresenceCtx, options?: RegisterOpt
 declare function presenceCount(ctx: PresenceCtx, tag?: string): number;
 
 /**
+ * @packageDocumentation
  * @demlik/tea/do — Durable Object adapter for `@demlik/tea`.
  *
  * The integration is built on ONE transport model and one durability primitive:
@@ -1879,4 +1907,4 @@ interface DoStoreOptions<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 ProjectionId, 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 };
+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,25 +1,27 @@
-import { status, agentBootMsg, agentEvents } from '../chunk-VFGKTGGC.js';
-export { applyEffectEvent, emptyLedger, foldLedger, isOwed, pendingEffectsLedger, survivingEffects } from '../chunk-3545BOYL.js';
-import '../chunk-ZDRN3YCE.js';
-import '../chunk-M6UZT7HS.js';
-import '../chunk-5KVHID6A.js';
-import '../chunk-6GIGQT6C.js';
+import { status, agentBootMsg, agentEvents } from '../chunk-WGGAMW7Y.js';
+export { applyEffectEvent, emptyLedger, foldLedger, isOwed, pendingEffectsLedger, survivingEffects } from '../chunk-25LBDCBC.js';
+import '../chunk-CAXMQJJ3.js';
+import '../chunk-VBUCHVCV.js';
+import '../chunk-MVY5DAMF.js';
+import '../chunk-IXBKFQH5.js';
 import '../chunk-JELSZN25.js';
-import '../chunk-UV6UWGEO.js';
-import { createIntake } from '../chunk-LEC4U6CX.js';
-import '../chunk-SKAMZKTE.js';
-import { defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-5VNWZADP.js';
-import '../chunk-2YOE5PIS.js';
+import '../chunk-D736QUGF.js';
+import { createIntake } from '../chunk-ZVJZ72HY.js';
+import '../chunk-RMX4EOQK.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-SC3FAFZN.js';
-import '../chunk-IN33Q4VJ.js';
-import '../chunk-HJO6VNQI.js';
-import '../chunk-TGG26XMK.js';
-import '../chunk-NSDFA6M6.js';
+import '../chunk-UF4MZSLT.js';
+import '../chunk-2KNLKQVN.js';
+import '../chunk-MU6MCIAC.js';
+import '../chunk-FV3Z5MBE.js';
+import '../chunk-LYLDCIPH.js';
 import '../chunk-2YFLOCWX.js';
-import { run, replay } from '../chunk-6VDCTR7N.js';
-import '../chunk-DYRKDCJI.js';
+import '../chunk-ZJ5AOYBH.js';
+import '../chunk-G5E74IJB.js';
+import { replay, run } from '../chunk-BP2R7TPP.js';
+import '../chunk-PBDYW2TU.js';
 
 // src/do/durable-timer.ts
 function durableTimer(config) {
@@ -69,6 +71,10 @@ function doEventSourcedStore(storage, machine, ctx, opts = {}) {
     const meta = JSON.parse(raw);
     return typeof meta.lastSeq === "number" ? meta.lastSeq : 0;
   }
+  async function ensureLastSeq() {
+    if (lastSeq === null) lastSeq = await readMeta();
+    return lastSeq;
+  }
   async function readSnapshot() {
     const raw = await storage.get(snapshotKey);
     if (raw === void 0 || raw === null) return { state: null, seq: 0 };
@@ -126,8 +132,7 @@ function doEventSourcedStore(storage, machine, ctx, opts = {}) {
     snapshotSeq = seq;
   }
   async function append(msg) {
-    if (lastSeq === null) lastSeq = await readMeta();
-    const seq = lastSeq + 1;
+    const seq = await ensureLastSeq() + 1;
     lastSeq = seq;
     await storage.put(eventKey(eventPrefix, seq), JSON.stringify(msg));
     await storage.put(
@@ -139,9 +144,9 @@ function doEventSourcedStore(storage, machine, ctx, opts = {}) {
     }
   }
   async function snapshotNow() {
-    if (lastSeq === null) lastSeq = await readMeta();
-    if (latestState === null || lastSeq <= snapshotSeq) return false;
-    await writeSnapshot(lastSeq, latestState);
+    const seq = await ensureLastSeq();
+    if (latestState === null || seq <= snapshotSeq) return false;
+    await writeSnapshot(seq, latestState);
     return true;
   }
   return { store, append, snapshotNow, readEvents };
@@ -252,8 +257,7 @@ function createAgentHost(config) {
   const now = config.now ?? Date.now;
   const isTerminal = config.terminal ?? ((s) => s.run.phase === "done" || s.run.phase === "failed");
   let cached = null;
-  async function runtime() {
-    if (cached !== null) return cached;
+  async function build() {
     const booting = run(config.buildMachine(), {
       ctx: config.ctx,
       store: config.store,
@@ -262,7 +266,15 @@ function createAgentHost(config) {
     });
     sseFromAgentEvents(booting, sse, config.toSseFrame);
     await autoBoot(booting, now);
-    cached = await booting.ready;
+    return booting.ready;
+  }
+  function runtime() {
+    if (cached !== null) return cached;
+    const building = build();
+    cached = building;
+    building.catch(() => {
+      if (cached === building) cached = null;
+    });
     return cached;
   }
   return {
@@ -276,12 +288,62 @@ function createAgentHost(config) {
     sse,
     async reset() {
       if (cached === null) return;
-      await cached.stop();
+      const built = await cached.catch(() => null);
       cached = null;
+      await built?.stop();
     }
   };
 }
 
+// src/do/presence.ts
+var WS_READY_STATE_OPEN = 1;
+function broadcastFrame(sockets, frame, options) {
+  const serialize = options?.serialize ?? JSON.stringify;
+  const except = options?.except;
+  const json = serialize(frame);
+  let sent = 0;
+  let skipped = 0;
+  for (const ws of sockets) {
+    if (except !== void 0 && ws === except) {
+      skipped++;
+      continue;
+    }
+    if (ws.readyState !== void 0 && ws.readyState !== WS_READY_STATE_OPEN) {
+      skipped++;
+      continue;
+    }
+    try {
+      ws.send(json);
+      sent++;
+    } catch {
+      skipped++;
+    }
+  }
+  return { sent, skipped };
+}
+function registerHibernatableSocket(ctx, server, options) {
+  ctx.acceptWebSocket(
+    server,
+    options?.tags === void 0 ? void 0 : [...options.tags]
+  );
+  if (options?.attachment !== void 0) {
+    server.serializeAttachment(options.attachment);
+  }
+}
+function acceptPresenceSocket(ctx, options) {
+  const pair = new WebSocketPair();
+  const client = pair[0];
+  const server = pair[1];
+  registerHibernatableSocket(ctx, server, options);
+  return {
+    server,
+    response: new Response(null, { status: 101, webSocket: client })
+  };
+}
+function presenceCount(ctx, tag) {
+  return ctx.getWebSockets(tag).length;
+}
+
 // src/do/command-socket.ts
 function acceptCommandSocket(clients, onFrame) {
   const pair = new WebSocketPair();
@@ -295,13 +357,7 @@ function acceptCommandSocket(clients, onFrame) {
   return new Response(null, { status: 101, webSocket: client });
 }
 function broadcast(clients, frame) {
-  const json = JSON.stringify(frame);
-  for (const ws of clients) {
-    try {
-      ws.send(json);
-    } catch {
-    }
-  }
+  broadcastFrame(clients, frame);
 }
 function acceptDurableCommandSocket(ctx) {
   const pair = new WebSocketPair();
@@ -310,13 +366,7 @@ function acceptDurableCommandSocket(ctx) {
   return new Response(null, { status: 101, webSocket: client });
 }
 function broadcastHibernatable(ctx, frame) {
-  const json = JSON.stringify(frame);
-  for (const ws of ctx.getWebSockets()) {
-    try {
-      ws.send(json);
-    } catch {
-    }
-  }
+  broadcastFrame(ctx.getWebSockets(), frame);
 }
 
 // src/do/deferred-gateway.ts
@@ -461,55 +511,6 @@ function appliedEffects(restore) {
   };
 }
 
-// src/do/presence.ts
-var WS_READY_STATE_OPEN = 1;
-function broadcastFrame(sockets, frame, options) {
-  const serialize = options?.serialize ?? JSON.stringify;
-  const except = options?.except;
-  const json = serialize(frame);
-  let sent = 0;
-  let skipped = 0;
-  for (const ws of sockets) {
-    if (except !== void 0 && ws === except) {
-      skipped++;
-      continue;
-    }
-    if (ws.readyState !== void 0 && ws.readyState !== WS_READY_STATE_OPEN) {
-      skipped++;
-      continue;
-    }
-    try {
-      ws.send(json);
-      sent++;
-    } catch {
-      skipped++;
-    }
-  }
-  return { sent, skipped };
-}
-function registerHibernatableSocket(ctx, server, options) {
-  ctx.acceptWebSocket(
-    server,
-    options?.tags === void 0 ? void 0 : [...options.tags]
-  );
-  if (options?.attachment !== void 0) {
-    server.serializeAttachment(options.attachment);
-  }
-}
-function acceptPresenceSocket(ctx, options) {
-  const pair = new WebSocketPair();
-  const client = pair[0];
-  const server = pair[1];
-  registerHibernatableSocket(ctx, server, options);
-  return {
-    server,
-    response: new Response(null, { status: 101, webSocket: client })
-  };
-}
-function presenceCount(ctx, tag) {
-  return ctx.getWebSockets(tag).length;
-}
-
 // src/do/projection.ts
 function projectionIdString(id) {
   return `${id.name}-${id.key}`;
@@ -535,7 +536,7 @@ function runProjection(projection, startOffset = 0) {
     }
   };
 }
-function projectionRegistry() {
+function projectionRegistry(onError) {
   const runners = /* @__PURE__ */ new Set();
   let counter = -1;
   return {
@@ -550,7 +551,8 @@ function projectionRegistry() {
       for (const runner of runners) {
         try {
           runner.present(update);
-        } catch {
+        } catch (err) {
+          onError?.(err, { id: runner.id });
         }
       }
       return offset;