iterate 0.2.7 → 0.3.0

package/dist/sdk-DMB-IM11.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-DMB-IM11.mjs","names":["RpcTarget","#live","#beforeRead","#subscription","RpcTarget","callable","#stub","#project","#projects","#session","#itx","#registryFor","#reads","#host","#memoHost"],"sources":["../src/sdk/capnweb/live-state/store.ts","../src/sdk/capnweb/live-state/protocol.ts","../src/sdk/capnweb/live-state/index.ts","../src/sdk/capnweb/index.ts","../src/serve-itx.ts","../src/sdk.ts"],"sourcesContent":["import { applyPatch } from \"./diff.ts\";\nimport { applyCompactPatch } from \"./compact.ts\";\nimport type { LiveUpdate } from \"./protocol.ts\";\n\n/**\n * The client half of the live-state channel: a tiny external store that folds\n * wire updates (one snapshot, then patches) back into the live value. The\n * server's `LiveState` engine is the producing half; `useLiveState` renders\n * this store via `useSyncExternalStore`.\n *\n * Revision discipline: a patch only applies when its `from` matches the held\n * revision. A mismatch means a message was missed (or arrived from a stale\n * subscription's revision line) — the store calls `resync` and holds its value\n * until the fresh snapshot lands, so a gap can never silently corrupt state.\n */\nexport type LiveStateStore<State> = {\n  getState: () => State | undefined;\n  subscribe: (listener: () => void) => () => void;\n  reset: () => void;\n  /** Fold one wire update into the held value; a revision gap means a missed patch — resync. */\n  apply: (update: LiveUpdate<State>, resync: () => void) => void;\n};\n\nexport function createLiveStateStore<State>(): LiveStateStore<State> {\n  let held: { revision: number; state: State | undefined } = { revision: -1, state: undefined };\n  const listeners = new Set<() => void>();\n  const notify = () => listeners.forEach((listener) => listener());\n  return {\n    getState: () => held.state,\n    subscribe: (listener: () => void) => {\n      listeners.add(listener);\n      return () => void listeners.delete(listener);\n    },\n    reset: () => {\n      held = { revision: -1, state: undefined };\n      notify();\n    },\n    apply: (update: LiveUpdate<State>, resync: () => void) => {\n      if (\"s\" in update) {\n        held = { revision: update.s[0], state: update.s[1] };\n      } else if (\"p\" in update) {\n        if (update.p[0] !== held.revision) {\n          resync();\n          return;\n        }\n        held = { revision: update.p[1], state: applyCompactPatch(held.state, update.p[2]) };\n      } else if (update.type === \"snapshot\") {\n        held = { revision: update.revision, state: update.state };\n      } else if (update.from !== held.revision) {\n        resync();\n        return;\n      } else {\n        held = { revision: update.to, state: applyPatch(held.state, update.patch) };\n      }\n      notify();\n    },\n  };\n}\n","/**\n * Wire types for the live-state channel: what a server engine pushes down a\n * subscription. A subscription always delivers one `snapshot` first (the full\n * current state), then a stream of `patch`es — each the minimal structural diff\n * since the previous revision. `useLiveState` reassembles these into the live\n * value, so feature code never touches these types directly.\n *\n * See `diff.ts` for how patches are produced (`diff`) and applied (`applyPatch`).\n */\n\n/**\n * A structural patch turning a previous JSON value into the next one. Three\n * shapes, discriminated by `set`, `array`, or an object patch:\n * - `{ set }` — replace this position wholesale. Used for primitives,\n *   `null`, type changes,\n *   and newly-added object keys.\n * - `{ fields?, drop? }` — descend into a plain object: `fields` maps each\n *   changed key to its own patch; `drop` lists keys that disappeared. At least\n *   one is present (an empty descend never gets emitted).\n * - `{ array }` — patch changed positions and set the resulting length. Kept\n *   elements retain their identity, including immutable text blocks inside a\n *   changed step. This form is sent only to subscribers requesting version 2.\n */\nexport type LiveStatePatch =\n  | { set: unknown }\n  | { array: { length: number; items: [number, LiveStatePatch][] } }\n  | { fields?: Record<string, LiveStatePatch>; drop?: string[] };\n\n/** Explicit codec negotiation keeps already-open clients valid across deploys. */\nexport type LiveStateSubscriptionOptions = { patchVersion?: 2 | 3 };\n\n/**\n * Version 3 addresses existing object fields by their sorted baseline position;\n * new fields use `+name`. Arrays use indices and an optional `#` length.\n * Primitives replace directly, `[value]` replaces other values, `[length, text]`\n * appends to a string, and `[]` deletes an object field. No dictionary survives\n * an update: every address refers to the acknowledged baseline of that patch.\n */\nexport type CompactLiveStatePatch =\n  | string\n  | number\n  | boolean\n  | null\n  | []\n  | [unknown]\n  | [number, string]\n  | { [address: string]: CompactLiveStatePatch };\n\n/** A transient reader's position; a new engine incarnation always has a new epoch. */\nexport type LiveStateCursor = { epoch: string; revision: number };\n\n/** A pull transports one delta, a fresh snapshot, or no change. No callback is retained. */\nexport type LiveStateRead<State> = { epoch: string; update: LiveUpdate<State> | null };\n\n/**\n * One message pushed down a live-state subscription. The first is always a\n * `snapshot` (a resync sends a fresh one); every message after carries only the\n * diff from revision `from` to `to`. Revisions are monotonic for the life of one\n * subscription, so a gap (`from` ≠ the client's revision) means a message was\n * missed and the client should resubscribe.\n *\n * `State` is asserted by the caller of `useLiveState` — the wire itself is\n * structure-agnostic.\n */\nexport type LiveUpdate<State = unknown> =\n  | { type: \"snapshot\"; revision: number; state: State }\n  | { type: \"patch\"; from: number; to: number; patch: LiveStatePatch }\n  | { s: [revision: number, state: State] }\n  | { p: [from: number, to: number, patch: CompactLiveStatePatch] };\n\nexport function isLiveStateSnapshot<State>(\n  update: LiveUpdate<State>,\n): update is Extract<LiveUpdate<State>, { type: \"snapshot\" } | { s: unknown }> {\n  return \"s\" in update || (\"type\" in update && update.type === \"snapshot\");\n}\n\nexport function liveStateRevision(update: LiveUpdate): number {\n  if (\"s\" in update) return update.s[0];\n  if (\"p\" in update) return update.p[1];\n  return update.type === \"snapshot\" ? update.revision : update.to;\n}\n","// `iterate/sdk/capnweb` — live state end to end: the snapshot+patch wire\n// protocol, the structural diff that produces patches, the client store that\n// reassembles them, and the SERVER engine (`LiveState`) that holds a value\n// and pushes minimal diffs to retained RPC subscribers. No socket, no keeper\n// — a Worker or Durable Object can import it without dragging the browser\n// session machinery into its bundle.\nimport { RpcTarget } from \"@iterate-com/capnweb\";\nimport type { LiveState as LiveStateEngine, LiveStateSubscription } from \"./engine.ts\";\nimport type { LiveStateSubscriptionOptions, LiveUpdate } from \"./protocol.ts\";\nimport { isThenable } from \"./retain.ts\";\nimport type { LiveStateRpc, LiveStateSubscriptionHandle } from \"./types.ts\";\n\ntype LiveStateSource<State extends object> = Pick<LiveStateEngine<State>, \"getState\" | \"subscribe\">;\n\ntype RefreshingLiveStateSource<State extends object> = {\n  readonly live: LiveStateSource<State>;\n  loadAndRefreshLive(): void | PromiseLike<void>;\n};\n\nexport { createLiveStateStore, type LiveStateStore } from \"./store.ts\";\nexport { applyPatch, diff } from \"./diff.ts\";\nexport { compactPatch, applyCompactPatch } from \"./compact.ts\";\nexport { isLiveStateSnapshot, liveStateRevision } from \"./protocol.ts\";\nexport type {\n  CompactLiveStatePatch,\n  LiveStateCursor,\n  LiveStateRead,\n  LiveStatePatch,\n  LiveStateSubscriptionOptions,\n  LiveUpdate,\n} from \"./protocol.ts\";\nexport { LiveState, type LiveStateSubscription } from \"./engine.ts\";\nexport type { LiveStateRpc, LiveStateSubscriptionHandle } from \"./types.ts\";\nexport {\n  disposeIgnoredRpcResult,\n  isThenable,\n  retainCallback,\n  type RetainedCallback,\n} from \"./retain.ts\";\n\n/**\n * Expose mutable server state as a read-only Cap'n Web capability.\n * Pass an in-memory `LiveState`, or a stream-processor registry whose engine\n * must hydrate before its first snapshot.\n */\nexport class LiveStateRpcTarget<State extends object>\n  extends RpcTarget\n  implements LiveStateRpc<State>\n{\n  readonly #live: LiveStateSource<State>;\n  readonly #beforeRead: (() => void | PromiseLike<void>) | undefined;\n\n  constructor(source: LiveStateSource<State> | RefreshingLiveStateSource<State>) {\n    super();\n    if (\"loadAndRefreshLive\" in source) {\n      this.#live = source.live;\n      this.#beforeRead = () => source.loadAndRefreshLive();\n    } else {\n      this.#live = source;\n      this.#beforeRead = undefined;\n    }\n  }\n\n  async get() {\n    const loading = this.#beforeRead?.();\n    if (isThenable(loading)) await loading;\n    return this.#live.getState();\n  }\n\n  async subscribe(\n    onUpdate: (update: LiveUpdate<State>) => unknown,\n    options?: LiveStateSubscriptionOptions,\n  ) {\n    const loading = this.#beforeRead?.();\n    if (isThenable(loading)) await loading;\n    return new LiveStateSubscriptionRpcTarget(this.#live.subscribe(onUpdate, options));\n  }\n}\n\n/**\n * The wire handle for one subscription — `ping`/`unsubscribe` over RPC.\n * Exported for relays that build their subscription OUTSIDE a `LiveState`\n * engine (the worker-local liveState-socket relay) but must hand back the\n * same handle shape `LiveStateRpcTarget.subscribe` does.\n */\nexport class LiveStateSubscriptionRpcTarget\n  extends RpcTarget\n  implements LiveStateSubscriptionHandle\n{\n  readonly #subscription: LiveStateSubscription;\n\n  constructor(subscription: LiveStateSubscription) {\n    super();\n    this.#subscription = subscription;\n  }\n\n  ping() {\n    return this.#subscription.ping();\n  }\n\n  unsubscribe() {\n    this.#subscription.unsubscribe();\n  }\n\n  [Symbol.dispose]() {\n    this.#subscription.unsubscribe();\n  }\n}\n","// `iterate/sdk/capnweb` — the project-independent Cap'n Web SDK surface.\n// Re-exporting the transport primitives and LiveState from one entry keeps a\n// consuming app on the exact Cap'n Web class identity used inside Iterate.\nexport * from \"@iterate-com/capnweb\";\nexport * from \"./live-state/index.ts\";\n","// `serveItx` — serve a NARROWED itx to a browser FROM a project worker or\n// Durable Object, over the app's own `/api`, speaking exactly the handshake\n// the SDK's session keeper expects (`iterate/client`, `iterate/sdk/itx/react`):\n// a Cap'n Web root whose `authenticate()` returns a Session whose\n// `projects.get(slug)` is the project. A page on the app's own origin needs\n// no configuration — the keeper dials the page's `/api` by default — and\n// `useItx()`, `useStreamConnection()`, `useLiveState()` work as on the OS\n// dashboard.\n//\n// The caller decides WHO the visitor is before calling this and WHAT they may\n// reach: `scope.surface` lists the members served, as dotted paths down to\n// each method. The platform side is `project.scope({ path, surface: roots })`\n// — a project-confined, non-admin itx exposing only those roots; this module\n// is the member-level allowlist. The credential the browser presents to\n// `authenticate()` is not authority here and is ignored.\n//\n// WHY A RELAY: a Cap'n Web session cannot serialize a Workers-RPC stub, so\n// the served project is a tree of small Cap'n Web targets built from the\n// served members: each leaf forwards its call onto the stub, browser callbacks\n// are retained and re-wrapped as plain functions, and a stub a call returns\n// (a connection handle) is wrapped so its methods stay callable. Anything not\n// listed does not exist on the served project at all.\nimport {\n  RpcTarget,\n  newHttpBatchRpcResponse,\n  newWorkersWebSocketRpcResponse,\n} from \"./sdk/capnweb/index.ts\";\nimport type { ItxAuthCredentials, Project } from \"./itx-api.generated.ts\";\n\nexport type ServeItxOptions = {\n  /** The worker's own itx (`this.itx`, `await env.ITX.get()`). Never reaches the browser. */\n  project: Project;\n  /**\n   * What the browser gets. `surface` lists the members served as DOTTED\n   * paths down to each METHOD: a leaf is called, so an object-valued member\n   * is listed through to its methods — `\"agent.liveState.get\"` and\n   * `\"agent.liveState.subscribe\"`, never `\"agent.liveState\"`. A bare root\n   * cannot be relayed because its members are unknown here.\n   */\n  scope: { path: string; surface: string[] };\n};\n\n/**\n * Answer an app's `/api` request with an itx session for one narrowed scope.\n * Call it from `fetch` after deciding who the visitor is:\n *\n *   if (url.pathname === \"/api\") {\n *     return await serveItx(request, {\n *       project: await this.env.ITX.get(),\n *       scope: {\n *         path: `/agents/web/${visitorIdFrom(request)}`,\n *         surface: [\n *           \"agent.message\",\n *           \"agent.liveState.get\",\n *           \"agent.liveState.subscribe\",\n *           \"agent.stream.openConnection\",\n *         ],\n *       },\n *     });\n *   }\n *\n * WebSocket upgrades carry the live session (stream connections, live\n * state); `POST` answers the client's HTTP-batch transport.\n */\nexport async function serveItx(request: Request, options: ServeItxOptions): Promise<Response> {\n  const { path, surface } = options.scope;\n  const roots = [...new Set(surface.map((entry) => entry.split(\".\", 1)[0]!))];\n  const served = relayServedProject(options.project.scope({ path, surface: roots }), surface);\n  const root = new ServedItxRoot(new ServedItxSession(served));\n  if (request.method === \"POST\") return await newHttpBatchRpcResponse(request, root);\n  if (request.headers.get(\"Upgrade\")?.toLowerCase() !== \"websocket\") {\n    return new Response(\"This endpoint accepts WebSocket upgrades and POST batches.\", {\n      status: 400,\n    });\n  }\n  return newWorkersWebSocketRpcResponse(request, root);\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// The relay.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The served project: the relay tree over a scoped stub for these dotted\n * members. Exported for the relay's own tests; callers use `serveItx`.\n * @internal\n */\nexport function relayServedProject(scoped: unknown, surface: readonly string[]): RpcTarget {\n  return relayNode(scoped, [], surfaceTree(surface));\n}\n\nconst LEAF = Symbol(\"served member\");\ntype SurfaceTree = { [member: string]: SurfaceTree | typeof LEAF };\n\n/** `[\"agent.message\", \"agent.stream.openConnection\"]` → nested member tree. */\nfunction surfaceTree(surface: readonly string[]): SurfaceTree {\n  const tree: SurfaceTree = {};\n  for (const entry of surface) {\n    const segments = entry.split(\".\");\n    if (segments.length < 2) {\n      throw new Error(\n        `serveItx cannot relay the bare root \"${entry}\": list the members to serve as dotted paths, e.g. \"${entry}.someMethod\"`,\n      );\n    }\n    let node = tree;\n    for (const [index, segment] of segments.entries()) {\n      const last = index === segments.length - 1;\n      const existing = node[segment];\n      if (last) {\n        if (existing !== undefined && existing !== LEAF) {\n          throw new Error(`serveItx: \"${entry}\" is both a member and a branch of the surface`);\n        }\n        node[segment] = LEAF;\n      } else {\n        if (existing === LEAF) {\n          throw new Error(`serveItx: \"${entry}\" is both a member and a branch of the surface`);\n        }\n        node = existing ?? (node[segment] = {});\n      }\n    }\n  }\n  return tree;\n}\n\n/**\n * One node of the served project: a real Cap'n Web target whose PROTOTYPE\n * carries exactly the served members — a method per leaf, a getter per\n * branch — plus `__describe`, which forwards so the platform's restricted\n * description comes back unchanged. A leaf IS a method call: an\n * object-valued member (`liveState`) must appear as a branch, i.e. listed\n * through to its methods.\n */\nfunction relayNode(stub: unknown, path: string[], tree: SurfaceTree): RpcTarget {\n  class ServedNode extends RpcTarget {}\n  for (const [member, child] of Object.entries(tree)) {\n    Object.defineProperty(\n      ServedNode.prototype,\n      member,\n      child === LEAF\n        ? {\n            configurable: true,\n            value: (...args: unknown[]) => forward(stub, [...path, member], args),\n            writable: true,\n          }\n        : { configurable: true, get: () => relayNode(stub, [...path, member], child) },\n    );\n  }\n  Object.defineProperty(ServedNode.prototype, \"__describe\", {\n    configurable: true,\n    value: () => forward(stub, [...path, \"__describe\"], []),\n    writable: true,\n  });\n  return new ServedNode();\n}\n\n/**\n * Walk `path` on the Workers-RPC stub (pipelined) and call the last segment\n * — as a genuine member call: extracting the method and `apply`ing it would\n * make the stub's proxy dial a remote member named \"apply\" with the stub\n * itself as an argument, which workerd refuses to serialize.\n */\nasync function forward(stub: unknown, path: string[], args: unknown[]): Promise<unknown> {\n  let target = stub as Record<string, unknown>;\n  for (const segment of path.slice(0, -1)) {\n    target = target[segment] as Record<string, unknown>;\n  }\n  const callable = target as Record<string, (...callArgs: unknown[]) => unknown>;\n  return relayResult(await callable[path.at(-1)!]!(...args.map((arg) => relayArgument(arg))));\n}\n\n/**\n * A browser callback arrives as a Cap'n Web stub function; the platform can\n * only call back a plain function, so wrap it. Plain data passes through,\n * recursively, because callbacks ride inside option objects.\n */\nfunction relayArgument(value: unknown): unknown {\n  if (typeof value === \"function\") {\n    // Cap'n Web releases a call's argument stubs when the call returns; a\n    // callback the platform keeps for a connection's lifetime must be\n    // retained past that — `dup()` is the stub's own way to say so. The\n    // duplicate is released with the session.\n    const stub = value as unknown as { dup?: () => unknown };\n    const callback = (typeof stub.dup === \"function\" ? stub.dup() : value) as (\n      ...callbackArgs: unknown[]\n    ) => unknown;\n    return (...callbackArgs: unknown[]) => callback(...callbackArgs);\n  }\n  if (Array.isArray(value)) return (value as unknown[]).map((entry) => relayArgument(entry));\n  if (isPlainObject(value)) {\n    const relayed: Record<string, unknown> = {};\n    for (const [key, entry] of Object.entries(value)) relayed[key] = relayArgument(entry);\n    return relayed;\n  }\n  return value;\n}\n\n/** A stub a call returned (a connection handle) is wrapped so its methods stay callable. */\nfunction relayResult(value: unknown): unknown {\n  return isWorkersRpcStub(value) ? new RelayedStub(value) : value;\n}\n\n/**\n * Workers-RPC stubs are callable proxies (`typeof` says \"function\") that\n * implement the dispose protocol; plain data has `Object.prototype` (or no\n * prototype), arrays are arrays, and a plain function has no disposer.\n * `cloudflare:workers` does not export the stub class to type against, so\n * the check is structural.\n */\nfunction isWorkersRpcStub(value: unknown): value is Disposable {\n  return (\n    (typeof value === \"function\" || (typeof value === \"object\" && value !== null)) &&\n    !Array.isArray(value) &&\n    !isPlainObject(value) &&\n    typeof (value as Partial<Disposable>)[Symbol.dispose] === \"function\"\n  );\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\") return false;\n  const prototype = Object.getPrototypeOf(value) as unknown;\n  return prototype === Object.prototype || prototype === null;\n}\n\n/** Names common protocols probe on any object; never forwarded. */\nconst NEVER_FORWARDED: ReadonlySet<string> = new Set([\n  \"then\",\n  \"toJSON\",\n  \"asymmetricMatch\",\n  \"constructor\",\n  \"dup\",\n  \"onRpcBroken\",\n]);\n\n/**\n * A stub a served call returned, as a Cap'n Web target: every unknown member\n * is a method forwarding onto the stub (a connection handle's `close()`,\n * `ping()`). Data properties of such a stub are not readable through the\n * relay — methods only.\n */\nclass RelayedStub extends RpcTarget {\n  readonly #stub: Disposable;\n  constructor(stub: Disposable) {\n    super();\n    this.#stub = stub;\n  }\n  static stubOf(relayed: RelayedStub): Disposable {\n    return relayed.#stub;\n  }\n}\nObject.setPrototypeOf(\n  RelayedStub.prototype,\n  new Proxy(Object.create(RpcTarget.prototype) as object, {\n    get(hopTarget, key, receiver) {\n      if (typeof key === \"symbol\" || key in hopTarget || NEVER_FORWARDED.has(key)) {\n        return Reflect.get(hopTarget, key, receiver);\n      }\n      if (!(receiver instanceof RelayedStub)) return undefined;\n      return (...args: unknown[]) => forward(RelayedStub.stubOf(receiver), [key], args);\n    },\n  }),\n);\n\n// ─────────────────────────────────────────────────────────────────────────────\n// The root the stock client expects.\n// ─────────────────────────────────────────────────────────────────────────────\n\nclass ServedItxProjects extends RpcTarget {\n  readonly #project: RpcTarget;\n\n  constructor(project: RpcTarget) {\n    super();\n    this.#project = project;\n  }\n\n  /** The served project, whatever slug the page addresses it by. */\n  get(_slug: string): RpcTarget {\n    return this.#project;\n  }\n}\n\nclass ServedItxSession extends RpcTarget {\n  readonly #projects: ServedItxProjects;\n\n  constructor(project: RpcTarget) {\n    super();\n    this.#projects = new ServedItxProjects(project);\n  }\n\n  get projects(): ServedItxProjects {\n    return this.#projects;\n  }\n\n  /** Also the session keeper's liveness probe. */\n  async __describe() {\n    return {\n      instructions: \"An app-served itx session: projects.get(slug) is the project.\",\n      children: { projects: \"The served projects catalog.\" },\n    };\n  }\n}\n\nclass ServedItxRoot extends RpcTarget {\n  readonly #session: ServedItxSession;\n\n  constructor(session: ServedItxSession) {\n    super();\n    this.#session = session;\n  }\n\n  /** The stock client's `authenticate` call. Identity was decided by the caller of `serveItx`. */\n  authenticate(_credentials: ItxAuthCredentials): ServedItxSession {\n    return this.#session;\n  }\n}\n","// `iterate/sdk` — what an iterate project repo imports from.\n//\n// The platform's public capability types (Project, Stream, StreamEvent,\n// ItxBinding, …) are generated from the platform's RpcTargets into\n// ./itx-api.generated.ts (regenerate from apps/os: `pnpm generate:itx-api`)\n// and re-exported here. Hand-written helpers for project code accumulate in\n// this file.\n//\n// Dynamic workers install and bundle this published package from their normal\n// package.json dependency. Preview deployments rewrite that dependency to the\n// exact pkg.pr.new artifact produced by the pull request.\nimport { DurableObject, RpcTarget, WorkerEntrypoint } from \"cloudflare:workers\";\nimport type {\n  DynamicWorkerCapability,\n  DynamicWorkerRef,\n  ItxBinding,\n  Project,\n  ProjectAuthPolicy,\n  StatefulDynamicWorkerRef,\n  StreamEvent,\n  StreamEventPager,\n} from \"./itx-api.generated.ts\";\nimport type { ProcessorStream, ProcessorStreamPager } from \"./processors/stream-handle.ts\";\nimport type {\n  ProcessorRuntimeState,\n  ProcessorSnapshot,\n  StreamDeliveryBatch,\n  StreamProcessorWakeRequest,\n  StreamProcessorWakeResponse,\n} from \"./processors/rpc-types.ts\";\nimport {\n  createStreamProcessorRegistry,\n  ProcessorFacet,\n  type ProcessorFacetAlarmProxy,\n  type ProcessorFacetHost,\n  type ProcessorFacetIdentity,\n  type RegisterableProcessor,\n  type RegisteredProcessorReads,\n  type StreamProcessorRegistry,\n} from \"./processors/cloudflare.ts\";\n\n// `.ts`-suffixed like every relative import here; tsc's\n// rewriteRelativeImportExtensions keeps the declaration emit for the published\n// dist/sdk.d.ts, where it must resolve to dist/itx-api.generated.d.ts.\nexport type * from \"./itx-api.generated.ts\";\nexport { serveItx } from \"./serve-itx.ts\";\n\n/**\n * What the platform supplies to every dynamic worker: the `ITX` binding\n * (`get()` for capability method calls, `fetch()` for HTTP into sibling\n * workers) and `ITERATE_WORKER_VERSION` — the content-addressed identity of\n * what Worker Loader executes: modules and effective compatibility settings.\n * Pass the latter as the `version` of a hosted processor registry: an\n * executable change resets a crash-looping keepalive's backoff budget, while\n * an unrelated source-repository revision does not.\n */\ntype IterateEnv = { ITX: ItxBinding; ITERATE_WORKER_VERSION: string };\ntype PipelinedProject = ReturnType<ItxBinding[\"get\"]>;\n\n/**\n * Forward a request to one of the project's dynamic workers (an \"app\") —\n * pages, APIs, streaming bodies, and WebSocket upgrades all ride through.\n *\n * Why this is a real `env.ITX.fetch` hop with the ref in a header, and not a\n * method call on the app: workerd only performs protocol work — WebSocket 101\n * upgrades, streaming response bodies — through genuine `fetch` handler hops\n * between workers. Calling `fetch` (or anything else) on an app handle from\n * `project.workers.get(ref)` is ordinary RPC: arguments and results are\n * serialized copies, so a Response carrying a socket cannot cross it (workerd\n * throws a DataCloneError). And because a fetch hop's only side channel for\n * \"which worker do I mean\" is the request itself, the target ref rides the\n * x-iterate-worker-dispatch header (JSON `{ ref, buildBudgetMs? }` — the same\n * ref shape `project.workers.get` takes). Method calls on apps still go\n * through `project.workers.get(ref)` RPC dispatch; HTTP never does.\n *\n * A cold build past `buildBudgetMs` (default 15s) answers a 503 building page\n * that refreshes itself, marked with x-iterate-worker-building — intercept\n * that response here to render your own.\n */\nasync function fetchDynamicWorker(\n  env: IterateEnv,\n  req: Request,\n  ref: DynamicWorkerRef,\n  opts?: { buildBudgetMs?: number },\n): Promise<Response> {\n  const headers = new Headers(req.headers);\n  headers.set(\n    \"x-iterate-worker-dispatch\",\n    JSON.stringify({ buildBudgetMs: opts?.buildBudgetMs ?? 15_000, ref }),\n  );\n  return await env.ITX.fetch(new Request(req, { headers }));\n}\n\n/**\n * Walk a dotted capability path over the worker instance and invoke the final\n * segment. The platform dispatches `itx.worker.<path>` calls as ONE flattened\n * `invokeCapability({ path, args })`, and this walks it in userland: nothing\n * ever crosses RPC except the final method's arguments and result, so a\n * getter on the worker class can hand back a whole vendor SDK (installed from\n * package.json) — or any nested surface — in a single round trip.\n */\nasync function invokeCapability(\n  receiver: unknown,\n  { args = [], path }: { args?: unknown[]; path: string[] },\n): Promise<unknown> {\n  for (const segment of path.slice(0, -1)) {\n    receiver = await Reflect.get(Object(receiver), segment);\n  }\n  const method = path.at(-1)!;\n  const handler = Reflect.get(Object(receiver), method);\n  if (typeof handler !== \"function\") {\n    throw new Error(`\"${path.join(\".\")}\" is not a method on this worker`);\n  }\n  return await Reflect.apply(handler, receiver, args);\n}\n\n/** Dispose an RPC stub, tolerating stubs without a disposer and disposers\n * that throw — cleanup must never mask the value it was cleaning up after. */\nfunction disposeStub(stub: unknown): void {\n  try {\n    (stub as Partial<Disposable>)[Symbol.dispose]?.();\n  } catch {}\n}\n\n/** Open a project itx session, use it, dispose it. RPC stubs from\n * `env.ITX.get()` must not outlive the invocation that dialed them, so every\n * operation opens its own session. */\nasync function withProject<T>(env: IterateEnv, fn: (project: Project) => Promise<T>): Promise<T> {\n  const project = await env.ITX.get();\n  try {\n    return await fn(project);\n  } finally {\n    disposeStub(project);\n  }\n}\n\n/**\n * Detach plain data returned by Workers RPC before releasing the per-call\n * result capability. Disposing the project root does not release values\n * obtained through it; each stream call owns its own result reference.\n */\nfunction detachPlainRpcResult<T>(result: T): T {\n  if (result === null || (typeof result !== \"object\" && typeof result !== \"function\")) {\n    return result;\n  }\n  // ProcessorStream returns JSON-shaped data only. Workers RPC adds a hidden\n  // disposer that is absent from the generated data types; a shallow spread\n  // preserves that data and drops the capability, but TypeScript cannot prove\n  // that the generic spread still has T's exact shape.\n  const detached = Array.isArray(result) ? [...result] : { ...result };\n  Reflect.deleteProperty(detached, Symbol.dispose);\n  try {\n    const dispose = Reflect.get(result, Symbol.dispose);\n    if (typeof dispose === \"function\") Reflect.apply(dispose, result, []);\n  } catch (error) {\n    // The plain data is already detached and the remote operation succeeded.\n    // Keep cleanup failure visible without rewriting that outcome as failure.\n    console.warn(\"project stream RPC result dispose failed after detaching plain data\", { error });\n  }\n  return detached as T;\n}\n\n/**\n * A view of `target` with `overrides` in front and everything else passed\n * through. Proxies (not spreads or Object.create) because DurableObjectState\n * and DurableObjectStorage are host objects: their methods must be invoked\n * with the REAL receiver or workerd throws \"Illegal invocation\".\n */\nfunction overlay<T extends object>(target: T, overrides: Record<PropertyKey, unknown>): T {\n  return new Proxy(target, {\n    get(object, prop) {\n      // Own keys only: `in` would match Object.prototype inherits\n      // (toString, …) and shadow the host object's.\n      if (Object.hasOwn(overrides, prop)) return overrides[prop];\n      const value = Reflect.get(object, prop, object);\n      return typeof value === \"function\" ? value.bind(object) : value;\n    },\n  });\n}\n\n/**\n * A {@link ProcessorStream} over the project stream at `path`, dialed through\n * the platform ITX binding — the stream handle a worker-hosted stream\n * processor registry needs (`iterate/processors`; see the config-repo\n * template's guestbook for the full hosting shape). RPC stubs from\n * `env.ITX.get()` must not outlive the invocation that dialed them, so every\n * operation opens, uses, and disposes its own session; `readEvents` owns one\n * session for its pager's lifetime (scope it with `using`, like any pager).\n */\nexport function itxProjectStream(env: IterateEnv, path: string): ProcessorStream {\n  const withStream = <T>(fn: (streams: Project[\"streams\"]) => Promise<T>): Promise<T> =>\n    withProject(env, (project) => fn(project.streams)).then(detachPlainRpcResult);\n  return {\n    append: (...events) => withStream((streams) => streams.get(path).append(...events)),\n    appendIfStreamId: (args) => withStream((streams) => streams.get(path).appendIfStreamId(args)),\n    getEvent: (args) => withStream((streams) => streams.get(path).getEvent(args)),\n    getEvents: (args) => withStream((streams) => streams.get(path).getEvents(args)),\n    getEventPage: (args) => withStream((streams) => streams.get(path).getEventPage(args)),\n    readEvents: (args): ProcessorStreamPager => {\n      let opened: Promise<{ pager: StreamEventPager; project: Disposable }> | undefined;\n      let closed = false;\n      return {\n        next: async () => {\n          if (closed) return [];\n          opened ??= env.ITX.get().then((project) => ({\n            pager: project.streams.get(path).readEvents(args),\n            project,\n          }));\n          const { pager } = await opened;\n          return detachPlainRpcResult(await pager.next());\n        },\n        [Symbol.dispose]() {\n          closed = true;\n          void opened\n            ?.then(({ pager, project }) => {\n              disposeStub(pager);\n              disposeStub(project);\n            })\n            .catch(() => {});\n        },\n      };\n    },\n    at: (siblingPath) => itxProjectStream(env, siblingPath),\n  };\n}\n\n/** Where the platform-delivered self ref lives in this worker's own storage\n * (see {@link IterateDurableObject.__stashSelfRef}). */\nconst SELF_REF_STORAGE_KEY = \"iterate:self-ref\";\n\n/**\n * Durable alarms for a stateful dynamic worker, presented as the ordinary\n * `DurableObjectState` alarm API — what `IterateDurableObject` installs as\n * `this.ctx`, so alarms on stateful workers just work.\n *\n * workerd does not implement alarms for facet-hosted Durable Objects — the\n * hosting model for stateful dynamic workers (workerd#6810; a facet\n * `setAlarm` even appears to succeed, then poisons the commit path). So the\n * platform Durable Object that hosts this worker keeps the real alarm on its\n * behalf: the trio here dials `itx.workers.get(ref).setAlarm/getAlarm` on the\n * worker's own ref — delivered by the host before any other traffic and\n * stashed durably ({@link IterateDurableObject.__stashSelfRef}) — and the\n * host's fire calls this class's `alarm(alarmInfo)` method, retried by the\n * platform if it throws, exactly like a native alarm handler.\n *\n * Everything except the three alarm methods is the worker's own `ctx`,\n * untouched (`storage.kv`, `waitUntil`, WebSocket APIs, …), so code written\n * against this state uses only standard Durable Object concepts, and if\n * workerd ships facet alarms the shim disappears without a caller changing.\n * Honest divergences: the alarm methods ignore the native `options` bag,\n * alarms armed inside `storage.transaction()` bypass the shim, and a class\n * with no `alarm()` handler fails at fire time (native `setAlarm` rejects at\n * arm time; the shim cannot check).\n */\nfunction selfAlarmState<State extends DurableObjectState>(ctx: State, env: IterateEnv): State {\n  const withSelf = <T>(fn: (worker: DynamicWorkerCapability) => Promise<T>): Promise<T> => {\n    const ref = ctx.storage.kv.get<StatefulDynamicWorkerRef>(SELF_REF_STORAGE_KEY);\n    if (ref === undefined) {\n      // Unreachable after any platform contact — every call, fetch, and\n      // alarm fire delivers the ref first. Constructor bodies run before\n      // that first contact, hence the carve-out in the error.\n      throw new Error(\n        \"this worker's own ref has not been delivered yet — alarms are unavailable in the \" +\n          \"constructor; arm from a handler instead\",\n      );\n    }\n    return withProject(env, (project) => fn(project.workers.get(ref)));\n  };\n  return overlay(ctx, {\n    storage: overlay(ctx.storage, {\n      setAlarm: (scheduledTime: number | Date) =>\n        withSelf((worker) =>\n          worker.setAlarm(\n            typeof scheduledTime === \"number\" ? scheduledTime : scheduledTime.getTime(),\n          ),\n        ),\n      deleteAlarm: () => withSelf((worker) => worker.setAlarm(null)),\n      getAlarm: () => withSelf((worker) => worker.getAlarm()),\n    }),\n  });\n}\n\n/**\n * Base class for stateless dynamic workers — the project worker (a repo's\n * default export) and stateless apps. A WorkerEntrypoint whose env carries\n * the platform's itx binding, plus the platform ceremony every worker needs\n * but shouldn't have to hand-roll:\n *\n * - `processEventBatch` / `processEvent`: the platform delivers every\n *   committed DURABLE event on every stream in the project as checkpointed\n *   per-stream batches — in per-stream order, at-least-once. Events appended\n *   with `ephemeral: true` (LLM streaming chunks and other transient\n *   signals) never arrive here. Session callbacks can receive one while its\n *   body remains in the Stream Durable Object's bounded memory buffer; react\n *   here to the durable fact that supersedes it (e.g. an assistant-role\n *   `agents/context-added` item). The base unpacks batches\n *   into one `processEvent(event)` call per event; override `processEvent` to react\n *   (one `if` per reaction, keyed on event.path + event.type). Throwing (or a worker that fails to build) leaves that\n *   stream's checkpoint in place and the whole batch is redelivered later,\n *   so return normally to advance past events you don't care about — and\n *   anything a reaction appends should carry an idempotency key.\n * - `invokeCapability`: the flattened `itx.worker.<path>` dispatcher — add a\n *   getter or method to your class and it becomes a capability surface.\n * - `fetchDynamicWorker`: forward HTTP (WebSockets included) to another of\n *   the project's dynamic workers.\n */\nexport class IterateWorkerEntrypoint<\n  Env extends IterateEnv = IterateEnv,\n> extends WorkerEntrypoint<Env> {\n  #itx: PipelinedProject | undefined;\n\n  constructor(ctx: ConstructorParameters<typeof WorkerEntrypoint<Env>>[0], env: Env) {\n    super(ctx, env);\n    this.env = env;\n  }\n\n  /**\n   * This invocation's project-root itx. Cloudflare constructs one\n   * WorkerEntrypoint per invocation and releases its RPC stubs when that\n   * execution context ends. The getter returns the native Workers RPC\n   * promise-proxy, so `await this.itx.agents.list()` pipelines immediately;\n   * repeated access within one event batch or fetch reuses the same handle.\n   *\n   * Durable Objects have a longer, multi-invocation lifetime and no eviction\n   * callback, so IterateDurableObject deliberately does not expose this\n   * memoized getter.\n   */\n  protected get itx(): PipelinedProject {\n    return (this.#itx ??= this.env.ITX.get());\n  }\n\n  /**\n   * Run the project-member auth partial fetch without transferring the app's\n   * request body on paths auth only inspects. The callback POST belongs to\n   * auth, so that one path deliberately transfers the complete request.\n   */\n  protected async fetchProjectAuth(\n    request: Request,\n    policy: ProjectAuthPolicy,\n  ): Promise<Response | null> {\n    if (request.method === \"POST\" && new URL(request.url).pathname === \"/_iterate/auth/callback\") {\n      return await this.itx.auth.get(policy).fetch(request);\n    }\n\n    const authRequest = new Request(request.url, {\n      headers: request.headers,\n      method: request.method,\n    });\n    return await this.itx.auth.get(policy).fetch(authRequest);\n  }\n\n  /** See `fetchDynamicWorker` at module level: a real fetch hop into a\n   * sibling dynamic worker — the only lane that can carry WebSocket upgrades\n   * and streaming bodies (RPC serializes; sockets can't cross it). */\n  protected async fetchDynamicWorker(\n    req: Request,\n    ref: DynamicWorkerRef,\n    opts?: { buildBudgetMs?: number },\n  ): Promise<Response> {\n    return await fetchDynamicWorker(this.env, req, ref, opts);\n  }\n\n  /** Platform entry point for event delivery (see the class docstring for\n   * the delivery contract). Override `processEvent`, not this, unless you\n   * need whole-batch atomicity. */\n  async processEventBatch(batch: StreamDeliveryBatch): Promise<void> {\n    for (const event of batch.events) await this.processEvent(event);\n  }\n\n  /** Called once per delivered event, in per-stream order, at-least-once.\n   * Override to react; the default ignores everything. */\n  protected async processEvent(_event: StreamEvent): Promise<void> {}\n\n  /** Platform entry point for flattened `itx.worker.<path>` capability\n   * calls (see the class docstring). */\n  async invokeCapability(input: { args?: unknown[]; path: string[] }): Promise<unknown> {\n    return await invokeCapability(this, input);\n  }\n}\n\n/**\n * Base class for stateful dynamic workers (apps hosted as Durable Objects\n * under a `durableWorkerKey`). Same platform surface as\n * `IterateWorkerEntrypoint` — see its docstring for the event-delivery and\n * capability-dispatch contracts — on a DurableObject, so state survives\n * across requests and WebSockets can be served from `fetch`. Durable alarms\n * work natively — `this.ctx.storage.setAlarm(...)` plus an `alarm()` method\n * on the class — even though this object is hosted as a workerd facet with\n * no alarms of its own; see {@link selfAlarmState} for the mechanism.\n */\nexport class IterateDurableObject<Env extends IterateEnv = IterateEnv> extends DurableObject<Env> {\n  constructor(ctx: ConstructorParameters<typeof DurableObject<Env>>[0], env: Env) {\n    super(ctx, env);\n    this.env = env;\n    // Read back through the property so the overlay carries the exact ctx\n    // type the base class declares in every typecheck context.\n    this.ctx = selfAlarmState(this.ctx, this.env);\n  }\n\n  /**\n   * Platform bootstrap door: the Durable Object hosting this worker delivers\n   * the worker's OWN ref here before any other traffic in its incarnation —\n   * a facet has no channel to learn its identity by itself, and the ref is\n   * what the alarm shim dials (`itx.workers.get(ref)` resolves back to the\n   * hosting DO). Stashed durably, so a warm facet under a fresh host needs\n   * no re-delivery to keep working.\n   */\n  __stashSelfRef(ref: StatefulDynamicWorkerRef): void {\n    this.ctx.storage.kv.put(SELF_REF_STORAGE_KEY, ref);\n  }\n\n  /** A real fetch hop into a sibling dynamic worker — see\n   * `IterateWorkerEntrypoint.fetchDynamicWorker`. */\n  protected async fetchDynamicWorker(\n    req: Request,\n    ref: DynamicWorkerRef,\n    opts?: { buildBudgetMs?: number },\n  ): Promise<Response> {\n    return await fetchDynamicWorker(this.env, req, ref, opts);\n  }\n\n  /** Platform entry point for event delivery — see\n   * `IterateWorkerEntrypoint.processEventBatch`. */\n  async processEventBatch(batch: StreamDeliveryBatch): Promise<void> {\n    for (const event of batch.events) await this.processEvent(event);\n  }\n\n  /** Called once per delivered event — see\n   * `IterateWorkerEntrypoint.processEvent`. */\n  protected async processEvent(_event: StreamEvent): Promise<void> {}\n\n  /** Platform entry point for flattened `itx.worker.<path>` capability\n   * calls — see `IterateWorkerEntrypoint.invokeCapability`. */\n  async invokeCapability(input: { args?: unknown[]; path: string[] }): Promise<unknown> {\n    return await invokeCapability(this, input);\n  }\n}\n// =============================================================================\n// Durable Object stream-processor hosting.\n// =============================================================================\n\nconst HOST_PROJECT_ID_KEY = \"iterate:processor-host:project-id\";\nconst HOST_STREAM_PATH_KEY = \"iterate:processor-host:stream-path\";\n\ntype WakeRegistryLookup = (\n  projectId: string,\n  path: string,\n) => Pick<StreamProcessorRegistry<object>, \"wakeStreamProcessor\">;\n\n/**\n * The worker's `processor` node: the wake door the stream spine dials PLUS\n * the public read verbs of the standard processor contract\n * (`StreamProcessorRpc`). The reads serve the registered runner directly, so\n * `streams.get(path).subscriptions.get(name).processor` and the stream's\n * `waitUntilProcessed` barrier reach an expression-placed dynamic worker's\n * processor with no extra wiring — the stream replays those verbs onto this\n * node (the stored wake expression minus its trailing wake step). It crosses\n * Workers RPC as a property read before its method is called, so it must be\n * a real RpcTarget.\n */\nclass ProcessorWakeTarget extends RpcTarget {\n  readonly #registryFor: WakeRegistryLookup;\n  readonly #reads: () => Promise<RegisteredProcessorReads<object>>;\n\n  constructor(\n    registryFor: WakeRegistryLookup,\n    reads: () => Promise<RegisteredProcessorReads<object>>,\n  ) {\n    super();\n    this.#registryFor = registryFor;\n    this.#reads = reads;\n  }\n\n  async wakeStreamProcessor(\n    request: StreamProcessorWakeRequest,\n  ): Promise<StreamProcessorWakeResponse> {\n    if (request.stream.projectId === null) {\n      throw new Error(\"hosted stream processors require project streams\");\n    }\n    // The registry fences mismatched coordinates itself, so a host with a\n    // fixed home stream rejects a stray wake instead of adopting its path.\n    return await this.#registryFor(\n      request.stream.projectId,\n      request.stream.path,\n    ).wakeStreamProcessor(request);\n  }\n\n  /** One consistent read of the committed fold, pulled through the durable\n   * stream tail first (read-your-writes, the hosting relays' catch-up leg). */\n  async snapshot(): Promise<ProcessorSnapshot<object>> {\n    const reads = await this.#reads();\n    await reads.catchUp();\n    return await reads.snapshot();\n  }\n\n  async getRuntimeState(): Promise<ProcessorRuntimeState<object>> {\n    return await (await this.#reads()).getRuntimeState();\n  }\n\n  /** Offset barrier against the runner's committed fold. The runner's waiter\n   * self-pulls, so its timeout bounds the whole read-your-writes operation. */\n  async waitUntilProcessed(input: { offset: number; timeoutMs?: number }): Promise<void> {\n    await (await this.#reads()).waitUntilEvent(input);\n  }\n}\n\n/**\n * The platform deps the host derives and hands a processor factory: the home\n * stream and its coordinates. Everything else a processor needs (clocks,\n * clients, itx-backed capabilities) the factory wires off `this.env`.\n */\nexport type ProcessorHostDeps = {\n  path: string;\n  projectId: string;\n  stream: ProcessorStream;\n};\n\nexport type ProcessorHost<State extends object> = {\n  /** The lazily built registry. Outside a wake request the coordinates come\n   * from the durable cache, the static `path`, or one project dial. */\n  registry(): Promise<StreamProcessorRegistry<State>>;\n  /** One consistent read of the hosted processor's committed fold. */\n  snapshot(): Promise<ProcessorSnapshot<State>>;\n  /** Assign to a `processor` getter — the wake door the stream spine dials,\n   * which also serves the standard read verbs (snapshot / getRuntimeState /\n   * waitUntilProcessed) so the subscriptions catalog and the stream barrier\n   * reach this processor. */\n  readonly wakeProcessor: ProcessorWakeTarget;\n  /** Route the Durable Object's `alarm()` here. Nothing cached means no\n   * registry ever armed one, so a stray fire is a no-op. */\n  handleAlarm(alarmInfo?: AlarmInvocationInfo): Promise<void>;\n};\n\n/**\n * Host one stream processor in a Durable Object: the registry ceremony, the\n * RPC-safe wake door, the alarm multiplex, and the durable coordinate cache\n * in one place, so an app class is only its processor plus its own verbs.\n *\n * With `path` the host serves one fixed home stream (the guestbook shape).\n * Without it the host learns its stream from the first wake request and\n * caches the coordinates durably (one Durable Object per dynamic stream,\n * keyed by the ref that names it). One host per Durable Object — the cache\n * keys assume it.\n */\nexport function createProcessorHost<State extends object = Record<string, unknown>>(args: {\n  ctx: DurableObjectState;\n  env: IterateEnv;\n  path?: string;\n  /** Post-eviction keepalive recovery, for processors that owe registered work. */\n  recovery?: boolean;\n  createProcessor(deps: ProcessorHostDeps): RegisterableProcessor;\n}): ProcessorHost<State> {\n  let built:\n    | { reads: RegisteredProcessorReads<State>; registry: StreamProcessorRegistry<State> }\n    | undefined;\n\n  const ensure = (projectId: string, path: string) => {\n    if (built === undefined) {\n      args.ctx.storage.kv.put(HOST_PROJECT_ID_KEY, projectId);\n      args.ctx.storage.kv.put(HOST_STREAM_PATH_KEY, path);\n      const stream = itxProjectStream(args.env, path);\n      const registry = createStreamProcessorRegistry<State>(args.ctx, {\n        path,\n        projectId,\n        stream,\n        version: args.env.ITERATE_WORKER_VERSION,\n      });\n      const processor = registry.register(\n        args.createProcessor({ path, projectId, stream }),\n        args.recovery === undefined ? undefined : { recovery: args.recovery },\n      );\n      built = {\n        // `RegisterableProcessor` erases the contract, so `reads` comes back\n        // `<unknown>`; the caller's `State` is the same assertion it already\n        // makes for the registry generic above.\n        reads: registry.reads(processor) as RegisteredProcessorReads<State>,\n        registry,\n      };\n    }\n    return built;\n  };\n\n  const buildOutsideWake = async () => {\n    if (built !== undefined) return built;\n    const path = args.path ?? args.ctx.storage.kv.get<string>(HOST_STREAM_PATH_KEY);\n    if (path === undefined) {\n      throw new Error(\"this processor host learns its stream from the first wake request\");\n    }\n    const projectId =\n      args.ctx.storage.kv.get<string>(HOST_PROJECT_ID_KEY) ??\n      (await withProject(args.env, async (project) => await project.projectId));\n    return ensure(projectId, path);\n  };\n\n  return {\n    registry: async () => (await buildOutsideWake()).registry,\n    snapshot: async () => await (await buildOutsideWake()).reads.snapshot(),\n    wakeProcessor: new ProcessorWakeTarget(\n      (projectId, path) => ensure(projectId, args.path ?? path).registry,\n      async () => (await buildOutsideWake()).reads as RegisteredProcessorReads<object>,\n    ),\n    async handleAlarm(alarmInfo?: AlarmInvocationInfo) {\n      const projectId = args.ctx.storage.kv.get<string>(HOST_PROJECT_ID_KEY);\n      const path = args.path ?? args.ctx.storage.kv.get<string>(HOST_STREAM_PATH_KEY);\n      if (projectId === undefined || path === undefined) return;\n      await ensure(projectId, path).registry.handleAlarm(alarmInfo);\n    },\n  };\n}\n\n/**\n * Ergonomic base for a Durable Object that hosts exactly one stream processor.\n *\n * It collapses the host boilerplate every processor app writes by hand today —\n * a {@link createProcessorHost} field, an `alarm()` that forwards to it, and a\n * `processor` getter exposing the wake door — down to a single\n * {@link createProcessor} factory. First-party and userspace processors are\n * authored the SAME way: all a subclass writes is how to build its processor\n * from the host-derived platform deps (`{ stream, path, projectId }`) plus\n * whatever it wires off `this.env`. That single seam is why a built-in\n * processor forks into userspace with no change to the processor itself — only\n * the dep wiring in `createProcessor` differs.\n *\n * Host-agnostic: the exact same class runs as its own Durable Object, as a\n * facet of the Stream DO, or as a facet of another DO. Only the alarm adapter\n * (native vs parent-proxied) and who dials the wake door differ per host, and\n * the host owns both.\n *\n * ```ts\n * export class GuestbookDurableObject extends StreamProcessorDurableObject<GuestbookState> {\n *   protected readonly streamPath = guestbookStreamPath; // fixed home stream\n *   protected createProcessor(deps: ProcessorHostDeps) {\n *     return new GuestbookProcessor(deps);\n *   }\n *   // alarm(), the `processor` wake door, snapshot(), registry() — inherited.\n * }\n * ```\n */\nexport abstract class StreamProcessorDurableObject<\n  State extends object = Record<string, unknown>,\n  Env extends IterateEnv = IterateEnv,\n> extends IterateDurableObject<Env> {\n  /**\n   * Build the processor from the host-derived platform deps. Wire your own deps\n   * (clocks, clients, itx-backed capabilities) off `this.env` here — this is\n   * the one method a processor app must implement, and the seam that keeps a\n   * built-in processor forkable into userspace unchanged.\n   */\n  protected abstract createProcessor(deps: ProcessorHostDeps): RegisterableProcessor;\n\n  /**\n   * A fixed home stream path (the guestbook shape). Leave undefined to learn\n   * the stream from the first wake request and cache the coordinates durably\n   * (one Durable Object per dynamic stream).\n   */\n  protected readonly streamPath?: string;\n\n  /**\n   * Post-eviction keepalive recovery, for processors that owe registered\n   * background work (the obligation pattern). Off by default.\n   */\n  protected readonly recovery: boolean = false;\n\n  /**\n   * Built lazily on first door/alarm access — deliberately NOT a field\n   * initializer. A base-class field initializer runs before the subclass's\n   * `streamPath` / `recovery` field initializers, so it would capture the base\n   * defaults instead of a subclass's overrides; reading them on first use\n   * sidesteps that ordering trap. Memoized because the host owns the registry\n   * cache, and one host per Durable Object is assumed.\n   */\n  #memoHost?: ProcessorHost<State>;\n  get #host(): ProcessorHost<State> {\n    return (this.#memoHost ??= createProcessorHost<State>({\n      ctx: this.ctx,\n      env: this.env,\n      path: this.streamPath,\n      recovery: this.recovery,\n      createProcessor: (deps) => this.createProcessor(deps),\n    }));\n  }\n\n  /**\n   * The processor node the stream spine dials: the wake door plus the standard\n   * read verbs (`snapshot` / `getRuntimeState` / `waitUntilProcessed`), so the\n   * subscriptions catalog and the stream barrier reach this processor. It\n   * crosses Workers RPC as a property read before its method is called, so it\n   * must be a real RpcTarget — which the host guarantees.\n   */\n  get processor() {\n    return this.#host.wakeProcessor;\n  }\n\n  /** Route the Durable Object's native `alarm()` into the host's multiplex. */\n  async alarm(alarmInfo?: AlarmInvocationInfo): Promise<void> {\n    await this.#host.handleAlarm(alarmInfo);\n  }\n\n  /**\n   * One consistent read of the hosted processor's committed fold, for a\n   * subclass's own read verbs (e.g. a `getState()`).\n   */\n  protected snapshot(): Promise<ProcessorSnapshot<State>> {\n    return this.#host.snapshot();\n  }\n\n  /**\n   * The lazily built registry, for subclasses that drive catch-up / live\n   * refresh directly (the guestbook's HTTP + append flow).\n   */\n  protected registry(): Promise<StreamProcessorRegistry<State>> {\n    return this.#host.registry();\n  }\n}\n\n/**\n * Ergonomic base for a userspace stream processor hosted as a FACET of the\n * platform's Stream Durable Object — the `facet-processor` subscription with a\n * `userspace` source, whose `StatefulDynamicWorkerRef` names THIS class. The\n * Stream DO loads the class from the project's source and starts it with\n * `ctx.facets.get(name, …)`, so it runs INSIDE the stream it serves: wakes are\n * an in-process parent→facet dial (no itx wake expression), and checkpoints /\n * projections land in the facet's own private SQLite.\n *\n * Same authoring seam as {@link StreamProcessorDurableObject} — a subclass\n * writes only `createProcessor` (and sets `recovery` when it owes background\n * work) — so a processor forks between \"its own Durable Object\" and \"a facet\n * of its stream\" with no change to the processor itself. The two differences a\n * facet forces, both handled here:\n *\n * - **No native alarm.** workerd does not implement alarms for facets\n *   (workerd#6810), so this base routes the registry's keepalive/recovery\n *   alarm through the parent's real platform alarm over itx —\n *   `streams.get(path).proxySetAlarm/proxyDeleteAlarm/proxyGetAlarm`, the\n *   itx-channel twin of a stateful worker's `workers.get(ref).setAlarm`. The\n *   parent fires it back as {@link ProcessorFacet.handleAlarm}. NEVER define\n *   `alarm()` on a subclass (the base throws): a facet's native `setAlarm`\n *   would appear to succeed, then poison its output gate.\n * - **Identity by first-contact `configure`, not the constructor.** The Stream\n *   DO delivers `{ parentName, projectId, path }`; the base stashes it and\n *   rebuilds the host from that stash on every incarnation (see\n *   {@link ProcessorFacet}).\n *\n * ```ts\n * export class GuestbookFacet extends StreamProcessorFacet {\n *   protected readonly recovery = true; // owes background work\n *   protected createProcessor(deps: ProcessorHostDeps) {\n *     return new GuestbookProcessor(deps);\n *   }\n * }\n * ```\n */\nexport abstract class StreamProcessorFacet<\n  Env extends IterateEnv = IterateEnv,\n> extends ProcessorFacet<Env> {\n  /**\n   * Build the processor from the host-derived platform deps, wiring your own\n   * deps (clocks, clients, itx-backed capabilities) off `this.env` — the one\n   * method a facet-hosted processor app implements, identical to\n   * {@link StreamProcessorDurableObject.createProcessor}.\n   */\n  protected abstract createProcessor(deps: ProcessorHostDeps): RegisterableProcessor;\n\n  /**\n   * Post-eviction keepalive recovery, for processors that owe registered\n   * background work (the obligation pattern). Off by default.\n   */\n  protected readonly recovery: boolean = false;\n\n  /**\n   * Dial the parent stream's alarm proxy over itx, resolved PER CALL (a stub\n   * must not outlive its RPC turn), each verb opening and disposing its own\n   * session like {@link itxProjectStream}. `identity.path` is the coordinate;\n   * `parentName` is unused here (userspace facets have no `env.STREAM`).\n   */\n  protected parentAlarms(identity: ProcessorFacetIdentity): ProcessorFacetAlarmProxy {\n    const env = this.env;\n    const { path } = identity;\n    return {\n      proxySetAlarm: (scheduledTimeMs) =>\n        withProject(env, (project) => project.streams.get(path).proxySetAlarm(scheduledTimeMs)),\n      proxyDeleteAlarm: () =>\n        withProject(env, (project) => project.streams.get(path).proxyDeleteAlarm()),\n      proxyGetAlarm: () => withProject(env, (project) => project.streams.get(path).proxyGetAlarm()),\n    };\n  }\n\n  /**\n   * Build the host wiring from the stashed identity: the stream handle is the\n   * same itx-backed {@link itxProjectStream} a worker-hosted processor appends\n   * through, and the single processor is registered under this facet's name.\n   */\n  protected createHost(identity: ProcessorFacetIdentity): ProcessorFacetHost {\n    if (identity.projectId === null) {\n      throw new Error(\"userspace stream-processor facets require a project stream\");\n    }\n    const { projectId, path } = identity;\n    const stream = itxProjectStream(this.env, path);\n    return {\n      stream,\n      version: this.env.ITERATE_WORKER_VERSION,\n      registerProcessors: (registry) => {\n        registry.register(this.createProcessor({ path, projectId, stream }), {\n          recovery: this.recovery,\n        });\n      },\n    };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,uBAAqD;CACnE,IAAI,OAAuD;EAAE,UAAU;EAAI,OAAO,KAAA;CAAU;CAC5F,MAAM,4BAAY,IAAI,IAAgB;CACtC,MAAM,eAAe,UAAU,SAAS,aAAa,SAAS,CAAC;CAC/D,OAAO;EACL,gBAAgB,KAAK;EACrB,YAAY,aAAyB;GACnC,UAAU,IAAI,QAAQ;GACtB,aAAa,KAAK,UAAU,OAAO,QAAQ;EAC7C;EACA,aAAa;GACX,OAAO;IAAE,UAAU;IAAI,OAAO,KAAA;GAAU;GACxC,OAAO;EACT;EACA,QAAQ,QAA2B,WAAuB;GACxD,IAAI,OAAO,QACT,OAAO;IAAE,UAAU,OAAO,EAAE;IAAI,OAAO,OAAO,EAAE;GAAG;QAC9C,IAAI,OAAO,QAAQ;IACxB,IAAI,OAAO,EAAE,OAAO,KAAK,UAAU;KACjC,OAAO;KACP;IACF;IACA,OAAO;KAAE,UAAU,OAAO,EAAE;KAAI,OAAO,kBAAkB,KAAK,OAAO,OAAO,EAAE,EAAE;IAAE;GACpF,OAAO,IAAI,OAAO,SAAS,YACzB,OAAO;IAAE,UAAU,OAAO;IAAU,OAAO,OAAO;GAAM;QACnD,IAAI,OAAO,SAAS,KAAK,UAAU;IACxC,OAAO;IACP;GACF,OACE,OAAO;IAAE,UAAU,OAAO;IAAI,OAAO,WAAW,KAAK,OAAO,OAAO,KAAK;GAAE;GAE5E,OAAO;EACT;CACF;AACF;;;ACaA,SAAgB,oBACd,QAC6E;CAC7E,OAAO,OAAO,UAAW,UAAU,UAAU,OAAO,SAAS;AAC/D;AAEA,SAAgB,kBAAkB,QAA4B;CAC5D,IAAI,OAAO,QAAQ,OAAO,OAAO,EAAE;CACnC,IAAI,OAAO,QAAQ,OAAO,OAAO,EAAE;CACnC,OAAO,OAAO,SAAS,aAAa,OAAO,WAAW,OAAO;AAC/D;;;;;;;;ACnCA,IAAa,qBAAb,cACUA,YAEV;CACE;CACA;CAEA,YAAY,QAAmE;EAC7E,MAAM;EACN,IAAI,wBAAwB,QAAQ;GAClC,KAAKC,QAAQ,OAAO;GACpB,KAAKC,oBAAoB,OAAO,mBAAmB;EACrD,OAAO;GACL,KAAKD,QAAQ;GACb,KAAKC,cAAc,KAAA;EACrB;CACF;CAEA,MAAM,MAAM;EACV,MAAM,UAAU,KAAKA,cAAc;EACnC,IAAI,WAAW,OAAO,GAAG,MAAM;EAC/B,OAAO,KAAKD,MAAM,SAAS;CAC7B;CAEA,MAAM,UACJ,UACA,SACA;EACA,MAAM,UAAU,KAAKC,cAAc;EACnC,IAAI,WAAW,OAAO,GAAG,MAAM;EAC/B,OAAO,IAAI,+BAA+B,KAAKD,MAAM,UAAU,UAAU,OAAO,CAAC;CACnF;AACF;;;;;;;AAQA,IAAa,iCAAb,cACUD,YAEV;CACE;CAEA,YAAY,cAAqC;EAC/C,MAAM;EACN,KAAKG,gBAAgB;CACvB;CAEA,OAAO;EACL,OAAO,KAAKA,cAAc,KAAK;CACjC;CAEA,cAAc;EACZ,KAAKA,cAAc,YAAY;CACjC;CAEA,CAAC,OAAO,WAAW;EACjB,KAAKA,cAAc,YAAY;CACjC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AE3CA,eAAsB,SAAS,SAAkB,SAA6C;CAC5F,MAAM,EAAE,MAAM,YAAY,QAAQ;CAClC,MAAM,QAAQ,CAAC,GAAG,IAAI,IAAI,QAAQ,KAAK,UAAU,MAAM,MAAM,KAAK,CAAC,CAAC,CAAC,EAAG,CAAC,CAAC;CAE1E,MAAM,OAAO,IAAI,cAAc,IAAI,iBADpB,mBAAmB,QAAQ,QAAQ,MAAM;EAAE;EAAM,SAAS;CAAM,CAAC,GAAG,OAC1B,CAAC,CAAC;CAC3D,IAAI,QAAQ,WAAW,QAAQ,OAAO,OAAA,GAAA,gBAAA,wBAAA,CAA8B,SAAS,IAAI;CACjF,IAAI,QAAQ,QAAQ,IAAI,SAAS,CAAC,EAAE,YAAY,MAAM,aACpD,OAAO,IAAI,SAAS,8DAA8D,EAChF,QAAQ,IACV,CAAC;CAEH,QAAA,GAAA,gBAAA,+BAAA,CAAsC,SAAS,IAAI;AACrD;;;;;;AAWA,SAAgB,mBAAmB,QAAiB,SAAuC;CACzF,OAAO,UAAU,QAAQ,CAAC,GAAG,YAAY,OAAO,CAAC;AACnD;AAEA,MAAM,OAAO,OAAO,eAAe;;AAInC,SAAS,YAAY,SAAyC;CAC5D,MAAM,OAAoB,CAAC;CAC3B,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,WAAW,MAAM,MAAM,GAAG;EAChC,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,MACR,wCAAwC,MAAM,sDAAsD,MAAM,aAC5G;EAEF,IAAI,OAAO;EACX,KAAK,MAAM,CAAC,OAAO,YAAY,SAAS,QAAQ,GAAG;GACjD,MAAM,OAAO,UAAU,SAAS,SAAS;GACzC,MAAM,WAAW,KAAK;GACtB,IAAI,MAAM;IACR,IAAI,aAAa,KAAA,KAAa,aAAa,MACzC,MAAM,IAAI,MAAM,cAAc,MAAM,+CAA+C;IAErF,KAAK,WAAW;GAClB,OAAO;IACL,IAAI,aAAa,MACf,MAAM,IAAI,MAAM,cAAc,MAAM,+CAA+C;IAErF,OAAO,aAAa,KAAK,WAAW,CAAC;GACvC;EACF;CACF;CACA,OAAO;AACT;;;;;;;;;AAUA,SAAS,UAAU,MAAe,MAAgB,MAA8B;CAC9E,MAAM,mBAAmBC,gBAAAA,UAAU,CAAC;CACpC,KAAK,MAAM,CAAC,QAAQ,UAAU,OAAO,QAAQ,IAAI,GAC/C,OAAO,eACL,WAAW,WACX,QACA,UAAU,OACN;EACE,cAAc;EACd,QAAQ,GAAG,SAAoB,QAAQ,MAAM,CAAC,GAAG,MAAM,MAAM,GAAG,IAAI;EACpE,UAAU;CACZ,IACA;EAAE,cAAc;EAAM,WAAW,UAAU,MAAM,CAAC,GAAG,MAAM,MAAM,GAAG,KAAK;CAAE,CACjF;CAEF,OAAO,eAAe,WAAW,WAAW,cAAc;EACxD,cAAc;EACd,aAAa,QAAQ,MAAM,CAAC,GAAG,MAAM,YAAY,GAAG,CAAC,CAAC;EACtD,UAAU;CACZ,CAAC;CACD,OAAO,IAAI,WAAW;AACxB;;;;;;;AAQA,eAAe,QAAQ,MAAe,MAAgB,MAAmC;CACvF,IAAI,SAAS;CACb,KAAK,MAAM,WAAW,KAAK,MAAM,GAAG,EAAE,GACpC,SAAS,OAAO;CAGlB,OAAO,YAAY,MAAMC,OAAS,KAAK,GAAG,EAAE,EAAG,CAAE,GAAG,KAAK,KAAK,QAAQ,cAAc,GAAG,CAAC,CAAC,CAAC;AAC5F;;;;;;AAOA,SAAS,cAAc,OAAyB;CAC9C,IAAI,OAAO,UAAU,YAAY;EAK/B,MAAM,OAAO;EACb,MAAM,WAAY,OAAO,KAAK,QAAQ,aAAa,KAAK,IAAI,IAAI;EAGhE,QAAQ,GAAG,iBAA4B,SAAS,GAAG,YAAY;CACjE;CACA,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAQ,MAAoB,KAAK,UAAU,cAAc,KAAK,CAAC;CACzF,IAAI,cAAc,KAAK,GAAG;EACxB,MAAM,UAAmC,CAAC;EAC1C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,GAAG,QAAQ,OAAO,cAAc,KAAK;EACpF,OAAO;CACT;CACA,OAAO;AACT;;AAGA,SAAS,YAAY,OAAyB;CAC5C,OAAO,iBAAiB,KAAK,IAAI,IAAI,YAAY,KAAK,IAAI;AAC5D;;;;;;;;AASA,SAAS,iBAAiB,OAAqC;CAC7D,QACG,OAAO,UAAU,cAAe,OAAO,UAAU,YAAY,UAAU,SACxE,CAAC,MAAM,QAAQ,KAAK,KACpB,CAAC,cAAc,KAAK,KACpB,OAAQ,MAA8B,OAAO,aAAa;AAE9D;AAEA,SAAS,cAAc,OAAkD;CACvE,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO;CACxD,MAAM,YAAY,OAAO,eAAe,KAAK;CAC7C,OAAO,cAAc,OAAO,aAAa,cAAc;AACzD;;AAGA,MAAM,kBAAuC,IAAI,IAAI;CACnD;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;AAQD,IAAM,cAAN,cAA0BD,gBAAAA,UAAU;CAClC;CACA,YAAY,MAAkB;EAC5B,MAAM;EACN,KAAKE,QAAQ;CACf;CACA,OAAO,OAAO,SAAkC;EAC9C,OAAO,QAAQA;CACjB;AACF;AACA,OAAO,eACL,YAAY,WACZ,IAAI,MAAM,OAAO,OAAOF,gBAAAA,UAAU,SAAS,GAAa,EACtD,IAAI,WAAW,KAAK,UAAU;CAC5B,IAAI,OAAO,QAAQ,YAAY,OAAO,aAAa,gBAAgB,IAAI,GAAG,GACxE,OAAO,QAAQ,IAAI,WAAW,KAAK,QAAQ;CAE7C,IAAI,EAAE,oBAAoB,cAAc,OAAO,KAAA;CAC/C,QAAQ,GAAG,SAAoB,QAAQ,YAAY,OAAO,QAAQ,GAAG,CAAC,GAAG,GAAG,IAAI;AAClF,EACF,CAAC,CACH;AAMA,IAAM,oBAAN,cAAgCA,gBAAAA,UAAU;CACxC;CAEA,YAAY,SAAoB;EAC9B,MAAM;EACN,KAAKG,WAAW;CAClB;;CAGA,IAAI,OAA0B;EAC5B,OAAO,KAAKA;CACd;AACF;AAEA,IAAM,mBAAN,cAA+BH,gBAAAA,UAAU;CACvC;CAEA,YAAY,SAAoB;EAC9B,MAAM;EACN,KAAKI,YAAY,IAAI,kBAAkB,OAAO;CAChD;CAEA,IAAI,WAA8B;EAChC,OAAO,KAAKA;CACd;;CAGA,MAAM,aAAa;EACjB,OAAO;GACL,cAAc;GACd,UAAU,EAAE,UAAU,+BAA+B;EACvD;CACF;AACF;AAEA,IAAM,gBAAN,cAA4BJ,gBAAAA,UAAU;CACpC;CAEA,YAAY,SAA2B;EACrC,MAAM;EACN,KAAKK,WAAW;CAClB;;CAGA,aAAa,cAAoD;EAC/D,OAAO,KAAKA;CACd;AACF;;;;;;;;;;;;;;;;;;;;;;;AC1OA,eAAe,mBACb,KACA,KACA,KACA,MACmB;CACnB,MAAM,UAAU,IAAI,QAAQ,IAAI,OAAO;CACvC,QAAQ,IACN,6BACA,KAAK,UAAU;EAAE,eAAe,MAAM,iBAAiB;EAAQ;CAAI,CAAC,CACtE;CACA,OAAO,MAAM,IAAI,IAAI,MAAM,IAAI,QAAQ,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC1D;;;;;;;;;AAUA,eAAe,iBACb,UACA,EAAE,OAAO,CAAC,GAAG,QACK;CAClB,KAAK,MAAM,WAAW,KAAK,MAAM,GAAG,EAAE,GACpC,WAAW,MAAM,QAAQ,IAAI,OAAO,QAAQ,GAAG,OAAO;CAExD,MAAM,SAAS,KAAK,GAAG,EAAE;CACzB,MAAM,UAAU,QAAQ,IAAI,OAAO,QAAQ,GAAG,MAAM;CACpD,IAAI,OAAO,YAAY,YACrB,MAAM,IAAI,MAAM,IAAI,KAAK,KAAK,GAAG,EAAE,iCAAiC;CAEtE,OAAO,MAAM,QAAQ,MAAM,SAAS,UAAU,IAAI;AACpD;;;AAIA,SAAS,YAAY,MAAqB;CACxC,IAAI;EACF,KAA8B,OAAO,QAAQ,GAAG;CAClD,QAAQ,CAAC;AACX;;;;AAKA,eAAe,YAAe,KAAiB,IAAkD;CAC/F,MAAM,UAAU,MAAM,IAAI,IAAI,IAAI;CAClC,IAAI;EACF,OAAO,MAAM,GAAG,OAAO;CACzB,UAAU;EACR,YAAY,OAAO;CACrB;AACF;;;;;;AAOA,SAAS,qBAAwB,QAAc;CAC7C,IAAI,WAAW,QAAS,OAAO,WAAW,YAAY,OAAO,WAAW,YACtE,OAAO;CAMT,MAAM,WAAW,MAAM,QAAQ,MAAM,IAAI,CAAC,GAAG,MAAM,IAAI,EAAE,GAAG,OAAO;CACnE,QAAQ,eAAe,UAAU,OAAO,OAAO;CAC/C,IAAI;EACF,MAAM,UAAU,QAAQ,IAAI,QAAQ,OAAO,OAAO;EAClD,IAAI,OAAO,YAAY,YAAY,QAAQ,MAAM,SAAS,QAAQ,CAAC,CAAC;CACtE,SAAS,OAAO;EAGd,QAAQ,KAAK,uEAAuE,EAAE,MAAM,CAAC;CAC/F;CACA,OAAO;AACT;;;;;;;AAQA,SAAS,QAA0B,QAAW,WAA4C;CACxF,OAAO,IAAI,MAAM,QAAQ,EACvB,IAAI,QAAQ,MAAM;EAGhB,IAAI,OAAO,OAAO,WAAW,IAAI,GAAG,OAAO,UAAU;EACrD,MAAM,QAAQ,QAAQ,IAAI,QAAQ,MAAM,MAAM;EAC9C,OAAO,OAAO,UAAU,aAAa,MAAM,KAAK,MAAM,IAAI;CAC5D,EACF,CAAC;AACH;;;;;;;;;;AAWA,SAAgB,iBAAiB,KAAiB,MAA+B;CAC/E,MAAM,cAAiB,OACrB,YAAY,MAAM,YAAY,GAAG,QAAQ,OAAO,CAAC,CAAC,CAAC,KAAK,oBAAoB;CAC9E,OAAO;EACL,SAAS,GAAG,WAAW,YAAY,YAAY,QAAQ,IAAI,IAAI,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC;EAClF,mBAAmB,SAAS,YAAY,YAAY,QAAQ,IAAI,IAAI,CAAC,CAAC,iBAAiB,IAAI,CAAC;EAC5F,WAAW,SAAS,YAAY,YAAY,QAAQ,IAAI,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC;EAC5E,YAAY,SAAS,YAAY,YAAY,QAAQ,IAAI,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC;EAC9E,eAAe,SAAS,YAAY,YAAY,QAAQ,IAAI,IAAI,CAAC,CAAC,aAAa,IAAI,CAAC;EACpF,aAAa,SAA+B;GAC1C,IAAI;GACJ,IAAI,SAAS;GACb,OAAO;IACL,MAAM,YAAY;KAChB,IAAI,QAAQ,OAAO,CAAC;KACpB,WAAW,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,aAAa;MAC1C,OAAO,QAAQ,QAAQ,IAAI,IAAI,CAAC,CAAC,WAAW,IAAI;MAChD;KACF,EAAE;KACF,MAAM,EAAE,UAAU,MAAM;KACxB,OAAO,qBAAqB,MAAM,MAAM,KAAK,CAAC;IAChD;IACA,CAAC,OAAO,WAAW;KACjB,SAAS;KACT,QACI,MAAM,EAAE,OAAO,cAAc;MAC7B,YAAY,KAAK;MACjB,YAAY,OAAO;KACrB,CAAC,CAAC,CACD,YAAY,CAAC,CAAC;IACnB;GACF;EACF;EACA,KAAK,gBAAgB,iBAAiB,KAAK,WAAW;CACxD;AACF;;;AAIA,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;AA0B7B,SAAS,eAAiD,KAAY,KAAwB;CAC5F,MAAM,YAAe,OAAoE;EACvF,MAAM,MAAM,IAAI,QAAQ,GAAG,IAA8B,oBAAoB;EAC7E,IAAI,QAAQ,KAAA,GAIV,MAAM,IAAI,MACR,0HAEF;EAEF,OAAO,YAAY,MAAM,YAAY,GAAG,QAAQ,QAAQ,IAAI,GAAG,CAAC,CAAC;CACnE;CACA,OAAO,QAAQ,KAAK,EAClB,SAAS,QAAQ,IAAI,SAAS;EAC5B,WAAW,kBACT,UAAU,WACR,OAAO,SACL,OAAO,kBAAkB,WAAW,gBAAgB,cAAc,QAAQ,CAC5E,CACF;EACF,mBAAmB,UAAU,WAAW,OAAO,SAAS,IAAI,CAAC;EAC7D,gBAAgB,UAAU,WAAW,OAAO,SAAS,CAAC;CACxD,CAAC,EACH,CAAC;AACH;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,IAAa,0BAAb,cAEU,iBAAsB;CAC9B;CAEA,YAAY,KAA6D,KAAU;EACjF,MAAM,KAAK,GAAG;EACd,KAAK,MAAM;CACb;;;;;;;;;;;;CAaA,IAAc,MAAwB;EACpC,OAAQ,KAAKC,SAAS,KAAK,IAAI,IAAI,IAAI;CACzC;;;;;;CAOA,MAAgB,iBACd,SACA,QAC0B;EAC1B,IAAI,QAAQ,WAAW,UAAU,IAAI,IAAI,QAAQ,GAAG,CAAC,CAAC,aAAa,2BACjE,OAAO,MAAM,KAAK,IAAI,KAAK,IAAI,MAAM,CAAC,CAAC,MAAM,OAAO;EAGtD,MAAM,cAAc,IAAI,QAAQ,QAAQ,KAAK;GAC3C,SAAS,QAAQ;GACjB,QAAQ,QAAQ;EAClB,CAAC;EACD,OAAO,MAAM,KAAK,IAAI,KAAK,IAAI,MAAM,CAAC,CAAC,MAAM,WAAW;CAC1D;;;;CAKA,MAAgB,mBACd,KACA,KACA,MACmB;EACnB,OAAO,MAAM,mBAAmB,KAAK,KAAK,KAAK,KAAK,IAAI;CAC1D;;;;CAKA,MAAM,kBAAkB,OAA2C;EACjE,KAAK,MAAM,SAAS,MAAM,QAAQ,MAAM,KAAK,aAAa,KAAK;CACjE;;;CAIA,MAAgB,aAAa,QAAoC,CAAC;;;CAIlE,MAAM,iBAAiB,OAA+D;EACpF,OAAO,MAAM,iBAAiB,MAAM,KAAK;CAC3C;AACF;;;;;;;;;;;AAYA,IAAa,uBAAb,cAA+E,cAAmB;CAChG,YAAY,KAA0D,KAAU;EAC9E,MAAM,KAAK,GAAG;EACd,KAAK,MAAM;EAGX,KAAK,MAAM,eAAe,KAAK,KAAK,KAAK,GAAG;CAC9C;;;;;;;;;CAUA,eAAe,KAAqC;EAClD,KAAK,IAAI,QAAQ,GAAG,IAAI,sBAAsB,GAAG;CACnD;;;CAIA,MAAgB,mBACd,KACA,KACA,MACmB;EACnB,OAAO,MAAM,mBAAmB,KAAK,KAAK,KAAK,KAAK,IAAI;CAC1D;;;CAIA,MAAM,kBAAkB,OAA2C;EACjE,KAAK,MAAM,SAAS,MAAM,QAAQ,MAAM,KAAK,aAAa,KAAK;CACjE;;;CAIA,MAAgB,aAAa,QAAoC,CAAC;;;CAIlE,MAAM,iBAAiB,OAA+D;EACpF,OAAO,MAAM,iBAAiB,MAAM,KAAK;CAC3C;AACF;AAKA,MAAM,sBAAsB;AAC5B,MAAM,uBAAuB;;;;;;;;;;;;AAkB7B,IAAM,sBAAN,cAAkC,UAAU;CAC1C;CACA;CAEA,YACE,aACA,OACA;EACA,MAAM;EACN,KAAKC,eAAe;EACpB,KAAKC,SAAS;CAChB;CAEA,MAAM,oBACJ,SACsC;EACtC,IAAI,QAAQ,OAAO,cAAc,MAC/B,MAAM,IAAI,MAAM,kDAAkD;EAIpE,OAAO,MAAM,KAAKD,aAChB,QAAQ,OAAO,WACf,QAAQ,OAAO,IACjB,CAAC,CAAC,oBAAoB,OAAO;CAC/B;;;CAIA,MAAM,WAA+C;EACnD,MAAM,QAAQ,MAAM,KAAKC,OAAO;EAChC,MAAM,MAAM,QAAQ;EACpB,OAAO,MAAM,MAAM,SAAS;CAC9B;CAEA,MAAM,kBAA0D;EAC9D,OAAO,OAAO,MAAM,KAAKA,OAAO,EAAA,CAAG,gBAAgB;CACrD;;;CAIA,MAAM,mBAAmB,OAA8D;EACrF,OAAO,MAAM,KAAKA,OAAO,EAAA,CAAG,eAAe,KAAK;CAClD;AACF;;;;;;;;;;;;AAwCA,SAAgB,oBAAoE,MAO3D;CACvB,IAAI;CAIJ,MAAM,UAAU,WAAmB,SAAiB;EAClD,IAAI,UAAU,KAAA,GAAW;GACvB,KAAK,IAAI,QAAQ,GAAG,IAAI,qBAAqB,SAAS;GACtD,KAAK,IAAI,QAAQ,GAAG,IAAI,sBAAsB,IAAI;GAClD,MAAM,SAAS,iBAAiB,KAAK,KAAK,IAAI;GAC9C,MAAM,WAAW,8BAAqC,KAAK,KAAK;IAC9D;IACA;IACA;IACA,SAAS,KAAK,IAAI;GACpB,CAAC;GACD,MAAM,YAAY,SAAS,SACzB,KAAK,gBAAgB;IAAE;IAAM;IAAW;GAAO,CAAC,GAChD,KAAK,aAAa,KAAA,IAAY,KAAA,IAAY,EAAE,UAAU,KAAK,SAAS,CACtE;GACA,QAAQ;IAIN,OAAO,SAAS,MAAM,SAAS;IAC/B;GACF;EACF;EACA,OAAO;CACT;CAEA,MAAM,mBAAmB,YAAY;EACnC,IAAI,UAAU,KAAA,GAAW,OAAO;EAChC,MAAM,OAAO,KAAK,QAAQ,KAAK,IAAI,QAAQ,GAAG,IAAY,oBAAoB;EAC9E,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,MAAM,mEAAmE;EAKrF,OAAO,OAFL,KAAK,IAAI,QAAQ,GAAG,IAAY,mBAAmB,KAClD,MAAM,YAAY,KAAK,KAAK,OAAO,YAAY,MAAM,QAAQ,SAAS,GAChD,IAAI;CAC/B;CAEA,OAAO;EACL,UAAU,aAAa,MAAM,iBAAiB,EAAA,CAAG;EACjD,UAAU,YAAY,OAAO,MAAM,iBAAiB,EAAA,CAAG,MAAM,SAAS;EACtE,eAAe,IAAI,qBAChB,WAAW,SAAS,OAAO,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,UAC1D,aAAa,MAAM,iBAAiB,EAAA,CAAG,KACzC;EACA,MAAM,YAAY,WAAiC;GACjD,MAAM,YAAY,KAAK,IAAI,QAAQ,GAAG,IAAY,mBAAmB;GACrE,MAAM,OAAO,KAAK,QAAQ,KAAK,IAAI,QAAQ,GAAG,IAAY,oBAAoB;GAC9E,IAAI,cAAc,KAAA,KAAa,SAAS,KAAA,GAAW;GACnD,MAAM,OAAO,WAAW,IAAI,CAAC,CAAC,SAAS,YAAY,SAAS;EAC9D;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAsB,+BAAtB,cAGU,qBAA0B;;;;;;CAclC;;;;;CAMA,WAAuC;;;;;;;;;CAUvC;CACA,IAAIC,QAA8B;EAChC,OAAQ,KAAKC,cAAc,oBAA2B;GACpD,KAAK,KAAK;GACV,KAAK,KAAK;GACV,MAAM,KAAK;GACX,UAAU,KAAK;GACf,kBAAkB,SAAS,KAAK,gBAAgB,IAAI;EACtD,CAAC;CACH;;;;;;;;CASA,IAAI,YAAY;EACd,OAAO,KAAKD,MAAM;CACpB;;CAGA,MAAM,MAAM,WAAgD;EAC1D,MAAM,KAAKA,MAAM,YAAY,SAAS;CACxC;;;;;CAMA,WAAwD;EACtD,OAAO,KAAKA,MAAM,SAAS;CAC7B;;;;;CAMA,WAA8D;EAC5D,OAAO,KAAKA,MAAM,SAAS;CAC7B;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAsB,uBAAtB,cAEU,eAAoB;;;;;CAa5B,WAAuC;;;;;;;CAQvC,aAAuB,UAA4D;EACjF,MAAM,MAAM,KAAK;EACjB,MAAM,EAAE,SAAS;EACjB,OAAO;GACL,gBAAgB,oBACd,YAAY,MAAM,YAAY,QAAQ,QAAQ,IAAI,IAAI,CAAC,CAAC,cAAc,eAAe,CAAC;GACxF,wBACE,YAAY,MAAM,YAAY,QAAQ,QAAQ,IAAI,IAAI,CAAC,CAAC,iBAAiB,CAAC;GAC5E,qBAAqB,YAAY,MAAM,YAAY,QAAQ,QAAQ,IAAI,IAAI,CAAC,CAAC,cAAc,CAAC;EAC9F;CACF;;;;;;CAOA,WAAqB,UAAsD;EACzE,IAAI,SAAS,cAAc,MACzB,MAAM,IAAI,MAAM,4DAA4D;EAE9E,MAAM,EAAE,WAAW,SAAS;EAC5B,MAAM,SAAS,iBAAiB,KAAK,KAAK,IAAI;EAC9C,OAAO;GACL;GACA,SAAS,KAAK,IAAI;GAClB,qBAAqB,aAAa;IAChC,SAAS,SAAS,KAAK,gBAAgB;KAAE;KAAM;KAAW;IAAO,CAAC,GAAG,EACnE,UAAU,KAAK,SACjB,CAAC;GACH;EACF;CACF;AACF"}

