@ewhauser/world-celld 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.6.0 (2026-09-16)
+
+## What's Changed
+* feat!: upgrade Workflow packages and require World spec v7 by @ewhauser in https://github.com/ewhauser/world-celld/pull/59
+
+
+**Full Changelog**: https://github.com/ewhauser/world-celld/compare/v0.5.0...v0.6.0
+
+## 0.5.0 (unreleased)
+
+### Breaking changes
+
+- Internal Queue delivery now requires the `QueueDeliveryRpc` named entrypoint.
+  Deploy matching consumer and primary worker scripts together; the former
+  `/v1/queue/deliver` route is removed with no fallback.
+
+- Require celld v0.5.0. Stop the entire old fleet before starting v0.5.0 nodes;
+  mixed-version fleets and older runtime compatibility are not supported.
+- Configure worker variables in deployment `vars`. Removed `CELLD_VAR_*` node
+  overrides are not supported; both scripts must deploy the same `WORLD_SECRET`.
+- Remove `CELLD_STORAGE_PROBE`, `CELLD_OUTPUT_GATE`, and `CELLD_OTEL_SINK` from
+  node environments. Use `CELLD_OTEL=1` for bucket telemetry or a collector base
+  URL for OTLP. Storage checks and durability gating are mandatory.
+
+### Improvements
+
+- Adopt the runtime's native Queue batching, alarm, storage, and recovery
+  improvements with the existing World retention and payload-storage design.
+- Document opt-in telemetry and development variables; verify persisted bucket
+  telemetry in the native runtime smoke.
+- Update runtime pins and verified downloads, and ship the
+  [upgrade guide](docs/celld-v0.5-upgrade.md) in the npm package.
+
 ## 0.4.1 (2026-08-24)
 
 ## What's Changed

package/NOTICE

@@ -12,7 +12,7 @@ vinnymac/worlds:
     src/apply-event.ts
     src/storage.ts
     src/streamer.ts
-    src/queue.ts               (modified: Cloudflare Queues replaced by QueueDO)
+    src/queue.ts               (modified: Cloudflare Queues adapted to celld Queues and R2)
     src/test-mocks.ts          (modified)
     src/util.ts
     src/worker/durable-objects/WorkflowRunDO.ts

package/README.md

