@ewhauser/world-celld 0.1.0

package/dist/worker.d.ts

@@ -0,0 +1,406 @@
+import { CreateEventRequest, Event, Hook, RunCreatedEventRequest, Step, ValidQueueName, WorkflowRun } from "@workflow/world";
+//#region src/worker/router.d.ts
+/** Minimal structural DO namespace type (celld provides the real thing). */
+interface DONamespaceLike {
+  idFromName(name: string): {
+    toString(): string;
+  };
+  get(id: {
+    toString(): string;
+  }): unknown;
+}
+interface WorkerEnv {
+  WORKFLOW_DB: DONamespaceLike;
+  WORKFLOW_STREAMS: DONamespaceLike;
+  WORKFLOW_INDEX: DONamespaceLike;
+  WORKFLOW_QUEUE: DONamespaceLike;
+  WORLD_SECRET?: string;
+}
+declare function createRouter(env: WorkerEnv): (request: Request) => Promise<Response>;
+//#endregion
+//#region src/apply-event.d.ts
+interface ApplyEventRequest {
+  /** The effective run id (already resolved / generated by the caller). */
+  runId: string;
+  data: CreateEventRequest | RunCreatedEventRequest;
+  /**
+   * Current holder of the hook token per the global KV token index
+   * (hook_created only). `null` means the token is unclaimed.
+   */
+  tokenHolder?: {
+    runId: string;
+    hookId: string;
+  } | null;
+}
+type ApplyEventErrorCode = 'RUN_NOT_FOUND' | 'STEP_NOT_FOUND' | 'HOOK_NOT_FOUND' | 'ENTITY_CONFLICT' | 'RUN_EXPIRED' | 'TOO_EARLY' | 'RUN_NOT_SUPPORTED' | 'LEGACY_RUN_NOT_SUPPORTED';
+interface ApplyEventFailure {
+  ok: false;
+  code: ApplyEventErrorCode;
+  message: string;
+  /** Seconds until retry is allowed (TOO_EARLY only). */
+  retryAfterSeconds?: number;
+  /** The run's spec version (RUN_NOT_SUPPORTED only). */
+  runSpecVersion?: number;
+}
+interface ApplyEventSuccess {
+  ok: true;
+  /** Absent for idempotent replays that record no new event. */
+  event?: Event;
+  run?: WorkflowRun;
+  step?: Step;
+  hook?: Hook;
+  /** Hooks whose tokens must be released from the global KV index. */
+  releasedHooks: Array<{
+    hookId: string;
+    token: string;
+  }>;
+  /** Set when a run entity was created (run_created or resilient bootstrap). */
+  runCreated?: {
+    workflowName: string;
+    createdAt: Date;
+  };
+  /** Set when the global KV hook index must be (re)written. */
+  hookToIndex?: Hook;
+  /** All events (ascending), preloaded for run_started responses. */
+  events?: Event[];
+}
+type ApplyEventOutcome = ApplyEventSuccess | ApplyEventFailure;
+//#endregion
+//#region src/queue.d.ts
+type Pathname = 'flow' | 'step';
+/**
+ * Enqueue request accepted by a QueueDO cell. The message payload travels
+ * pre-encoded with the shared tagged-JSON codec (`body`), so the cell can
+ * forward it byte-identical to the app's queue handler without re-encoding.
+ */
+interface EnqueueRequest {
+  messageId: string;
+  queueName: ValidQueueName;
+  pathname: Pathname;
+  /** `stringify(message)` — the exact bytes POSTed to the app on delivery. */
+  body: string;
+  idempotencyKey?: string;
+  delaySeconds?: number;
+  /**
+   * Delivery configuration. The cell pins this from its first enqueue (the
+   * eve-ambient pattern); a later mismatch is rejected as CONFIG_MISMATCH.
+   */
+  config: QueueCellConfig;
+}
+interface QueueCellConfig {
+  /** Base URL of the app; deliveries POST to `${baseUrl}/.well-known/workflow/v1/{flow|step}`. */
+  targetBaseUrl: string;
+  queueShards: number;
+}
+type EnqueueOutcome = {
+  ok: true;
+  messageId: string;
+  deduped: boolean;
+} | {
+  ok: false;
+  code: 'CONFIG_MISMATCH';
+  message: string;
+};
+//#endregion
+//#region src/config.d.ts
+interface HookTokenOwner {
+  runId: string;
+  hookId: string;
+}
+//#endregion
+//#region src/worker/do-base.d.ts
+/**
+ * Durable Object base class — Node variant.
+ *
+ * The cell classes extend `DurableObject` so celld's JS RPC works on their
+ * stubs. This module is what Node builds (tests, the `./testing` in-process
+ * fleet) resolve; the worker build swaps it for do-base-workerd.ts, which
+ * re-exports the real `cloudflare:workers` base (see tsdown.config.ts).
+ * Behaviorally identical at this layer: the base only assigns ctx/env.
+ */
+declare class DurableObject<TEnv = unknown> {
+  readonly ctx: DurableObjectState;
+  readonly env: TEnv;
+  constructor(ctx: DurableObjectState, env: TEnv);
+}
+//#endregion
+//#region src/worker/durable-objects/IndexDO.d.ts
+/**
+ * Global index cell, replacing the Workers KV namespace world-cloudflare
+ * uses for run listing and hook token/id lookup.
+ *
+ * A single cell (named `index`) serializes every read and write. Hook-token
+ * reservation, publication, and release use storage transactions so
+ * concurrent runs cannot both acquire the same token.
+ *
+ * The RPC surface matches the storage-layer KVNamespace interface bit-for-bit
+ * (including MockKVNamespace's pagination contract: cursor = last returned
+ * key, `list_complete` reflects whether further keys exist), so the vendored
+ * storage.ts works against it unchanged.
+ */
+declare class IndexDO extends DurableObject {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+    reverse?: boolean;
+  }): Promise<{
+    keys: Array<{
+      name: string;
+    }>;
+    list_complete: boolean;
+    cursor?: string;
+  }>;
+  reserveHookToken(token: string, owner: HookTokenOwner): Promise<{
+    claimed: boolean;
+    holder?: HookTokenOwner;
+  }>;
+  finalizeHookIndexes(token: string, hookId: string, serializedHook: string, owner: HookTokenOwner): Promise<void>;
+  releaseHookToken(token: string, owner: HookTokenOwner): Promise<void>;
+  deleteHookIndexes(token: string, hookId: string, owner: HookTokenOwner): Promise<void>;
+}
+//#endregion
+//#region src/worker/durable-objects/QueueDO.d.ts
+/**
+ * Queue cell: the celld replacement for Cloudflare Queues.
+ *
+ * One cell (`q:<shard>`) owns the full lifecycle of its messages: durable
+ * scheduling via the cell alarm, delivery via outbound fetch (the same x-vqs
+ * dialect as the in-process test pump), retries with capped exponential
+ * backoff, idempotencyKey dedup, and a dead-letter table.
+ *
+ * Storage layout (KV-style, ordered scans via zero-padded epoch-ms keys):
+ *   cfg                          pinned QueueCellConfig (first-enqueue wins)
+ *   msg:<messageId>              MessageRow
+ *   due:<paddedMs>:<messageId>   schedule index -> messageId
+ *   inflight:<messageId>         crash-recovery deadline (epoch ms)
+ *   key:<idempotencyKey>         active dedup claim -> messageId
+ *   dlq:<paddedMs>:<messageId>   DeadLetterRow
+ *
+ * celld gotchas designed around:
+ * - celld#144 (alarm handlers can overlap): the storage-only claim phase runs
+ *   inside blockConcurrencyWhile; slow delivery I/O runs outside the gate via
+ *   waitUntil.
+ * - six-failure alarm abandonment: the alarm handler never throws for data
+ *   conditions — backoff reschedules the alarm instead. rearmAlarm() is the
+ *   recovery hatch, and every enqueue also re-arms.
+ * - deploys restart the fleet: in-flight deliveries die with the isolate; the
+ *   inflight-deadline sweep on the next alarm redelivers (at-least-once).
+ */
+interface MessageRow {
+  messageId: string;
+  queueName: string;
+  pathname: 'flow' | 'step';
+  /** Pre-encoded tagged-JSON payload — forwarded byte-identical. */
+  body: string;
+  /**
+   * Delivery target captured at enqueue time. Carried per message (not
+   * pinned on the cell) so an app redeploy at a new URL never bricks the
+   * queue: old messages deliver (or dead-letter) against their original
+   * target, new messages against the new one.
+   */
+  targetBaseUrl: string;
+  idempotencyKey?: string;
+  /** Completed delivery attempts. */
+  attempt: number;
+  enqueuedAt: number;
+  lastError?: string;
+}
+interface DeadLetterRow extends MessageRow {
+  failedAt: number;
+}
+interface QueueStats {
+  pending: number;
+  inflight: number;
+  deadLetters: number;
+  alarmAt: number | null;
+}
+declare class QueueDO extends DurableObject {
+  #private;
+  enqueue(request: EnqueueRequest): Promise<EnqueueOutcome>;
+  alarm(): Promise<void>;
+  stats(): Promise<QueueStats>;
+  listDeadLetters(params?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<{
+    data: DeadLetterRow[];
+    cursor: string | null;
+    hasMore: boolean;
+  }>;
+  /** Move a dead letter back to the live queue (attempt count reset). */
+  redriveDeadLetter(messageId: string): Promise<{
+    ok: boolean;
+  }>;
+  purgeDeadLetters(): Promise<{
+    purged: number;
+  }>;
+  /**
+   * Recovery hatch for celld's six-failure alarm abandonment: derive the due
+   * time again and arm it.
+   */
+  rearmAlarm(): Promise<{
+    alarmAt: number | null;
+  }>;
+}
+//#endregion
+//#region src/worker/durable-objects/StreamDO.d.ts
+/**
+ * Durable Object backing workflow streams.
+ *
+ * Two roles, selected by the DO name:
+ * - `stream:<name>`: chunk storage for a single stream. A monotonic
+ *   per-stream counter (maintained transactionally inside the DO) assigns
+ *   each chunk its index; one chunk per storage key.
+ * - `run-streams:<runId>`: registry of stream names owned by a run,
+ *   powering `listStreamsByRunId`.
+ */
+declare class StreamDO extends DurableObject {
+  private getMeta;
+  /**
+   * Append a chunk. The index is allocated inside the transaction, so
+   * concurrent writers can never collide or skip.
+   */
+  writeChunk(data: Uint8Array): Promise<number>;
+  /**
+   * Close the stream (idempotent). Readers observe `done: true` once all
+   * previously written chunks have been consumed.
+   */
+  closeStream(): Promise<void>;
+  /**
+   * Read up to `limit` chunks starting at `startIndex` (0-based, inclusive).
+   */
+  getChunks(params: {
+    startIndex: number;
+    limit: number;
+  }): Promise<{
+    chunks: Uint8Array[];
+    /** Whether the stream is closed. */
+    done: boolean;
+    /** Index of the last written chunk, -1 when empty. */
+    tailIndex: number;
+  }>;
+  /**
+   * Lightweight stream metadata: last chunk index and completion flag.
+   */
+  getInfo(): Promise<{
+    tailIndex: number;
+    done: boolean;
+  }>;
+  /**
+   * Register a stream name against this per-run registry instance.
+   */
+  registerStream(name: string): Promise<void>;
+  /**
+   * List stream names registered against this per-run registry instance.
+   */
+  listStreams(): Promise<string[]>;
+}
+//#endregion
+//#region src/worker/durable-objects/WorkflowRunDO.d.ts
+/**
+ * Durable Object for managing a single workflow run's state.
+ *
+ * All event-sourced writes go through {@link applyEvent} inside a single
+ * storage transaction: guard checks, the event append, and the entity
+ * mutation are atomic even if the DO is evicted mid-operation.
+ *
+ * Instances named `claim:<queueName>:<idempotencyKey>` are used purely as
+ * queue-message dedup claims (see claimInflight/releaseInflight).
+ */
+declare class WorkflowRunDO extends DurableObject {
+  private schemaReady;
+  /**
+   * Lazily ensure schema migrations have run.
+   * Memoized so it only runs once per DO instantiation.
+   */
+  private ensureSchema;
+  /**
+   * Apply an event: validate, guard, append the event and mutate the entity
+   * in ONE storage transaction. Guard failures are returned as structured
+   * outcomes (not thrown) because typed errors do not survive the RPC
+   * boundary with their `name` intact.
+   */
+  applyEvent(request: ApplyEventRequest): Promise<ApplyEventOutcome>;
+  /**
+   * Get the workflow run
+   */
+  getRun(): Promise<WorkflowRun | null>;
+  /**
+   * Get a specific step
+   */
+  getStep(stepId: string): Promise<Step | null>;
+  /**
+   * List steps with real limit/cursor pagination (cursor = last stepId).
+   */
+  listSteps(params?: {
+    limit?: number;
+    cursor?: string;
+    sortOrder?: 'asc' | 'desc';
+  }): Promise<{
+    data: Step[];
+    cursor: string | null;
+    hasMore: boolean;
+  }>;
+  /**
+   * Get a specific event
+   */
+  getEvent(eventId: string): Promise<Event | null>;
+  /**
+   * List events with real limit/cursor pagination. Events are keyed by their
+   * monotonic ULID eventId, so storage order == event order.
+   */
+  listEvents(params?: {
+    limit?: number;
+    cursor?: string;
+    sortOrder?: 'asc' | 'desc';
+  }): Promise<{
+    data: Event[];
+    cursor: string | null;
+    hasMore: boolean;
+  }>;
+  /**
+   * List hooks with real limit/cursor pagination (cursor = last hookId).
+   */
+  listHooks(params?: {
+    limit?: number;
+    cursor?: string;
+    sortOrder?: 'asc' | 'desc';
+  }): Promise<{
+    data: Hook[];
+    cursor: string | null;
+    hasMore: boolean;
+  }>;
+  /**
+   * Claim a queue-message dedup slot. Used on DO instances dedicated to a
+   * single idempotency key (`claim:<queueName>:<idempotencyKey>`).
+   *
+   * - Unclaimed -> claim and proceed.
+   * - Claimed by the SAME messageId -> redelivery of the same message
+   *   (previous attempt failed transiently) -> proceed.
+   * - Claimed by a DIFFERENT messageId -> concurrent duplicate -> reject,
+   *   unless the claim is stale (holder crashed / went to the DLQ without
+   *   releasing), in which case the claim is stolen.
+   */
+  claimInflight(params: {
+    messageId: string;
+    staleMs: number;
+  }): Promise<{
+    claimed: boolean;
+  }>;
+  /**
+   * Release a queue-message dedup claim after the message was fully handled.
+   */
+  releaseInflight(): Promise<void>;
+}
+//#endregion
+//#region src/worker/worker.d.ts
+declare const _default: {
+  fetch(request: Request, env: WorkerEnv): Promise<Response>;
+};
+//#endregion
+export { IndexDO, QueueDO, StreamDO, type WorkerEnv, WorkflowRunDO, createRouter, _default as default };
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","names":[],"sources":["../src/worker/router.ts","../src/apply-event.ts","../src/queue.ts","../src/config.ts","../src/worker/do-base.ts","../src/worker/durable-objects/IndexDO.ts","../src/worker/durable-objects/QueueDO.ts","../src/worker/durable-objects/StreamDO.ts","../src/worker/durable-objects/WorkflowRunDO.ts","../src/worker/worker.ts"],"mappings":";;;UAmBiB;EACf,WAAW;IAAiB;;EAC5B,IAAI;IAAM;;;UAGK;EACf,aAAa;EACb,kBAAkB;EAClB,gBAAgB;EAChB,gBAAgB;EAChB;;iBAmFc,aAAa,KAAK,aAClB,SAAS,YAAU,QAAQ;;;UC3B1B;;EAEf;EACA,MAAM,qBAAqB;;;;;EAK3B;IAAgB;IAAe;;;KAGrB;UAUK;EACf;EACA,MAAM;EACN;;EAEA;;EAEA;;UAGe;EACf;;EAEA,QAAQ;EACR,MAAM;EACN,OAAO;EACP,OAAO;;EAEP,eAAe;IAAQ;IAAgB;;;EAEvC;IAAe;IAAsB,WAAW;;;EAEhD,cAAc;;EAEd,SAAS;;KAGC,oBAAoB,oBAAoB;;;KC/E/C;;;;;;UAoBY;EACf;EACA,WAAW;EACX,UAAU;;EAEV;EACA;EACA;;;;;EAKA,QAAQ;;UAGO;;EAEf;EACA;;KAGU;EACN;EAAU;EAAmB;;EAC7B;EAAW;EAAyB;;;;UCtEzB;EACf;EACA;;;;;;;;;;;;;cCrBW,cAAc;WAEd,KAAK;WACL,KAAK;EADL,YAAA,KAAK,oBACL,KAAK;;;;;;;;;;;;;;;;;cCoBL,gBAAgB;EACrB,IAAI,cAAc;EAKlB,IAAI,aAAa,gBAAgB;EAIjC,OAAO,cAAc;EAIrB,KAAK;IACT;IACA;IACA;IACA;MACE;IACF,MAAM;MAAQ;;IACd;IACA;;EA2BI,iBACJ,eACA,OAAO,iBACN;IAAU;IAAkB,SAAS;;EAmBlC,oBACJ,eACA,gBACA,wBACA,OAAO,iBACN;EAmBG,iBAAiB,eAAe,OAAO,iBAAiB;EAUxD,kBAAkB,eAAe,gBAAgB,OAAO,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UC3GhE;EACf;EACA;EACA;;EAEA;;;;;;;EAOA;EACA;;EAEA;EACA;EACA;;UAGe,sBAAsB;EACrC;;UAGe;EACf;EACA;EACA;EACA;;cAqCW,gBAAgB;;EAoBrB,QAAQ,SAAS,iBAAiB,QAAQ;EA2D1C,SAAS;EA8NT,SAAS,QAAQ;EAgBjB,gBAAgB;IACpB;IACA;MACE;IAAU,MAAM;IAAiB;IAAuB;;;EAkBtD,kBAAkB,oBAAoB;IAAU;;EAkChD,oBAAoB;IAAU;;;;;;EAe9B,cAAc;IAAU;;;;;;;;;;;;;;;cClcnB,iBAAiB;UACd;;;;;EASR,WAAW,MAAM,aAAa;;;;;EAiB9B,eAAe;;;;EAUf,UAAU;IAAU;IAAoB;MAAkB;IAC9D,QAAQ;;IAER;;IAEA;;;;;EAmBI,WAAW;IAAU;IAAmB;;;;;EAQxC,eAAe,eAAe;;;;EAO9B,eAAe;;;;;;;;;;;;;;cCeV,sBAAsB;UACzB;;;;;UAMA;;;;;;;EAaF,WAAW,SAAS,oBAAoB,QAAQ;;;;EAqBhD,UAAU,QAAQ;;;;EASlB,QAAQ,iBAAiB,QAAQ;;;;EASjC,UAAU;IACd;IACA;IACA;MACE;IAAU,MAAM;IAAQ;IAAuB;;;;;EAiB7C,SAAS,kBAAkB,QAAQ;;;;;EAUnC,WAAW;IACf;IACA;IACA;MACE;IAAU,MAAM;IAAS;IAAuB;;;;;EAiB9C,UAAU;IACd;IACA;IACA;MACE;IAAU,MAAM;IAAQ;IAAuB;;;;;;;;;;;;;EAyB7C,cAAc;IAClB;IACA;MACE;IAAU;;;;;EAoBR,mBAAmB;;;;;EChRJ,MAAA,SAAA,SAAO,KAAO,YAAY,QAAQ"}