package/dist/sdk.d.ts

@@ -0,0 +1,339 @@
+import { DurableObject, RpcTarget, WorkerEntrypoint } from "cloudflare:workers";
+import type { DynamicWorkerRef, ItxBinding, ProjectAuthPolicy, StatefulDynamicWorkerRef, StreamEvent } from "./itx-api.generated.ts";
+import type { ProcessorStream } from "./processors/stream-handle.ts";
+import type { ProcessorRuntimeState, ProcessorSnapshot, StreamDeliveryBatch, StreamProcessorWakeRequest, StreamProcessorWakeResponse } from "./processors/rpc-types.ts";
+import { ProcessorFacet, type ProcessorFacetAlarmProxy, type ProcessorFacetHost, type ProcessorFacetIdentity, type RegisterableProcessor, type RegisteredProcessorReads, type StreamProcessorRegistry } from "./processors/cloudflare.ts";
+export type * from "./itx-api.generated.ts";
+export { serveItx } from "./serve-itx.ts";
+/**
+ * What the platform supplies to every dynamic worker: the `ITX` binding
+ * (`get()` for capability method calls, `fetch()` for HTTP into sibling
+ * workers) and `ITERATE_WORKER_VERSION` — the content-addressed identity of
+ * what Worker Loader executes: modules and effective compatibility settings.
+ * Pass the latter as the `version` of a hosted processor registry: an
+ * executable change resets a crash-looping keepalive's backoff budget, while
+ * an unrelated source-repository revision does not.
+ */
+type IterateEnv = {
+    ITX: ItxBinding;
+    ITERATE_WORKER_VERSION: string;
+};
+type PipelinedProject = ReturnType<ItxBinding["get"]>;
+/**
+ * A {@link ProcessorStream} over the project stream at `path`, dialed through
+ * the platform ITX binding — the stream handle a worker-hosted stream
+ * processor registry needs (`iterate/processors`; see the config-repo
+ * template's guestbook for the full hosting shape). RPC stubs from
+ * `env.ITX.get()` must not outlive the invocation that dialed them, so every
+ * operation opens, uses, and disposes its own session; `readEvents` owns one
+ * session for its pager's lifetime (scope it with `using`, like any pager).
+ */
+export declare function itxProjectStream(env: IterateEnv, path: string): ProcessorStream;
+/**
+ * Base class for stateless dynamic workers — the project worker (a repo's
+ * default export) and stateless apps. A WorkerEntrypoint whose env carries
+ * the platform's itx binding, plus the platform ceremony every worker needs
+ * but shouldn't have to hand-roll:
+ *
+ * - `processEventBatch` / `processEvent`: the platform delivers every
+ *   committed DURABLE event on every stream in the project as checkpointed
+ *   per-stream batches — in per-stream order, at-least-once. Events appended
+ *   with `ephemeral: true` (LLM streaming chunks and other transient
+ *   signals) never arrive here. Session callbacks can receive one while its
+ *   body remains in the Stream Durable Object's bounded memory buffer; react
+ *   here to the durable fact that supersedes it (e.g. an assistant-role
+ *   `agents/context-added` item). The base unpacks batches
+ *   into one `processEvent(event)` call per event; override `processEvent` to react
+ *   (one `if` per reaction, keyed on event.path + event.type). Throwing (or a worker that fails to build) leaves that
+ *   stream's checkpoint in place and the whole batch is redelivered later,
+ *   so return normally to advance past events you don't care about — and
+ *   anything a reaction appends should carry an idempotency key.
+ * - `invokeCapability`: the flattened `itx.worker.<path>` dispatcher — add a
+ *   getter or method to your class and it becomes a capability surface.
+ * - `fetchDynamicWorker`: forward HTTP (WebSockets included) to another of
+ *   the project's dynamic workers.
+ */
+export declare class IterateWorkerEntrypoint<Env extends IterateEnv = IterateEnv> extends WorkerEntrypoint<Env> {
+    #private;
+    constructor(ctx: ConstructorParameters<typeof WorkerEntrypoint<Env>>[0], env: Env);
+    /**
+     * This invocation's project-root itx. Cloudflare constructs one
+     * WorkerEntrypoint per invocation and releases its RPC stubs when that
+     * execution context ends. The getter returns the native Workers RPC
+     * promise-proxy, so `await this.itx.agents.list()` pipelines immediately;
+     * repeated access within one event batch or fetch reuses the same handle.
+     *
+     * Durable Objects have a longer, multi-invocation lifetime and no eviction
+     * callback, so IterateDurableObject deliberately does not expose this
+     * memoized getter.
+     */
+    protected get itx(): PipelinedProject;
+    /**
+     * Run the project-member auth partial fetch without transferring the app's
+     * request body on paths auth only inspects. The callback POST belongs to
+     * auth, so that one path deliberately transfers the complete request.
+     */
+    protected fetchProjectAuth(request: Request, policy: ProjectAuthPolicy): Promise<Response | null>;
+    /** See `fetchDynamicWorker` at module level: a real fetch hop into a
+     * sibling dynamic worker — the only lane that can carry WebSocket upgrades
+     * and streaming bodies (RPC serializes; sockets can't cross it). */
+    protected fetchDynamicWorker(req: Request, ref: DynamicWorkerRef, opts?: {
+        buildBudgetMs?: number;
+    }): Promise<Response>;
+    /** Platform entry point for event delivery (see the class docstring for
+     * the delivery contract). Override `processEvent`, not this, unless you
+     * need whole-batch atomicity. */
+    processEventBatch(batch: StreamDeliveryBatch): Promise<void>;
+    /** Called once per delivered event, in per-stream order, at-least-once.
+     * Override to react; the default ignores everything. */
+    protected processEvent(_event: StreamEvent): Promise<void>;
+    /** Platform entry point for flattened `itx.worker.<path>` capability
+     * calls (see the class docstring). */
+    invokeCapability(input: {
+        args?: unknown[];
+        path: string[];
+    }): Promise<unknown>;
+}
+/**
+ * Base class for stateful dynamic workers (apps hosted as Durable Objects
+ * under a `durableWorkerKey`). Same platform surface as
+ * `IterateWorkerEntrypoint` — see its docstring for the event-delivery and
+ * capability-dispatch contracts — on a DurableObject, so state survives
+ * across requests and WebSockets can be served from `fetch`. Durable alarms
+ * work natively — `this.ctx.storage.setAlarm(...)` plus an `alarm()` method
+ * on the class — even though this object is hosted as a workerd facet with
+ * no alarms of its own; see {@link selfAlarmState} for the mechanism.
+ */
+export declare class IterateDurableObject<Env extends IterateEnv = IterateEnv> extends DurableObject<Env> {
+    constructor(ctx: ConstructorParameters<typeof DurableObject<Env>>[0], env: Env);
+    /**
+     * Platform bootstrap door: the Durable Object hosting this worker delivers
+     * the worker's OWN ref here before any other traffic in its incarnation —
+     * a facet has no channel to learn its identity by itself, and the ref is
+     * what the alarm shim dials (`itx.workers.get(ref)` resolves back to the
+     * hosting DO). Stashed durably, so a warm facet under a fresh host needs
+     * no re-delivery to keep working.
+     */
+    __stashSelfRef(ref: StatefulDynamicWorkerRef): void;
+    /** A real fetch hop into a sibling dynamic worker — see
+     * `IterateWorkerEntrypoint.fetchDynamicWorker`. */
+    protected fetchDynamicWorker(req: Request, ref: DynamicWorkerRef, opts?: {
+        buildBudgetMs?: number;
+    }): Promise<Response>;
+    /** Platform entry point for event delivery — see
+     * `IterateWorkerEntrypoint.processEventBatch`. */
+    processEventBatch(batch: StreamDeliveryBatch): Promise<void>;
+    /** Called once per delivered event — see
+     * `IterateWorkerEntrypoint.processEvent`. */
+    protected processEvent(_event: StreamEvent): Promise<void>;
+    /** Platform entry point for flattened `itx.worker.<path>` capability
+     * calls — see `IterateWorkerEntrypoint.invokeCapability`. */
+    invokeCapability(input: {
+        args?: unknown[];
+        path: string[];
+    }): Promise<unknown>;
+}
+type WakeRegistryLookup = (projectId: string, path: string) => Pick<StreamProcessorRegistry<object>, "wakeStreamProcessor">;
+/**
+ * The worker's `processor` node: the wake door the stream spine dials PLUS
+ * the public read verbs of the standard processor contract
+ * (`StreamProcessorRpc`). The reads serve the registered runner directly, so
+ * `streams.get(path).subscriptions.get(name).processor` and the stream's
+ * `waitUntilProcessed` barrier reach an expression-placed dynamic worker's
+ * processor with no extra wiring — the stream replays those verbs onto this
+ * node (the stored wake expression minus its trailing wake step). It crosses
+ * Workers RPC as a property read before its method is called, so it must be
+ * a real RpcTarget.
+ */
+declare class ProcessorWakeTarget extends RpcTarget {
+    #private;
+    constructor(registryFor: WakeRegistryLookup, reads: () => Promise<RegisteredProcessorReads<object>>);
+    wakeStreamProcessor(request: StreamProcessorWakeRequest): Promise<StreamProcessorWakeResponse>;
+    /** One consistent read of the committed fold, pulled through the durable
+     * stream tail first (read-your-writes, the hosting relays' catch-up leg). */
+    snapshot(): Promise<ProcessorSnapshot<object>>;
+    getRuntimeState(): Promise<ProcessorRuntimeState<object>>;
+    /** Offset barrier against the runner's committed fold. The runner's waiter
+     * self-pulls, so its timeout bounds the whole read-your-writes operation. */
+    waitUntilProcessed(input: {
+        offset: number;
+        timeoutMs?: number;
+    }): Promise<void>;
+}
+/**
+ * The platform deps the host derives and hands a processor factory: the home
+ * stream and its coordinates. Everything else a processor needs (clocks,
+ * clients, itx-backed capabilities) the factory wires off `this.env`.
+ */
+export type ProcessorHostDeps = {
+    path: string;
+    projectId: string;
+    stream: ProcessorStream;
+};
+export type ProcessorHost<State extends object> = {
+    /** The lazily built registry. Outside a wake request the coordinates come
+     * from the durable cache, the static `path`, or one project dial. */
+    registry(): Promise<StreamProcessorRegistry<State>>;
+    /** One consistent read of the hosted processor's committed fold. */
+    snapshot(): Promise<ProcessorSnapshot<State>>;
+    /** Assign to a `processor` getter — the wake door the stream spine dials,
+     * which also serves the standard read verbs (snapshot / getRuntimeState /
+     * waitUntilProcessed) so the subscriptions catalog and the stream barrier
+     * reach this processor. */
+    readonly wakeProcessor: ProcessorWakeTarget;
+    /** Route the Durable Object's `alarm()` here. Nothing cached means no
+     * registry ever armed one, so a stray fire is a no-op. */
+    handleAlarm(alarmInfo?: AlarmInvocationInfo): Promise<void>;
+};
+/**
+ * Host one stream processor in a Durable Object: the registry ceremony, the
+ * RPC-safe wake door, the alarm multiplex, and the durable coordinate cache
+ * in one place, so an app class is only its processor plus its own verbs.
+ *
+ * With `path` the host serves one fixed home stream (the guestbook shape).
+ * Without it the host learns its stream from the first wake request and
+ * caches the coordinates durably (one Durable Object per dynamic stream,
+ * keyed by the ref that names it). One host per Durable Object — the cache
+ * keys assume it.
+ */
+export declare function createProcessorHost<State extends object = Record<string, unknown>>(args: {
+    ctx: DurableObjectState;
+    env: IterateEnv;
+    path?: string;
+    /** Post-eviction keepalive recovery, for processors that owe registered work. */
+    recovery?: boolean;
+    createProcessor(deps: ProcessorHostDeps): RegisterableProcessor;
+}): ProcessorHost<State>;
+/**
+ * Ergonomic base for a Durable Object that hosts exactly one stream processor.
+ *
+ * It collapses the host boilerplate every processor app writes by hand today —
+ * a {@link createProcessorHost} field, an `alarm()` that forwards to it, and a
+ * `processor` getter exposing the wake door — down to a single
+ * {@link createProcessor} factory. First-party and userspace processors are
+ * authored the SAME way: all a subclass writes is how to build its processor
+ * from the host-derived platform deps (`{ stream, path, projectId }`) plus
+ * whatever it wires off `this.env`. That single seam is why a built-in
+ * processor forks into userspace with no change to the processor itself — only
+ * the dep wiring in `createProcessor` differs.
+ *
+ * Host-agnostic: the exact same class runs as its own Durable Object, as a
+ * facet of the Stream DO, or as a facet of another DO. Only the alarm adapter
+ * (native vs parent-proxied) and who dials the wake door differ per host, and
+ * the host owns both.
+ *
+ * ```ts
+ * export class GuestbookDurableObject extends StreamProcessorDurableObject<GuestbookState> {
+ *   protected readonly streamPath = guestbookStreamPath; // fixed home stream
+ *   protected createProcessor(deps: ProcessorHostDeps) {
+ *     return new GuestbookProcessor(deps);
+ *   }
+ *   // alarm(), the `processor` wake door, snapshot(), registry() — inherited.
+ * }
+ * ```
+ */
+export declare abstract class StreamProcessorDurableObject<State extends object = Record<string, unknown>, Env extends IterateEnv = IterateEnv> extends IterateDurableObject<Env> {
+    #private;
+    /**
+     * Build the processor from the host-derived platform deps. Wire your own deps
+     * (clocks, clients, itx-backed capabilities) off `this.env` here — this is
+     * the one method a processor app must implement, and the seam that keeps a
+     * built-in processor forkable into userspace unchanged.
+     */
+    protected abstract createProcessor(deps: ProcessorHostDeps): RegisterableProcessor;
+    /**
+     * A fixed home stream path (the guestbook shape). Leave undefined to learn
+     * the stream from the first wake request and cache the coordinates durably
+     * (one Durable Object per dynamic stream).
+     */
+    protected readonly streamPath?: string;
+    /**
+     * Post-eviction keepalive recovery, for processors that owe registered
+     * background work (the obligation pattern). Off by default.
+     */
+    protected readonly recovery: boolean;
+    /**
+     * The processor node the stream spine dials: the wake door plus the standard
+     * read verbs (`snapshot` / `getRuntimeState` / `waitUntilProcessed`), so the
+     * subscriptions catalog and the stream barrier reach this processor. It
+     * crosses Workers RPC as a property read before its method is called, so it
+     * must be a real RpcTarget — which the host guarantees.
+     */
+    get processor(): ProcessorWakeTarget;
+    /** Route the Durable Object's native `alarm()` into the host's multiplex. */
+    alarm(alarmInfo?: AlarmInvocationInfo): Promise<void>;
+    /**
+     * One consistent read of the hosted processor's committed fold, for a
+     * subclass's own read verbs (e.g. a `getState()`).
+     */
+    protected snapshot(): Promise<ProcessorSnapshot<State>>;
+    /**
+     * The lazily built registry, for subclasses that drive catch-up / live
+     * refresh directly (the guestbook's HTTP + append flow).
+     */
+    protected registry(): Promise<StreamProcessorRegistry<State>>;
+}
+/**
+ * Ergonomic base for a userspace stream processor hosted as a FACET of the
+ * platform's Stream Durable Object — the `facet-processor` subscription with a
+ * `userspace` source, whose `StatefulDynamicWorkerRef` names THIS class. The
+ * Stream DO loads the class from the project's source and starts it with
+ * `ctx.facets.get(name, …)`, so it runs INSIDE the stream it serves: wakes are
+ * an in-process parent→facet dial (no itx wake expression), and checkpoints /
+ * projections land in the facet's own private SQLite.
+ *
+ * Same authoring seam as {@link StreamProcessorDurableObject} — a subclass
+ * writes only `createProcessor` (and sets `recovery` when it owes background
+ * work) — so a processor forks between "its own Durable Object" and "a facet
+ * of its stream" with no change to the processor itself. The two differences a
+ * facet forces, both handled here:
+ *
+ * - **No native alarm.** workerd does not implement alarms for facets
+ *   (workerd#6810), so this base routes the registry's keepalive/recovery
+ *   alarm through the parent's real platform alarm over itx —
+ *   `streams.get(path).proxySetAlarm/proxyDeleteAlarm/proxyGetAlarm`, the
+ *   itx-channel twin of a stateful worker's `workers.get(ref).setAlarm`. The
+ *   parent fires it back as {@link ProcessorFacet.handleAlarm}. NEVER define
+ *   `alarm()` on a subclass (the base throws): a facet's native `setAlarm`
+ *   would appear to succeed, then poison its output gate.
+ * - **Identity by first-contact `configure`, not the constructor.** The Stream
+ *   DO delivers `{ parentName, projectId, path }`; the base stashes it and
+ *   rebuilds the host from that stash on every incarnation (see
+ *   {@link ProcessorFacet}).
+ *
+ * ```ts
+ * export class GuestbookFacet extends StreamProcessorFacet {
+ *   protected readonly recovery = true; // owes background work
+ *   protected createProcessor(deps: ProcessorHostDeps) {
+ *     return new GuestbookProcessor(deps);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class StreamProcessorFacet<Env extends IterateEnv = IterateEnv> extends ProcessorFacet<Env> {
+    /**
+     * Build the processor from the host-derived platform deps, wiring your own
+     * deps (clocks, clients, itx-backed capabilities) off `this.env` — the one
+     * method a facet-hosted processor app implements, identical to
+     * {@link StreamProcessorDurableObject.createProcessor}.
+     */
+    protected abstract createProcessor(deps: ProcessorHostDeps): RegisterableProcessor;
+    /**
+     * Post-eviction keepalive recovery, for processors that owe registered
+     * background work (the obligation pattern). Off by default.
+     */
+    protected readonly recovery: boolean;
+    /**
+     * Dial the parent stream's alarm proxy over itx, resolved PER CALL (a stub
+     * must not outlive its RPC turn), each verb opening and disposing its own
+     * session like {@link itxProjectStream}. `identity.path` is the coordinate;
+     * `parentName` is unused here (userspace facets have no `env.STREAM`).
+     */
+    protected parentAlarms(identity: ProcessorFacetIdentity): ProcessorFacetAlarmProxy;
+    /**
+     * Build the host wiring from the stashed identity: the stream handle is the
+     * same itx-backed {@link itxProjectStream} a worker-hosted processor appends
+     * through, and the single processor is registered under this facet's name.
+     */
+    protected createHost(identity: ProcessorFacetIdentity): ProcessorFacetHost;
+}