@@ -4,18 +4,30 @@ A [Workflow DevKit](https://useworkflow.dev) `World` backed by
 [celld](https://github.com/denoland/celld).
 
 `world-celld` stores workflow runs, hooks, and streams in celld cells. Scheduled
-work is delivered with durable cell alarms. This gives Node applications a
+work is delivered through celld's native Queues, with run-bearing message bodies
+stored in the fleet's object store. This gives Node applications a
 self-hosted alternative to platform-specific Workflow backends.
 
 > [!WARNING]
 > `world-celld` is experimental and has not been proven in production. Its API
 > and storage layout may change before 1.0.
 
+## World protocol compatibility
+
+This adapter supports World spec v7 with the Workflow 5 beta packages. Event
+slots are allocated in the same transaction that stores each event, so reads
+see a dense log and failed writes leave no gaps. No background sealing or
+`noop` events are needed. Runs stamped with earlier spec versions are rejected
+when applying events; finish existing runs before upgrading.
+
+Run listing accepts either a single status or an array of statuses (OR matching).
+An empty status array matches no runs.
+
 ## What it provides
 
 - Workflow run, step, event, and hook persistence
 - Durable streams
-- Delayed work, retries, deduplication, and dead-letter storage
+- Delayed work, retries, consumer-side deduplication, and dead-letter routing
 - Configurable cleanup of terminal workflow payloads
 - An authenticated HTTP connection between a Node application and a celld fleet
 - An in-process fleet for local development and conformance testing
@@ -70,20 +82,47 @@ const world = createCelldWorld({
 });
 ```
 
-`WORKFLOW_BASE_URL` (or `baseUrl`) is where queue cells deliver flow and step
+`WORKFLOW_BASE_URL` (or `baseUrl`) is where the native Queue bridge delivers flow
 requests. It must be reachable from every celld node.
 
 ## Deploy the worker
 
-Before deploying, you need a celld v0.3.0 fleet, `esbuild` on `PATH`, and an
-object store that meets celld's conditional-write requirements. v0.3.0 is the
-currently tested runtime baseline. Refer to the
+Before deploying, you need a celld v0.5.0 fleet, `esbuild` on `PATH`, and an
+object store that meets celld's conditional-write requirements. Refer to the
 [celld documentation](https://github.com/denoland/celld) for fleet and storage
 setup.
 
+**world-celld 0.5.0 is a breaking release and requires celld v0.5.0.**
+Older runtimes and node-level worker-variable overrides are unsupported.
+
+For an existing fleet, follow the [v0.5.0 upgrade and feature review](docs/celld-v0.5-upgrade.md).
+Stop every old celld node before starting v0.5.0; this is not a rolling upgrade.
+
+Before either deploy, set `vars.WORLD_SECRET` in both copied Wrangler configs
+to the same secret from your secret manager. Set optional
+`vars.WORKFLOW_CALLBACK_SECRET` in the primary config and
+`vars.WORKFLOW_RETENTION_MS` there to the desired maximum workflow age
+(for example, `"7776000000"` for 90 days). Use private deployment copies outside
+source control: celld persists these variables in the deployment stored in the
+fleet bucket. v0.5.0 rejects `CELLD_VAR_*`; `.dev.vars` is read only by
+`celld dev`, not by `celld deploy`.
+
+No second storage service is required for queue payloads. celld v0.5.0 serves
+the `WORKFLOW_QUEUE_PAYLOADS` binding from the existing fleet bucket under
+`r2/workflow-world-queue-payloads/`. `r2_buckets` is the Wrangler-compatible
+configuration key for that binding; it does not require Cloudflare R2.
+
+Deploy the Queue consumer first, then the primary HTTP worker. The consumer
+binds the primary worker's `QueueDeliveryRpc` named entrypoint; deploy matching
+versions of both scripts during a maintenance window. The former internal
+`/v1/queue/deliver` route is removed. The order matters:
+the consumer deploy creates the Queue attachment; the primary deploy must go last
+so it remains the fleet's public application.
+
 From a source checkout:
 
 ```sh
+celld deploy ./celld-queue-worker --bucket s3://my-cells-bucket
 celld deploy ./celld-worker --bucket s3://my-cells-bucket
 ```
 
@@ -91,29 +130,40 @@ From an installed package, first copy the deployable worker into your project:
 
 ```sh
 cp -R node_modules/@ewhauser/world-celld/celld-worker ./workflow-world
+cp -R node_modules/@ewhauser/world-celld/celld-queue-worker ./workflow-world-queue
+celld deploy ./workflow-world-queue --bucket s3://my-cells-bucket
 celld deploy ./workflow-world --bucket s3://my-cells-bucket
 ```
 
-The worker rejects stateful requests unless `WORLD_SECRET` is configured. Pass
-the same secret to the fleet and the application:
+If upgrading from the former QueueDO implementation, this is a hard queue
+cutover. Existing `QueueDO` messages and dead letters are
+not migrated into celld's native Queue; drain or otherwise account for them
+before upgrading an existing fleet. The old QueueDO cell data becomes
+unreachable after the binding is removed.
+
+The worker rejects stateful requests unless `WORLD_SECRET` is configured in its
+deployment. Use that same secret for the application
+(`CELLD_WORLD_SECRET`). Start nodes with the storage and listener settings:
 
 ```sh
-CELLD_VAR_WORLD_SECRET="$CELLD_WORLD_SECRET" \
-CELLD_VAR_WORKFLOW_RETENTION_MS=7776000000 \
 celld --bucket s3://my-cells-bucket \
   --listen 0.0.0.0:8080 \
   --internal-listen 10.0.0.12:8081 \
   --advertise 10.0.0.12:8081
 ```
 
-Use a secret manager rather than putting the value in `wrangler.jsonc`. Keep
+Keep deployment configs containing secrets out of source control. Keep
 celld's internal listener on a trusted network; the World bearer token protects
 the worker RPC routes, not celld's administrative endpoints.
 
-The example sets a fleet-wide maximum workflow age of 90 days. Leave
-`WORKFLOW_RETENTION_MS` at `0` to disable that policy.
+Setting `vars.WORKFLOW_RETENTION_MS` to `"7776000000"` enables a fleet-wide
+maximum workflow age of 90 days. Leave `WORKFLOW_RETENTION_MS` at `0` to disable that policy.
+
+More deployment detail is in [`celld-worker/README.md`](./celld-worker/README.md)
+and [`celld-queue-worker/README.md`](./celld-queue-worker/README.md).
 
-More deployment detail is in [`celld-worker/README.md`](./celld-worker/README.md).
+For opt-in bucket or collector telemetry and local `.dev.vars` setup, see
+the [operational examples](docs/celld-v0.5-upgrade.md#adopt-telemetry).
 
 ## How it works
 
@@ -129,11 +179,14 @@ celld worker router
   |-- HookTokenDO    32 stable token-ownership shards
   |-- HookIdDO       32 stable hook-id lookup shards
   |-- StreamDO       stream chunks and run/stream indexes
-  `-- QueueDO        delayed delivery, retries, and dead letters
+  |-- object storage run-bearing queue payload bodies in the fleet bucket
+  `-- native Queue producer
           |
-          | HTTP callbacks
           v
-Workflow application /.well-known/workflow/v1/flow
+native Queue --> companion consumer --> QueueDeliveryRpc.deliver()
+                                                        |
+                                                        v
+                         Workflow application /.well-known/workflow/v1/flow
 ```
 
 The application-side package implements the Workflow `World` interface and
@@ -147,8 +200,8 @@ Index routing is a versioned hard-cutover protocol. Run catalog writes hash the
 natural keys across 32 shards each. A single stateless worker request queries
 all 16 catalog shards in parallel and merges their lexicographic pages before
 authoritative RunDO reads. The RunDO is also the only permanent lifecycle
-authority: hook shards consult it directly, while queue and catalog expiry
-fences compact after bounded protocol leases. Token and hook-ID admission are
+authority: hook shards and queue idempotency claims consult it directly, while
+catalog expiry fences compact after bounded protocol leases. Token and hook-ID admission are
 each transactional inside their natural-key shards. Exact claim IDs plus a
 serialized cancellation fence resolve ambiguous delivery without pretending
 the two ownership shards form a cross-Durable-Object transaction. Stateless cohesive index routes keep
@@ -172,7 +225,6 @@ variable is shown below.
 | `secret`                | `CELLD_WORLD_SECRET`     | required with `fleetUrl` |
 | `baseUrl`               | `WORKFLOW_BASE_URL`      | `http://localhost:$PORT` |
 | `deploymentId`          | `CELLD_DEPLOYMENT_ID`    | `celld-default`          |
-| `queueShards`           | —                        | `1`                      |
 | `runRetentionMs`        | `CELLD_RUN_RETENTION_MS` | `0` (disabled)           |
 | `streamLongPollMs`      | —                        | `20000`                  |
 | `streamFlushIntervalMs` | —                        | `0`                      |
@@ -180,30 +232,22 @@ variable is shown below.
 
 The deployed worker also accepts these celld variables:
 
-| Variable                          | Default  | Purpose                                              |
-| --------------------------------- | -------- | ---------------------------------------------------- |
-| `WORLD_SECRET`                    | none     | Required bearer secret for RPC routes                |
-| `WORKFLOW_CALLBACK_SECRET`        | none     | Sent with deliveries as `x-workflow-callback-secret` |
-| `QUEUE_MAX_ATTEMPTS`              | `5`      | Attempts before a message is dead-lettered           |
-| `QUEUE_MAX_INFLIGHT`              | `5`      | Concurrent deliveries per queue cell (maximum `128`) |
-| `QUEUE_DELIVERY_TIMEOUT_MS`       | `300000` | Callback timeout (maximum `300000`)                  |
-| `WORKFLOW_RETENTION_MS`           | `0`      | Maximum run age from creation; includes active runs  |
-| `WORKFLOW_RETENTION_BATCH_SIZE`   | `128`    | Runs admitted by each cron sweep (maximum `1000`)    |
-| `WORKFLOW_RETENTION_QUEUE_SHARDS` | `1`      | Queue-shard fallback for older runs                  |
-
-`queueShards` is part of queue placement and is pinned when a queue cell is
-first used. It may be any positive safe integer; the `128` storage-operation
-batch limit does not cap the fleet's total shard count. Drain pending work
-before changing it.
+| Variable                        | Default | Purpose                                              |
+| ------------------------------- | ------- | ---------------------------------------------------- |
+| `WORLD_SECRET`                  | none    | Required bearer secret for RPC routes                |
+| `WORKFLOW_CALLBACK_SECRET`      | none    | Sent with deliveries as `x-workflow-callback-secret` |
+| `WORKFLOW_RETENTION_MS`         | `0`     | Maximum run age from creation; includes active runs  |
+| `WORKFLOW_RETENTION_BATCH_SIZE` | `128`   | Runs admitted by each cron sweep (maximum `1000`)    |
 
 Queue deadlines use fixed-width 13-digit epoch-millisecond keys. A requested
 `delaySeconds` or handler redelivery timeout is accepted only when its deadline
-is at most `9999999669998`, leaving 330,001 ms for a fresh alarm edge and the
-maximum delivery lease. Every derived due, retry, inflight, and GC deadline is
-checked against the absolute `9999999999999` limit. A production retry which
-cannot preserve that headroom is dead-lettered instead of clamped or rescheduled;
-the test pump terminates the equivalent in-memory message. Long test-mode waits
-are chunked at the host timer limit without changing this deadline contract.
+leaves room for the 15-minute idempotency-claim window below the absolute
+`9999999999999` limit. A suspension that cannot preserve that headroom becomes
+a normal broker retry instead of being clamped. celld's native
+producer delay is capped at 86,400 seconds, so the consumer chains longer waits
+while preserving the absolute deadline and stable message identity. Long
+test-mode waits are chunked at the host timer limit without changing this
+deadline contract.
 
 ## Workflow retention
 
@@ -217,8 +261,9 @@ failed, and cancelled runs.
 The packaged worker declares an hourly UTC celld cron trigger. Each occurrence
 scans one bounded creation-time catalog page and asks the authoritative run
 cells to enforce the cutoff. A run cell immediately fences reads, writes, stream
-activity, and queue work, removes its catalog entry, then finishes the existing
-bounded stream, queue, and payload cleanup phases through its durable alarm.
+activity, and queue payload work, removes its catalog entry, then finishes the
+existing bounded stream, object-store queue-payload, and run-payload cleanup phases through
+its durable alarm.
 Repeated cron invocations and alarm retries are idempotent.
 
 One occurrence admits at most `WORKFLOW_RETENTION_BATCH_SIZE` runs (default
@@ -227,11 +272,6 @@ backlog, later occurrences continue with the next oldest entries. Edit
 `triggers.crons` in the copied `celld-worker/wrangler.jsonc` if hourly discovery
 does not provide the desired expiration resolution or catch-up rate.
 
-New runs persist the application's `queueShards` value for complete queue
-cleanup. `WORKFLOW_RETENTION_QUEUE_SHARDS` is the fallback for runs created
-before that metadata existed and must match the placement used by those runs.
-Both values may be any positive safe integer.
-
 ### Terminal payload retention
 
 When `runRetentionMs` is greater than zero, a terminal transition atomically
@@ -240,8 +280,10 @@ step, hook, and stream data remains readable until that deadline. Active and
 pending runs are never eligible for automatic cleanup.
 
 At expiration, the run cell fences new writes and removes the run's derived
-indexes, stream chunks, pending and dead-letter queue messages, and durable run
-payloads. Cleanup is a persisted, idempotent state machine. Each alarm processes
+indexes, stream chunks, object-store queue payloads, and durable run payloads.
+Native Queue pointer messages can remain until celld's fixed four-day retention
+expires; a pointer whose object-store body was removed is acknowledged as permanently gone
+and cannot resurrect the run. Cleanup is a persisted, idempotent state machine. Each alarm processes
 one bounded page, persists its progress, and re-arms the next alarm; an
 interrupted phase records its error and retries with capped backoff.
 
@@ -273,10 +315,8 @@ fleet-wide maximum age are both enabled, the earlier deadline wins.
 
 - Delivery is at least once. Workflow steps and other external side effects
   must be idempotent.
-- Queue cells expose `stats`, `listDeadLetters`, `redriveDeadLetter`,
-  `purgeDeadLetters`, and `rearmAlarm` through the authenticated RPC endpoint.
-  `purgeDeadLetters` deletes at most 128 entries per call; repeat it while its
-  result reports `hasMore`.
+- Native Queue operations are administered with celld's `queue info`, `peek`,
+  `pause`, `resume`, `purge`, and `redrive` commands.
 - Run cells expose retention status, scheduling, immediate cleanup, and alarm
   recovery through `world.retention`.
 - A new application URL applies to newly enqueued messages. Existing messages
@@ -307,14 +347,21 @@ pnpm test:integration
 
 ### Real celld restart smoke
 
-The required CI smoke owns native celld v0.3.0 and MinIO processes on loopback,
+The required CI smoke owns native celld v0.5.0 and MinIO processes on loopback,
 uses fresh temporary bucket and runtime state, and kills celld with `SIGKILL`
 before deleting its local working state and starting a new process against the
 bucket-backed state. It checks that:
 
+- opt-in runtime telemetry is persisted as nonempty Parquet files in the fleet bucket;
 - acknowledged run and stream state survives the process restart;
 - an accepted delayed queue message that becomes due while celld is down is
-  delivered once after the alarm is restored;
+  delivered once after the native broker is restored;
+- the companion Queue consumer can call the named `QueueDeliveryRpc` service
+  entrypoint and recover run-bearing payloads from the fleet object store;
+- transient callbacks increment attempts while suspension preserves the attempt
+  count and message identity;
+- invalid credentials, envelopes, and attempts are rejected across real RPC;
+- the former HTTP delivery route returns 404;
 - multi-page retention cleanup continues from a persisted nonterminal phase;
 - cancelling an in-flight HTTP long poll leaves the stream writable and
   readable.
@@ -326,9 +373,8 @@ pnpm test:integration:celld-smoke
 ```
 
 The runner downloads celld and MinIO artifacts at pinned versions and verifies
-their SHA-256 digests before use. MinIO does not implement the conditional-write
-contract celld requires for production ownership fencing, so the smoke disables
-the storage probe and runs exactly one celld process at a time. It proves the
+their SHA-256 digests before use. celld performs its required storage-contract
+probe at startup; the smoke runs exactly one celld process at a time. It proves the
 single-process restart boundaries above, not multi-node ownership, handoff, or
 failover correctness.
 
@@ -340,13 +386,12 @@ message reaches a successful callback, including forced `503` redeliveries. A
 second workload creates terminal runs with streams and delayed queue messages,
 then verifies complete payload cleanup without resurrection. Results include
 queue and cleanup throughput plus p50, p95, p99, and maximum latency and are
-saved under `.perf-results/`. The harness currently pins celld v0.3.0.
+saved under `.perf-results/`. The harness pins celld v0.5.0 and deploys the same
+two-script native Queue topology as the restart smoke.
 
-> MinIO Community is **not a supported celld production store**. It does not
-> implement the conditional writes celld needs for ownership fencing. This
-> deliberately single-node harness disables celld's storage probe and tests
-> the queue's persistence, redelivery, and performance paths only; it does not
-> validate multi-node ownership or failover correctness.
+> This harness runs a single celld node and leaves the required storage-contract
+> probe enabled. Passing it does not establish multi-node fencing, ownership
+> handoff, or production suitability for a particular object-store deployment.
 
 With Docker and the Compose plugin installed, run:
 
@@ -354,43 +399,10 @@ With Docker and the Compose plugin installed, run:
 pnpm test:perf:minio
 ```
 
-The defaults send 1,000 messages with concurrency 32 across two queue cells,
-and force every twentieth message through one `503` redelivery.
-
-#### Reference result
-
-The following directional baseline was recorded on August 21, 2026. MinIO and
-celld ran as native arm64 processes because Docker was unavailable on the test
-machine; container results will differ.
-
-| Environment | Value                                                                                                    |
-| ----------- | -------------------------------------------------------------------------------------------------------- |
-| Machine     | MacBook Pro (Mac15,8), Apple M3 Max, 16 cores (12 performance, 4 efficiency), 64 GB RAM                  |
-| OS          | macOS 26.5.2 (25F84), arm64                                                                              |
-| Services    | celld v0.3.0; MinIO RELEASE.2025-09-07T16-13-09Z                                                         |
-| Workload    | 1,000 messages; concurrency 32; 2 queue shards; 256-byte target payload; every 20th message retried once |
-
-| Metric                  |                                                                            Result |
-| ----------------------- | --------------------------------------------------------------------------------: |
-| Delivery integrity      | 1,000 accepted, 1,000 delivered, 0 missing, 0 duplicate successes, 0 dead letters |
-| Callback attempts       |                                           1,050, including 50 forced redeliveries |
-| Enqueue throughput      |                                                                 865.66 messages/s |
-| Delivery throughput     |                                                                 794.60 messages/s |
-| Enqueue latency         |                          p50 26.06 ms; p95 70.72 ms; p99 146.59 ms; max 157.70 ms |
-| All delivery latency    |                         p50 65.05 ms; p95 184.47 ms; p99 225.10 ms; max 328.75 ms |
-| First-attempt latency   |                         p50 63.65 ms; p95 177.93 ms; p99 209.38 ms; max 226.86 ms |
-| Retried-message latency |                        p50 114.81 ms; p95 286.35 ms; p99 328.75 ms; max 328.75 ms |
-| Final queue state       |                         0 pending, 0 in flight, 0 dead letters across both shards |
-
-The retention workload in the same run tombstoned 100 of 100 terminal runs,
-expired all 100 reads, deleted 400 payload keys, 100 streams, and 100 delayed
-queue messages, and left both queue shards empty.
-
-Use these numbers as a smoke-test reference, not a portable performance
-guarantee. For regression tracking, compare repeated runs on the same machine
-and runtime configuration. Two shards gave the best latency balance for this
-workload; benchmark your own traffic before changing the shard count. A fleet
-pins its shard count on first use, so changing it requires draining the queues.
+The defaults send 1,000 messages with concurrency 32 and force every twentieth
+message through one `503` redelivery. The old QueueDO/shard baseline is not
+comparable to the native celld Queue path and was intentionally removed; record
+a fresh machine-specific baseline before enabling budgets.
 
 Override the workload or set machine-specific regression budgets with
 environment variables:
@@ -398,18 +410,17 @@ environment variables:
 ```sh
 PERF_MESSAGES=10000 \
 PERF_CONCURRENCY=64 \
-PERF_QUEUE_SHARDS=16 \
 PERF_MIN_DELIVERY_PER_SECOND=100 \
 PERF_MAX_DELIVERY_P99_MS=5000 \
 pnpm test:perf:minio
 ```
 
 Useful controls are `PERF_PAYLOAD_BYTES`, `PERF_RETRY_EVERY`,
-`PERF_TIMEOUT_MS`, `PERF_QUEUE_MAX_INFLIGHT`,
+`PERF_TIMEOUT_MS`,
 `PERF_MIN_ENQUEUE_PER_SECOND`, `PERF_MIN_DELIVERY_PER_SECOND`, and
 `PERF_MAX_DELIVERY_P99_MS`. Throughput and latency budgets default to disabled
-because local machines vary. Message-loss, dead-letter, message-ID, queue-drain,
-and duplicate-success checks are always enforced.
+because local machines vary. Message-loss, message-ID, callback validity, and
+duplicate-success checks are always enforced.
 
 Bug reports and focused pull requests are welcome. Please include a regression
 test for behavior changes and run the checks above before submitting a PR.

package/celld-queue-worker/README.md

@@ -0,0 +1,26 @@
+# world-celld Queue consumer
+
+This companion celld v0.5.0 script consumes the native `workflow-world` Queue
+and forwards each delivery to the primary `workflow-world` script through a
+`QueueDeliveryRpc` named service binding. The consumer calls
+`deliver(secret, envelope, attempt)` and handles `complete`, `suspend`, or `retry`
+results. RPC exceptions retry without acknowledgment. The separate script keeps the broker consumer attachment independent of the
+public HTTP worker.
+
+Deploy it before the primary worker so the Queue consumer attachment exists:
+
+```sh
+cp -r node_modules/@ewhauser/world-celld/celld-queue-worker ./workflow-world-queue
+celld deploy ./workflow-world-queue --bucket s3://my-cells-bucket
+```
+
+Before deploying, set `vars.WORLD_SECRET` in the copied Wrangler config to the
+same bearer secret used by the primary worker. Keep that private deployment
+config out of source control. v0.5.0 rejects `CELLD_VAR_*` node overrides.
+Deploy the primary worker after this script so it remains the fleet's
+public application. Native Queue operations are available through `celld queue
+info`, `peek`, `pause`, `resume`, `purge`, and `redrive`.
+
+The primary worker must export `QueueDeliveryRpc`, and this script's service
+binding must set `entrypoint` to that name. Deploy matching worker versions
+during a maintenance window; there is no fallback to `/v1/queue/deliver`.

package/celld-queue-worker/worker.ts

@@ -0,0 +1,3 @@
+// Companion native Queue consumer. It intentionally exports no fetch handler:
+// Keep the Queue consumer attachment independent of the public HTTP worker.
+export { default } from '@ewhauser/world-celld/queue-consumer';

package/celld-queue-worker/wrangler.jsonc

@@ -0,0 +1,26 @@
+{
+  "name": "workflow-world-queue-consumer",
+  "main": "worker.ts",
+  "compatibility_date": "2026-01-01",
+  "services": [
+    { "binding": "WORLD_SERVICE", "service": "workflow-world", "entrypoint": "QueueDeliveryRpc" },
+  ],
+  "queues": {
+    "producers": [{ "binding": "WORKFLOW_QUEUE", "queue": "workflow-world" }],
+    "consumers": [
+      {
+        "queue": "workflow-world",
+        "max_batch_size": 10,
+        "max_batch_timeout": 1,
+        "max_retries": 100,
+        "dead_letter_queue": "workflow-world-dlq",
+        "max_concurrency": 25,
+      },
+    ],
+  },
+  "vars": {
+    // REQUIRED. Inject the same value used by the primary worker through
+    // vars in a private deployment copy of this config; never commit secrets.
+    "WORLD_SECRET": "",
+  },
+}

package/celld-worker/README.md

@@ -1,52 +1,60 @@
 # world-celld worker
 
-The celld-deployable half of `@ewhauser/world-celld`: six cell classes
-(WorkflowRunDO, RunCatalogDO, HookTokenDO, HookIdDO, StreamDO, and QueueDO)
-behind an authenticated HTTP router.
-Storage, control, and queue methods use fixed JSON RPC routes; stream chunks use
-bounded binary batch writes and binary long-poll reads.
+The primary celld-deployable half of `@ewhauser/world-celld`: five cell classes
+(WorkflowRunDO, RunCatalogDO, HookTokenDO, HookIdDO, and StreamDO) behind an
+authenticated HTTP router, plus the `QueueDeliveryRpc` named entrypoint
+for the companion consumer. Storage and control methods use fixed JSON RPC
+routes; stream chunks use bounded binary batch writes and binary long-poll
+reads. Queue producers use celld's native Queue binding, with run-bearing
+payload bodies stored in the fleet's object store.
 
 ## Deploy
 
-Copy this directory out of `node_modules` so `celld deploy` can bundle it
-(its `main` must live inside the project directory), then deploy against your
-fleet bucket:
+Copy this directory and the companion Queue consumer out of `node_modules` so
+`celld deploy` can bundle them. Deploy the consumer first and this primary
+worker last. Before deploying, set `vars.WORLD_SECRET` in both copied
+Wrangler configs to the same secret from your secret manager. Keep those
+private deployment copies out of source control; celld stores their variables
+in the fleet bucket. Stop the whole old fleet before starting v0.5.0 nodes:
 
 ```sh
 cp -r node_modules/@ewhauser/world-celld/celld-worker ./workflow-world
+cp -r node_modules/@ewhauser/world-celld/celld-queue-worker ./workflow-world-queue
+celld deploy ./workflow-world-queue --bucket s3://my-cells-bucket
 celld deploy ./workflow-world --bucket s3://my-cells-bucket
 ```
 
+Upgrading from the former QueueDO implementation is a hard cutover. Drain or
+account for its pending messages and dead letters first; they are not migrated
+to the native Queue.
+
 Requirements:
 
-- celld v0.3.0 (the currently tested runtime baseline).
+- celld v0.5.0 (the currently tested runtime baseline).
 - `esbuild` on PATH (celld shells out to it).
 - A bucket with conditional-write support (celld's fencing requirement).
-- `WORLD_SECRET` injected at the node level (`CELLD_VAR_WORLD_SECRET=...`) —
+- `WORLD_SECRET` set in the deployment config (`vars.WORLD_SECRET`) —
   the router fails closed with 503 while it is empty.
 
+Queue payloads do not require another provider or another set of credentials.
+celld maps the `WORKFLOW_QUEUE_PAYLOADS` binding into the fleet bucket under
+`r2/workflow-world-queue-payloads/`. The `r2_buckets` key in `wrangler.jsonc`
+names the Workers-compatible binding API; it does not require Cloudflare R2.
+
 ## Fleet-wide retention
 
 The bundled `wrangler.jsonc` declares an hourly UTC cron trigger. It does no
-catalog work by default. Set `CELLD_VAR_WORKFLOW_RETENTION_MS` on every node to
-enable a maximum workflow age measured from run creation:
-
-```sh
-CELLD_VAR_WORKFLOW_RETENTION_MS=7776000000 \
-celld --bucket s3://my-cells-bucket
-```
+catalog work by default. Set `vars.WORKFLOW_RETENTION_MS` to `"7776000000"`
+in the primary Wrangler config and redeploy to enable a maximum workflow age
+measured from run creation. v0.5.0 rejects `CELLD_VAR_*` node overrides.
+`.dev.vars` overrides apply only to `celld dev`, not production deployments.
 
 `7776000000` is 90 days. The policy includes pending and running workflows as
 well as terminal ones. Each cron occurrence admits at most
 `WORKFLOW_RETENTION_BATCH_SIZE` runs (default `128`); the existing per-run alarm
-state machine finishes bounded index, stream, queue, and payload cleanup.
-
-New runs persist the application's `queueShards` placement. Set
-`WORKFLOW_RETENTION_QUEUE_SHARDS` to the historical positive-safe-integer
-queue-shard count when cleaning runs created before this worker version. The
-`128` multikey storage-operation limit is not a total-shard ceiling. Edit
-`triggers.crons` in the copied config if hourly discovery is not the desired
-resolution.
+state machine finishes bounded index, stream, object-store queue-payload, and run-payload
+cleanup. Edit `triggers.crons` in the copied config if hourly discovery is not
+the desired resolution.
 
 Point the app at any node's public listener:
 

package/celld-worker/worker.ts

@@ -3,9 +3,9 @@
 // application's node_modules so the deployed bundle stays in step with the
 // installed @ewhauser/world-celld version.
 export {
+  QueueDeliveryRpc,
   HookIdDO,
   HookTokenDO,
-  QueueDO,
   RunCatalogDO,
   StreamDO,
   WorkflowRunDO,

package/celld-worker/wrangler.jsonc

@@ -12,7 +12,6 @@
       { "name": "WORKFLOW_RUN_CATALOG", "class_name": "RunCatalogDO" },
       { "name": "WORKFLOW_HOOK_TOKENS", "class_name": "HookTokenDO" },
       { "name": "WORKFLOW_HOOK_IDS", "class_name": "HookIdDO" },
-      { "name": "WORKFLOW_QUEUE", "class_name": "QueueDO" },
     ],
   },
   "migrations": [
@@ -24,10 +23,20 @@
         "RunCatalogDO",
         "HookTokenDO",
         "HookIdDO",
-        "QueueDO",
       ],
     },
   ],
+  "queues": {
+    "producers": [{ "binding": "WORKFLOW_QUEUE", "queue": "workflow-world" }],
+  },
+  // celld maps this Workers-compatible binding into the existing fleet bucket
+  // at r2/<bucket_name>/; it does not require a Cloudflare R2 deployment.
+  "r2_buckets": [
+    {
+      "binding": "WORKFLOW_QUEUE_PAYLOADS",
+      "bucket_name": "workflow-world-queue-payloads",
+    },
+  ],
   // Fleet-wide maximum-age retention is discovered hourly. The handler is a
   // no-op while WORKFLOW_RETENTION_MS is "0". Change this expression if a
   // different sweep cadence is required; celld cron schedules are UTC.
@@ -35,7 +44,7 @@
   "vars": {
     // REQUIRED: bearer secret for the world's RPC and binary stream surface.
     // Authenticated routes fail closed with 503 while this is empty. Inject the real value
-    // at the node level with CELLD_VAR_WORLD_SECRET instead of committing it.
+    // into vars in a private deployment copy of this config; never commit secrets.
     "WORLD_SECRET": "",
     // Optional: forwarded as x-workflow-callback-secret on queue deliveries.
     "WORKFLOW_CALLBACK_SECRET": "",
@@ -44,10 +53,5 @@
     "WORKFLOW_RETENTION_MS": "0",
     // Maximum runs admitted to cleanup by one hourly sweep (1..1000).
     "WORKFLOW_RETENTION_BATCH_SIZE": "128",
-    // Must match createCelldWorld({ queueShards }) so every queue shard is
-    // included in cleanup for active runs discovered by the sweep.
-    "WORKFLOW_RETENTION_QUEUE_SHARDS": "1",
-    // Optional queue tuning (strings): QUEUE_MAX_ATTEMPTS, QUEUE_MAX_INFLIGHT,
-    // QUEUE_DELIVERY_TIMEOUT_MS.
   },
 }