@demlik/tea 0.17.0 → 0.18.0

package/dist/do/index.d.ts

@@ -1,18 +1,18 @@
-import { S as Store, b as BootedRunHandle, E as EngineRun, c as RunHandle, F as FencedStore } from '../runtime-types-B62Ucnxr.js';
-import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-CNaw97Be.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-CNaw97Be.js';
+import { S as Store, b as BootedRunHandle, E as EngineRun, c as RunHandle, M as Migrated, F as FencedStore, D as DeletableStore } from '../runtime-types-BKg2CGMx.js';
+import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-BmUrRA-h.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-BmUrRA-h.js';
 import { RetryPolicy, Rng } from '../retry-backoff/index.js';
-import { C as Cmd, S as Sub, M as Machine, W as Wired } from '../core-rDbOaJTN.js';
-import { g as AgentEvent, b as AgentTurn, c as AgentState, i as AgentMachineMsg, B as AgentStatus } from '../machine-BcfCFMYF.js';
+import { C as Cmd, c as Sub, M as Machine, W as Wired } from '../core-Ce9ncpuv.js';
+import { A as AgentEvent, f as AgentTurn, e as AgentState, i as AgentMachineMsg, K as AgentStatus } from '../machine-CuojfZup.js';
 import '@standard-schema/spec';
-import '../index-BOrsbdAf.js';
-import '../index-CWmsXNdX.js';
-import '../index-DaX_P35Q.js';
-import '../types-DPm5YCDQ.js';
-import '../index-CcrKLtse.js';
-import '../index-q1PoukOZ.js';
+import '../index-Dy3379ve.js';
+import '../index-D8sYVzCI.js';
+import '../index-e36uEyl4.js';
+import '../types-SzNSHKlV.js';
+import '../index-DWdg7R1l.js';
+import '../index-2kNxy6az.js';
 import '../protocol-ClRZBhHQ.js';