package/dist/sdk.mjs

@@ -0,0 +1,2 @@
+import { a as createProcessorHost, i as StreamProcessorFacet, n as IterateWorkerEntrypoint, o as itxProjectStream, r as StreamProcessorDurableObject, s as serveItx, t as IterateDurableObject } from "./sdk-DMB-IM11.mjs";
+export { IterateDurableObject, IterateWorkerEntrypoint, StreamProcessorDurableObject, StreamProcessorFacet, createProcessorHost, itxProjectStream, serveItx };

package/dist/serve-itx.d.ts

@@ -0,0 +1,46 @@
+import { RpcTarget } from "./sdk/capnweb/index.ts";
+import type { Project } from "./itx-api.generated.ts";
+export type ServeItxOptions = {
+    /** The worker's own itx (`this.itx`, `await env.ITX.get()`). Never reaches the browser. */
+    project: Project;
+    /**
+     * What the browser gets. `surface` lists the members served as DOTTED
+     * paths down to each METHOD: a leaf is called, so an object-valued member
+     * is listed through to its methods — `"agent.liveState.get"` and
+     * `"agent.liveState.subscribe"`, never `"agent.liveState"`. A bare root
+     * cannot be relayed because its members are unknown here.
+     */
+    scope: {
+        path: string;
+        surface: string[];
+    };
+};
+/**
+ * Answer an app's `/api` request with an itx session for one narrowed scope.
+ * Call it from `fetch` after deciding who the visitor is:
+ *
+ *   if (url.pathname === "/api") {
+ *     return await serveItx(request, {
+ *       project: await this.env.ITX.get(),
+ *       scope: {
+ *         path: `/agents/web/${visitorIdFrom(request)}`,
+ *         surface: [
+ *           "agent.message",
+ *           "agent.liveState.get",
+ *           "agent.liveState.subscribe",
+ *           "agent.stream.openConnection",
+ *         ],
+ *       },
+ *     });
+ *   }
+ *
+ * WebSocket upgrades carry the live session (stream connections, live
+ * state); `POST` answers the client's HTTP-batch transport.
+ */
+export declare function serveItx(request: Request, options: ServeItxOptions): Promise<Response>;
+/**
+ * The served project: the relay tree over a scoped stub for these dotted
+ * members. Exported for the relay's own tests; callers use `serveItx`.
+ * @internal
+ */
+export declare function relayServedProject(scoped: unknown, surface: readonly string[]): RpcTarget;

package/dist/starter-apps/flake-dashboard/app-ref.d.ts

@@ -0,0 +1,31 @@
+import type { StreamEventInput } from "../../processors/index.ts";
+export declare const flakesStreamPath = "/flakes";
+export declare const flakeDashboardWorkerRef: {
+    className: string;
+    durableWorkerKey: string;
+    path: string;
+    source: {
+        createWorker: {
+            entryPoint: string;
+            files: {
+                include: string[];
+                repoPath: string;
+                type: "repo";
+            };
+        };
+    };
+    type: "stateful";
+};
+/**
+ * The dashboard's birth certificate. Idempotency-keyed so every caller — the
+ * worker's lazy initialization AND the CI reporter script, whichever appends
+ * first — may offer it; the config values are immutable birth facts.
+ */
+export declare function flakeDashboardCreationEvents(config: {
+    repository: {
+        owner: string;
+        repo: string;
+    };
+    issueTitle: string;
+    defaultBranch: string;
+}): StreamEventInput[];