@ewhauser/world-celld 0.1.1 → 0.2.0

package/dist/worker.d.ts

@@ -1,4 +1,4 @@
-import { CreateEventRequest, Event, Hook, RunCreatedEventRequest, Step, ValidQueueName, WorkflowRun } from "@workflow/world";
+import { CreateEventRequest, Event, Hook, RunCreatedEventRequest, Step, TerminalWorkflowRunStatus, ValidQueueName, WorkflowRun } from "@workflow/world";
 //#region src/worker/router.d.ts
 /** Minimal structural DO namespace type (celld provides the real thing). */
 interface DONamespaceLike {
@@ -18,6 +18,71 @@ interface WorkerEnv {
 }
 declare function createRouter(env: WorkerEnv): (request: Request) => Promise<Response>;
 //#endregion
+//#region src/retention.d.ts
+type CleanupPhase = 'retained' | 'index' | 'streams' | 'queues' | 'payload' | 'tombstoned';
+interface CleanupRecord {
+  version: 1;
+  runId: string;
+  workflowName: string;
+  createdAt: Date;
+  completedAt: Date;
+  terminalStatus: TerminalWorkflowRunStatus;
+  dueAt: Date;
+  queueShards: number;
+  phase: CleanupPhase;
+  attempts: number;
+  lastError?: string;
+  lastAttemptAt?: Date;
+  tombstonedAt?: Date;
+  deletedPayloadKeys: number;
+  deletedStreams: number;
+  deletedQueueMessages: number;
+}
+interface RunTombstone {
+  version: 1;
+  runId: string;
+  terminalStatus: TerminalWorkflowRunStatus;
+  completedAt: Date;
+  expiredAt: Date;
+  tombstonedAt: Date;
+}
+type RunReadOutcome<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  code: 'RUN_EXPIRED';
+  message: string;
+  tombstone: RunTombstone;
+};
+interface HookIndexReference {
+  hookId: string;
+  token: string;
+}
+interface ExpireRunIndexesRequest {
+  runId: string;
+  keys: string[];
+  hooks: HookIndexReference[];
+  expiredAt: number;
+}
+interface ExpireRunIndexesResult {
+  deleted: number;
+}
+interface ExpireRunStreamsResult {
+  streams: string[];
+}
+interface ExpireStreamResult {
+  deleted: boolean;
+  chunks: number;
+}
+interface ExpireQueueRunResult {
+  deleted: number;
+}
+interface ScheduleCleanupRequest {
+  retentionMs: number;
+  queueShards: number;
+}
+//#endregion
 //#region src/apply-event.d.ts
 interface ApplyEventRequest {
   /** The effective run id (already resolved / generated by the caller). */
@@ -31,6 +96,8 @@ interface ApplyEventRequest {
     runId: string;
     hookId: string;
   } | null;
+  /** Internal world-celld retention policy captured with the event. */
+  cleanup?: ScheduleCleanupRequest;
 }
 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 {
@@ -79,6 +146,8 @@ interface EnqueueRequest {
   pathname: Pathname;
   /** `stringify(message)` — the exact bytes POSTed to the app on delivery. */
   body: string;
+  /** Owning workflow run; absent only for health-check messages. */
+  runId?: string;
   idempotencyKey?: string;
   delaySeconds?: number;
   /**
@@ -98,7 +167,7 @@ type EnqueueOutcome = {
   deduped: boolean;
 } | {
   ok: false;
-  code: 'CONFIG_MISMATCH';
+  code: 'CONFIG_MISMATCH' | 'RUN_EXPIRED';
   message: string;
 };
 //#endregion
@@ -141,6 +210,10 @@ declare class DurableObject<TEnv = unknown> {
 declare class IndexDO extends DurableObject {
   get(key: string): Promise<string | null>;
   put(key: string, value: string): Promise<void>;
+  /** Publish a derived index only while its owning run is not expired. */
+  putOwned(runId: string, key: string, value: string): Promise<{
+    stored: boolean;
+  }>;
   delete(key: string): Promise<void>;
   list(options?: {
     prefix?: string;
@@ -161,6 +234,12 @@ declare class IndexDO extends DurableObject {
   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>;
+  /**
+   * Fence a run and remove all of its known derived indexes atomically.
+   * Once the fence exists, putOwned() and hook finalization cannot resurrect
+   * entries from a delayed request.
+   */
+  expireRun(request: ExpireRunIndexesRequest): Promise<ExpireRunIndexesResult>;
 }
 //#endregion
 //#region src/worker/durable-objects/QueueDO.d.ts
@@ -179,6 +258,8 @@ declare class IndexDO extends DurableObject {
  *   inflight:<messageId>         crash-recovery deadline (epoch ms)
  *   key:<idempotencyKey>         active dedup claim -> messageId
  *   dlq:<paddedMs>:<messageId>   DeadLetterRow
+ *   run:<runId>:<messageId>      QueueRunReference for retention cleanup
+ *   expired-run:<runId>          run fence preventing delayed enqueue
  *
  * celld gotchas designed around:
  * - celld#144 (alarm handlers can overlap): the storage-only claim phase runs
@@ -196,6 +277,7 @@ interface MessageRow {
   pathname: 'flow' | 'step';
   /** Pre-encoded tagged-JSON payload — forwarded byte-identical. */
   body: string;
+  runId?: 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
@@ -245,6 +327,8 @@ declare class QueueDO extends DurableObject {
   rearmAlarm(): Promise<{
     alarmAt: number | null;
   }>;
+  /** Fence a run and purge every live, inflight, and dead-letter message it owns. */
+  expireRun(runId: string, expiredAt: number): Promise<ExpireQueueRunResult>;
 }
 //#endregion
 //#region src/worker/durable-objects/StreamDO.d.ts
@@ -260,16 +344,17 @@ declare class QueueDO extends DurableObject {
  */
 declare class StreamDO extends DurableObject {
   private getMeta;
+  private assertOwner;
   /**
    * Append a chunk. The index is allocated inside the transaction, so
    * concurrent writers can never collide or skip.
    */
-  writeChunk(data: Uint8Array): Promise<number>;
+  writeChunk(runId: string, data: Uint8Array): Promise<number>;
   /**
    * Close the stream (idempotent). Readers observe `done: true` once all
    * previously written chunks have been consumed.
    */
-  closeStream(): Promise<void>;
+  closeStream(runId: string): Promise<void>;
   /**
    * Read up to `limit` chunks starting at `startIndex` (0-based, inclusive).
    */
@@ -293,11 +378,17 @@ declare class StreamDO extends DurableObject {
   /**
    * Register a stream name against this per-run registry instance.
    */
-  registerStream(name: string): Promise<void>;
+  registerStream(runId: string, name: string): Promise<void>;
   /**
    * List stream names registered against this per-run registry instance.
    */
   listStreams(): Promise<string[]>;
+  /** Fence a run's registry before any stream cells are removed. */
+  expireRegistry(runId: string, expiredAt: number): Promise<ExpireRunStreamsResult>;
+  /** Remove the registry payload after every referenced stream was fenced. */
+  finalizeRegistry(runId: string): Promise<void>;
+  /** Delete stream payload while leaving a small ownership tombstone. */
+  expireStream(runId: string, expiredAt: number): Promise<ExpireStreamResult>;
 }
 //#endregion
 //#region src/worker/durable-objects/WorkflowRunDO.d.ts
@@ -313,87 +404,59 @@ declare class StreamDO extends DurableObject {
  */
 declare class WorkflowRunDO extends DurableObject {
   private schemaReady;
-  /**
-   * Lazily ensure schema migrations have run.
-   * Memoized so it only runs once per DO instantiation.
-   */
+  private now;
   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.
-   */
+  private expiredTombstone;
+  private read;
+  /** Apply an event and capture all retention metadata in the same transaction. */
   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).
-   */
+  getRun(): Promise<RunReadOutcome<WorkflowRun | null>>;
+  getStep(stepId: string): Promise<RunReadOutcome<Step | null>>;
   listSteps(params?: {
     limit?: number;
     cursor?: string;
     sortOrder?: 'asc' | 'desc';
-  }): Promise<{
+  }): Promise<RunReadOutcome<{
     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.
-   */
+  }>>;
+  getEvent(eventId: string): Promise<RunReadOutcome<Event | null>>;
   listEvents(params?: {
     limit?: number;
     cursor?: string;
     sortOrder?: 'asc' | 'desc';
-  }): Promise<{
+  }): Promise<RunReadOutcome<{
     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<{
+  }): Promise<RunReadOutcome<{
     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.
-   */
+  }>>;
+  getCleanupStatus(): Promise<CleanupRecord | null>;
+  /** Explicitly schedule an existing terminal run, used for opt-in backfills. */
+  scheduleCleanup(request: ScheduleCleanupRequest): Promise<CleanupRecord | null>;
+  cleanupNow(request: ScheduleCleanupRequest): Promise<CleanupRecord | null>;
+  rearmCleanup(): Promise<CleanupRecord | null>;
+  alarm(): Promise<void>;
+  private namespace;
+  private setCleanupPhase;
+  private executeCleanup;
+  private deletePayloadBatch;
+  private recordCleanupFailure;
   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

package/dist/worker.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"worker.d.ts","names":[],"sources":["../src/worker/router.ts","../src/retention.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":"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"}