-import '../index-Cx0F2M34.js';
+import '../index-Ce5GYAuI.js';
 
 /**
  * @demlik/tea/do — `stepHost`, the HTTP-PULL control carrier (#92).
@@ -580,10 +580,11 @@ interface EventSourcedOptions<S, M> {
      */
     readonly snapshotEvery?: number;
     /**
-     * Boundary parse for the persisted SNAPSHOT cell (the `S` blob). Same
-     * contract as `doStore`'s `parse`: returns `S` on a recognized shape, `null`
-     * on an unrecognized one (boot fresh), and must NOT throw. Default accepts
-     * any non-null, non-array object as `S`.
+     * Boundary parse for the persisted SNAPSHOT cell (the `S` blob). Returns `S`
+     * on a recognized shape, `null` on an unrecognized one, and must NOT throw.
+     * Unlike `doStore`'s `parse`, `null` loses nothing: the snapshot is only a
+     * shortcut, so a `null` discards it and replays the whole event log from
+     * seq 0. Default accepts any non-null, non-array object as `S`.
      */
     readonly parse?: (raw: unknown) => S | null;
     /**
@@ -995,14 +996,29 @@ declare function sseHub<E>(): SseHub<E>;
  *   - `name`/`key` default to `"sse"`/`"main"`; override for a second SSE view.
  *
  * @example
- *   const hub = sseHub<MyEvent>();
- *   const registry = projectionRegistry<MyState, MyMsg>();
- *   registry.register(sseProjection(hub, (msg) =>
- *     msg?.type === "turn_done" ? { kind: "turn", ... } : null,
- *   ));
- *   driveProjections(registry, runtime); // SSE is now one projection
- *   // /sse route unchanged:
- *   return hub.open();
+ * ```ts
+ * import type { Runtime } from "@demlik/tea";
+ * import {
+ *   driveProjections,
+ *   projectionRegistry,
+ *   sseHub,
+ *   sseProjection,
+ * } from "@demlik/tea/do";
+ *
+ * type MyState = { readonly turns: number };
+ * type MyMsg = { type: "turn_done"; turn: number } | { type: "tick" };
+ * type MyEvent = { kind: "turn"; turn: number };
+ * declare const runtime: Runtime<MyState, MyMsg>;
+ *
+ * const hub = sseHub<MyEvent>();
+ * const registry = projectionRegistry<MyState, MyMsg>();
+ * registry.register(sseProjection(hub, (msg: MyMsg | null) =>
+ *   msg?.type === "turn_done" ? { kind: "turn", turn: msg.turn } : null,
+ * ));
+ * driveProjections(registry, runtime); // SSE is now one projection
+ * // /sse route unchanged:
+ * const sseRoute = (): Response => hub.open();
+ * ```
  */
 declare function sseProjection<Model, Msg extends {
     type: string;
@@ -1024,13 +1040,22 @@ declare function sseProjection<Model, Msg extends {
  * hand-rolled Msg switch to `on`.
  *
  * @example
- *   const hub = sseHub<MyFrame>();
- *   const runtime = await run(machine, { ctx, events: agentEvents() }).ready;
- *   const off = sseFromAgentEvents(runtime, hub, (e) =>
- *     e.type === "RunDone" ? { kind: "done", output: e.output } : null,
- *   );
- *   // /sse route unchanged:
- *   return hub.open();
+ * ```ts
+ * import type { Runtime } from "@demlik/tea";
+ * import type { AgentEndedStatus, AgentEvent } from "@demlik/tea/agent";
+ * import { sseFromAgentEvents, sseHub } from "@demlik/tea/do";
+ *
+ * type MyFrame = { kind: "ended"; status: AgentEndedStatus };
+ * // Built with `run(machine, { ctx, events: agentEvents() }).ready`.
+ * declare const runtime: Runtime<unknown, { type: string }, AgentEvent<string>>;
+ *
+ * const hub = sseHub<MyFrame>();
+ * const off = sseFromAgentEvents(runtime, hub, (e) =>
+ *   e.type === "RunDone" ? { kind: "ended", status: e.status } : null,
+ * );
+ * // /sse route unchanged:
+ * const sseRoute = (): Response => hub.open();
+ * ```
  */
 declare function sseFromAgentEvents<R, Frame>(runtime: {
     on<K extends AgentEvent<R>["type"]>(type: K, handler: (event: Extract<AgentEvent<R>, {
@@ -1140,20 +1165,55 @@ interface AgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R,
  * issue #53 had every consumer re-write.
  *
  * @example
- *   const host = createAgentHost<Stage, Purpose, Outputs, ClientResult, SseEvent>({
- *     run, // from `@demlik/tea/promise`
- *     buildMachine: () => agent.toMachine<Ctx>({ toolInterpret }),
- *     store: doStore(storage, parse),
- *     ctx,
- *     toSseFrame: (e) =>
- *       e.type === "ToolSettled" ? { kind: "result", ...} :
- *       e.type === "TurnSettled" && e.turn.toolCalls.length === 0
- *         ? { kind: "verdict", verdict: e.turn.content } :
- *       e.type === "RunDone" ? { kind: "phase", phase: "done" } : null,
- *   });
- *   // route:   return host.sse.open();
- *   // start:   await (await host.runtime()).dispatch({ type: "agent_start", ... });
- *   // test:    (await host.status()).kind === "suspended"
+ * ```ts
+ * import type { Interpret, Migrated } from "@demlik/tea";
+ * import type {
+ *   AgentKnob,
+ *   AgentMachineMsg,
+ *   AgentState,
+ *   AgentTurn,
+ *   ToolCall,
+ * } from "@demlik/tea/agent";
+ * import { createAgentHost, doStore } from "@demlik/tea/do";
+ * import { run } from "@demlik/tea/promise";
+ *
+ * type Stage = "plan" | "act";
+ * type Purpose = "plan_turn" | "act_turn";
+ * type Outputs = Record<Purpose, AgentTurn>;
+ * type ClientResult = string;
+ * type ToolCmd = { readonly type: "run_tool" } & ToolCall;
+ * type SseEvent =
+ *   | { kind: "result"; callId: string; result: ClientResult }
+ *   | { kind: "verdict"; verdict: string }
+ *   | { kind: "phase"; phase: string };
+ * interface Ctx { readonly apiKey: string }
+ * type S = AgentState<Stage, Purpose, Outputs, ClientResult>;
+ *
+ * // From `createAgent(...)`, and the interpret for its tool Cmd.
+ * declare const agent: AgentKnob<Stage, Purpose, Outputs, ClientResult, ToolCmd, false, false>;
+ * declare const toolInterpret: Interpret<AgentMachineMsg<Purpose, Outputs, ClientResult>, ToolCmd, Ctx>;
+ * declare const storage: DurableObjectStorage;
+ * declare const parse: (raw: unknown) => Migrated<S>;
+ * declare const ctx: Ctx;
+ *
+ * const host = createAgentHost({
+ *   run,
+ *   buildMachine: () => agent.toMachine<Ctx>({ toolInterpret }),
+ *   store: doStore(storage, parse),
+ *   ctx,
+ *   toSseFrame: (e): SseEvent | null =>
+ *     e.type === "ToolSettled" ? { kind: "result", callId: e.callId, result: e.result } :
+ *     e.type === "TurnSettled" && e.turn.toolCalls.length === 0
+ *       ? { kind: "verdict", verdict: e.turn.content } :
+ *     e.type === "RunDone" ? { kind: "phase", phase: e.status.kind } : null,
+ * });
+ * // route:
+ * const sseRoute = (): Response => host.sse.open();
+ * // start:
+ * await (await host.runtime()).dispatch({ type: "agent_start", runId: "run-1", at: Date.now() });
+ * // test:
+ * const suspended = (await host.status()).kind === "suspended";
+ * ```
  */
 declare function createAgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame, C extends Cmd = Cmd, U extends Sub = Sub, Ctx = unknown>(config: AgentHostConfig<Stage, P, O, R, Frame, C, U, Ctx>): AgentHost<Stage, P, O, R, Frame>;
 
@@ -1799,10 +1859,20 @@ interface PresenceUpgrade {
  * via {@link registerHibernatableSocket}.
  *
  * @example
+ * ```ts
+ * import { acceptPresenceSocket, type PresenceCtx } from "@demlik/tea/do";
+ *
+ * declare const room: { snapshot(): unknown };
+ *
+ * class Lobby {
+ *   constructor(readonly ctx: PresenceCtx) {}
+ *
  *   async fetch(request: Request): Promise<Response> {
  *     if (request.headers.get("Upgrade") !== "websocket") {
  *       return new Response("expected a websocket upgrade", { status: 426 });
  *     }
+ *     const playerId = new URL(request.url).searchParams.get("player");
+ *     const welcome = { type: "welcome", playerId };
  *     const { server, response } = acceptPresenceSocket(this.ctx, {
  *       attachment: { playerId },
  *     });
@@ -1810,6 +1880,8 @@ interface PresenceUpgrade {
  *     server.send(JSON.stringify(room.snapshot()));
  *     return response;
  *   }
+ * }
+ * ```
  */
 declare function acceptPresenceSocket<A>(ctx: PresenceCtx, options?: RegisterOptions<A>): PresenceUpgrade;
 /**
@@ -1829,12 +1901,11 @@ declare function presenceCount(ctx: PresenceCtx, tag?: string): number;
  *   1. `doStore<S>(storage, parse, key?)` — `Store<S>` impl backed by
  *      `DurableObjectStorage`. JSON-stringifies on save, JSON-parses on load
  *      and returns `unknown` (invariant-8 boundary); the substrate then calls
- *      `migrate(raw)` (which forwards to `parse`) to turn it into `S | null`.
- *      Returns `null` (typed as `unknown`) when the key is absent. Structural
- *      JSON malformation throws at load — `run()`'s boot path surfaces that
- *      (PRD throw-semantics table: "store.load throw at boot → run() throws
- *      synchronously"). Shape mismatch is NOT a throw — `parse` returns
- *      `null` and the substrate boots fresh.
+ *      `migrate(raw)` (which forwards to `parse`) to turn it into `S`, `null`
+ *      or a refusal. Returns `null` (typed as `unknown`) when the key is
+ *      absent. Structural JSON malformation throws at load, and `run()`'s boot
+ *      path turns that into a `StoreRefusedError` on `ready`. A shape
+ *      mismatch is `parse`'s to answer with `refuse(reason)` (#316).
  *
  *   2. `deferredGateway` + `createAgentHost` (from `./host`) — THE transport for
  *      a DO-hosted agent. A `createAgent().toMachine()` machine owns exactly one
@@ -1892,22 +1963,23 @@ interface DoStoreOptions<S> {
  * `parse` is REQUIRED because DO storage is a real serialization boundary —
  * the bytes that come back through `JSON.parse` are structurally `unknown`,
  * and the caller (the DO that owns `S`) is the only party with enough
- * information to validate the shape. Returning `null` from `parse` means
- * "no usable persisted state" — the substrate boots `init` with `loaded =
- * null`, a known-good fresh-boot path. `parse` must NOT throw per the
- * `Store<S>.migrate` contract; shape mismatch is a value (null), not a
- * panic.
+ * information to validate the shape. `parse` returns `S` for a shape it
+ * recognizes, `null` when nothing was saved (the substrate boots `init` with
+ * `loaded = null`), and `refuse(reason)` for saved bytes it cannot read.
+ * `parse` must NOT throw per the `Store<S>.migrate` contract; a shape
+ * mismatch is a value (a refusal), not a panic.
  *
  * Structural malformations (the stored cell isn't even JSON) still throw at
  * `load()` — that's an infrastructure error, distinct from a schema
- * mismatch. The substrate surfaces it via `runtime.ready` rejection.
+ * mismatch. Either way `runtime.ready` rejects with `StoreRefusedError`
+ * before `init` runs, so nothing is saved over the old bytes.
  *
  * Concrete bite this closes: when a `State` variant is renamed between
  * deploys, the DO's new code previously received a value typed as the new
  * `S` that held a runtime string from the old `S` — silent undefined
- * behavior in `init`/`update`. After this, the boundary parse rejects the
- * old shape (returns null) and the DO boots fresh, picking up its new
- * schema from the next dispatch onward.
+ * behavior in `init`/`update`. After this, the boundary parse refuses the
+ * old shape and the DO fails to start instead of running on it or saving
+ * a fresh state over it.
  *
  * Serialization sharp edge (#182): `save` JSON-serializes the Model, and
  * `JSON.stringify` does NOT survive a `Map`/`Set`/`Date` (a `Map` stringifies
@@ -1920,14 +1992,18 @@ interface DoStoreOptions<S> {
  * value equal to `state`. Omit `serialize` and the Model must stay plain-JSON
  * (the `Record`-not-`Map` constraint the default imposes, unchanged).
  *
- * @param parse - boundary parse, the deserialize half (`unknown -> S | null`).
+ * @param parse - boundary parse, the deserialize half (`unknown -> S | null`,
+ *   or `refuse(reason)` for bytes it cannot read).
  * @param keyOrOptions - either the storage key (legacy positional form,
  *   defaults to `@@state`) or a {@link DoStoreOptions} bag carrying `key`
  *   and/or the `serialize` hook. A bare string is treated as `{ key }`.
+ *
+ * Either form is a `DeletableStore<S>`: `delete()` removes the state cell and
+ * its `<key>@@version` cell in one `storage.delete` call.
  */
-declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => S | null, keyOrOptions: DoStoreOptions<S> & {
+declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => Migrated<S>, 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>;
+}): FencedStore<S> & DeletableStore<S>;
+declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => Migrated<S>, keyOrOptions?: string | DoStoreOptions<S>): DeletableStore<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,20 +1,20 @@
-import { status, agentBootMsg, agentEvents } from '../chunk-XBZQT2TD.js';
-import '../chunk-G5E74IJB.js';
-import { createIntake } from '../chunk-OPH6Y4UT.js';
+import { status, agentBootMsg, AGENT_EVENT_TYPES, agentEvents } from '../chunk-PCJA2HTZ.js';
+import { createIntake } from '../chunk-JYNYG5SF.js';
 export { applyEffectEvent, emptyLedger, foldLedger, isOwed, pendingEffectsLedger, survivingEffects } from '../chunk-6IQPODUF.js';
-import '../chunk-4PXNZ5UY.js';
-import '../chunk-4NTCPTNQ.js';
+import '../chunk-XVIKSRCK.js';
+import '../chunk-YIMOFXST.js';
 import '../chunk-QNGYQMZB.js';
-import '../chunk-PR6TB3BL.js';
-import '../chunk-TXN2KFHF.js';
-import '../chunk-6XBEYZME.js';
+import '../chunk-WTSOW2MD.js';
+import '../chunk-C3G2QFEZ.js';
 import { defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-VBDU4JL6.js';
+import '../chunk-PR6TB3BL.js';
 import '../chunk-4LPY67E4.js';
-import '../chunk-GWWCCSDH.js';
-import '../chunk-QWIPH4YH.js';
-import '../chunk-KWNCM6XM.js';
-import '../chunk-C4U5D5HP.js';
-import { StoreConflictError, replay } from '../chunk-K4ETBNKS.js';
+import '../chunk-TXN2KFHF.js';
+import '../chunk-H2ELKHI6.js';
+import '../chunk-AHW2CLPT.js';
+import '../chunk-JVE2LBFJ.js';
+import '../chunk-FNGZMVIT.js';
+import { StoreConflictError, replay } from '../chunk-AIIXV4XB.js';
 
 // src/do/durable-timer.ts
 function durableTimer(config) {
@@ -234,11 +234,7 @@ function sseFromAgentEvents(runtime, hub, toFrame) {
     const frame = toFrame(event);
     if (frame !== null) hub.emit(frame);
   };
-  const offs = [
-    runtime.on("TurnSettled", push),
-    runtime.on("ToolSettled", push),
-    runtime.on("RunDone", push)
-  ];
+  const offs = AGENT_EVENT_TYPES.map((type) => runtime.on(type, push));
   return () => {
     for (const off of offs) off();
   };
@@ -714,6 +710,9 @@ function doStore(storage, parse, keyOrOptions = DEFAULT_STATE_KEY) {
     },
     migrate(raw) {
       return parse(raw);
+    },
+    async delete() {
+      await storage.delete([key, versionKey]);
     }
   };
   if (options.fenced !== true) return base;