rcf-lite 0.21.0 → 0.23.0

package/blueprints/messaging-queue-cloudflare/README.md

@@ -0,0 +1,125 @@
+# messaging-queue-cloudflare
+
+A directed producer-to-consumer worklist queue on Cloudflare Queues, accessed through a producer facade that is the sole reader of the Queues binding. Cloudflare Queues is the first adapter (queue binding under wrangler config, consumer registered on the Worker `queue` handler); the reserved `messaging-queue-postgres` sibling (Baz decision 7) mints on demand. Ships publish, consume, ack, retry, and DLQ; four lifecycle events (`producerReady`, `messagePublished`, `messageAcked`, `messageDeadLettered`) with a metadata-only field discipline. Composes on `deploy-cloudflare-workers` transitively via the wrangler binding, not through the capability mechanism, so `capabilities: ["queue"]` is what `jobs-background` reads to obtain the producer facade at apply time; no `requiresAppliedCapabilities` block ships at v1.0.0.
+
+## What this blueprint gives you
+
+- **A producer facade** (TAC-3001) that is the sole reader of the queue binding (`env.RCF_TEST_QUEUE` in the fixture; the elicited binding name in a real project) in your source tree, opens on boot, and exposes typed named domain verbs (`publish`, `publishBatch`). Emits `producerReady` on the first successful ready-check.
+- **A consumer registration** (TAC-3002) on the Worker's `queue` handler; reads a batch, dispatches per-message to the registered handler, acks per message, returns `retry` on retryable failure, drives the retry-to-DLQ trajectory at the elicited `max_retries` per ADR-3003.
+- **An event sink** (TAC-3003) with a metadata-only field discipline: `producerReady`, `messagePublished`, `messageAcked`, `messageDeadLettered`; no body bytes, no header value, no consumer context, no producer context.
+- **Six Node-only probes** proving every runtime observable: four against the wrangler-dev-equivalent seam (`producer-facade-ready`, `publish-to-delivery`, `retry-and-dlq`, `event-secrecy`) plus one accountBound `real-account-concurrency-smoke` that skips cleanly without `CI_HAS_CLOUDFLARE_ACCOUNT` per spec section 3.5, and a shared `probe-utils.mjs` helper module.
+
+## The six REQs
+
+| REQ | What it commits |
+|---|---|
+| REQ-001 | Producer facade sole reader of the Queues binding; opens on boot; emits `producerReady`. |
+| REQ-002 | Publish / consume / ack contract with stable message-id and producer-supplied trace-id. |
+| REQ-003 | Retry contract: consumer returning `retry` re-delivers with an incremented attempt counter. |
+| REQ-004 | Dead-letter contract: elicited `max_retries` (default 3 per Cloudflare Queues), DLQ per-consumer via wrangler `dead_letter_queue` field, DLQ retention 4 days per https://developers.cloudflare.com/queues/configuration/dead-letter-queues/. |
+| REQ-005 | Batch consume: elicited `max_batch_size` (default 10, ceiling 100) and `max_batch_timeout` (default 5 seconds, ceiling 60 seconds) per https://developers.cloudflare.com/queues/platform/limits/. |
+| REQ-006 | Four lifecycle events with metadata-only fields; event-secrecy probe asserts against a PII fixture body. |
+
+## The three TACs
+
+- **TAC-3001 producer facade**: sole reader of the queue binding; `publish` and `publishBatch` are the outward surface.
+- **TAC-3002 consumer registration**: the Worker `queue` handler surface; batch envelope; per-message ack / retry semantics.
+- **TAC-3003 event sink**: metadata-only lifecycle event contract; whitelist enforced in code.
+
+## The four ADRs
+
+- **ADR-3001 adapter**: Cloudflare Queues v1.0.0 shipped first adapter. `recommendedDefault: true`. Standards trace clause: Cloudflare Queues documented per-message and per-batch limits.
+- **ADR-3002 delivery semantics** (`scope: global`, topic `deliverySemantics`): at-least-once as the shipped shape; conflicts by design with future exactly-once or at-most-once siblings. Standards trace clause: WSD-005 clauses on at-least-once and out-of-order tolerance.
+- **ADR-3003 max-attempts floor**: `max_retries` default 3, floor 1, ceiling 100 per Cloudflare Queues platform limits. `elicited: true`. Standards trace clause: Cloudflare Queues default retry limit 3 and documented ceiling 100.
+- **ADR-3004 batch defaults**: `max_batch_size` default 10 (ceiling 100), `max_batch_timeout` default 5 seconds (ceiling 60 seconds). `elicited: true`. Standards trace clause: Cloudflare Queues per-consumer batch settings.
+
+## Elicited parameters
+
+Queue name (or binding name in a Workers deploy); `max_retries` before DLQ (default 3, floor 1, ceiling 100); DLQ queue name (a second Cloudflare Queue declared via `dead_letter_queue` in wrangler config); `max_batch_size` (default 10, ceiling 100); `max_batch_timeout` (default 5 seconds, ceiling 60 seconds); producer-supplied trace-id header key (default `x-trace-id`).
+
+## Companions
+
+- **logging**: every publish, every ack, and every DLQ landing writes through the applied logger; a logging companion supplies the factory.
+- **errorHandling**: a publish failure, a DLQ overflow constructs an internal error record; an error-handling companion supplies the record factory and the boundary.
+
+## Composition and conflicts
+
+Composes on `deploy-cloudflare-workers` transitively via the wrangler binding (not through the capability mechanism), so no `requiresAppliedCapabilities` block ships at v1.0.0. Contributes ADR-3002 as `scope: global` on new topic `deliverySemantics`; a future `messaging-queue-postgres` sibling (Baz decision 7, deferred v1.0.0 pending demand) or an exactly-once / at-most-once sibling would conflict here by design. `capabilities: ["queue"]`; `providesRoles: []`.
+
+## Reserved sibling
+
+`messaging-queue-postgres` (Baz decision 7). Reserved slug beside the `queue` capability row in `packages/rcf-lite/docs/blueprint-authoring.md` section 6a. When demand mints it, the sibling composes on `persistence-data-postgres` as its transport and conflicts by design on `deliverySemantics` with this blueprint; the operator picks one queue backend per project via a project-level ADR.
+
+## The six probes
+
+Each probe is a Node module under `contributions/probes/` exporting the round-5 spec section 3.2 verdict envelope, with a matching `run-<probe-name>.mjs` shim that drives the probe against the shared fixture's T-3 slice and writes the per-blueprint report at `.rcf/reports/blueprints/messaging-queue-cloudflare/<probe-name>.json`.
+
+| Probe | Anchor AC | What it proves | accountBound |
+|---|---|---|---|
+| `producer-facade-ready` | AC-29101-1 | Producer facade opens against the queue binding; `producerReady` fires with `queueName`. | false |
+| `publish-to-delivery` | AC-29102-1, AC-29102-2, AC-29105-1, AC-29108-1 | 5 messages round-trip body byte-equal with stable message-ids and producer-supplied trace-ids preserved; per-message ack; wrangler-dev-equivalent seam. | false |
+| `retry-and-dlq` | AC-29103-1, AC-29104-1 | Consumer returning `retry` observes same stable message-id with attempts 1..max_retries; DLQ landing fires `messageDeadLettered` at `max_retries + 1`; DLQ contents body byte-equal via the DLQ inspector helper. | false |
+| `event-secrecy` | AC-29106-1 | Every event record carries only the whitelist (event, ts, messageId, queueName, attempts); no PII fixture text on JSON grep. | false |
+| `real-account-concurrency-smoke` | AC-29108-2 | Real 500-message round-trip against `rcf-lite-ci-queue-smoke` when `CI_HAS_CLOUDFLARE_ACCOUNT` set; records `accountBoundSkipped: true` when not. | true |
+
+## Anatomy
+
+```
+blueprints/messaging-queue-cloudflare/
+  blueprint.json
+  README.md
+  CHANGELOG.md
+  guide/
+    messaging-queue-cloudflare.md
+  docs/
+    topics.md
+  contributions/
+    requirements/
+      messaging-queue-cloudflare-req-001.json ... req-006.json
+    user-stories/
+      messaging-queue-cloudflare-us-29101.json ... us-29108.json
+    tacs/
+      tac-3001-messaging-queue-cloudflare-producer-facade.json
+      tac-3002-messaging-queue-cloudflare-consumer-registration.json
+      tac-3003-messaging-queue-cloudflare-event-sink.json
+    adrs/
+      adr-3001-messaging-queue-cloudflare-adapter.json
+      adr-3002-messaging-queue-cloudflare-delivery-semantics.json
+      adr-3003-messaging-queue-cloudflare-max-attempts-floor.json
+      adr-3004-messaging-queue-cloudflare-batch-defaults.json
+    probes/
+      probe-utils.mjs
+      producer-facade-ready.mjs                 (+ run-producer-facade-ready.mjs)
+      publish-to-delivery.mjs                   (+ run-publish-to-delivery.mjs)
+      retry-and-dlq.mjs                         (+ run-retry-and-dlq.mjs)
+      event-secrecy.mjs                         (+ run-event-secrecy.mjs)
+      real-account-concurrency-smoke.mjs        (+ run-real-account-concurrency-smoke.mjs)
+```
+
+## Known limitations and mechanism-reach gaps
+
+The five local probes drive the fixture's in-memory queue-driver (`src/queue-driver.mjs`), which realises the Cloudflare Queues binding shape (`send` / `sendBatch` on the producer side, batch envelope with per-message `ack` / `retry` on the consumer side) so the producer facade module and consumer registration are indistinguishable from a live Queues run at the facade boundary. The wrangler-dev-equivalent seam (SDR-3-a on US-29107) is a deliberate v1.0.0 posture: rcf-lite gains no runtime dependency, CI stays reproducible without a live Cloudflare account, and Cloudflare Queues does not support consumer concurrency under `wrangler dev` per https://developers.cloudflare.com/queues/configuration/local-development/ (that assertion is what `real-account-concurrency-smoke` carries as `accountBound: true`).
+
+Two live paths are unproven at v1.0.0 and are recorded per AC below so the gate reviewer and any downstream composing blueprint see exactly what is and is not proven for each AC. The gate reviewer's own single `wrangler dev` run and the `accountBound` smoke are what promote these gaps to proven.
+
+- **AC-29101-1** (producer facade opens on boot; `producerReady` fires with `queueName`): proven against the in-memory realisation of the Cloudflare Queues binding shape (probe `producer-facade-ready`, verdict pass); live Queues delivery unproven pending a reviewer `wrangler dev` run or the accountBound smoke.
+- **AC-29101-2** (sole-reader grep on the applied fixture): proven against the in-memory realisation (source-tree scan of `src/producer.mjs` against `src/consumer.mjs` peers); live-Queues source-tree posture is identical (the grep target is the fixture tree, not the vendor surface), so this AC has no live-only gap.
+- **AC-29102-1** (5 messages round-trip body byte-equal with stable message-id and producer-supplied trace-id): proven against the in-memory realisation of the binding shape (probe `publish-to-delivery`, verdict pass); live Queues delivery of the same 5-message batch unproven pending a reviewer `wrangler dev` run or the accountBound smoke.
+- **AC-29102-2** (`messageAcked` fires per successful consumer return; message not redelivered): proven against the in-memory realisation of the binding shape (probe `publish-to-delivery`, verdict pass); live Queues per-message ack behaviour unproven pending a reviewer `wrangler dev` run or the accountBound smoke.
+- **AC-29103-1** (retry trajectory: same stable message-id across attempts 1..max_retries with incrementing attempt counter): proven against the in-memory realisation of the binding shape (probe `retry-and-dlq`, verdict pass with attempts 1,2,3 on the same message-id); live Queues retry counter observation unproven pending a reviewer `wrangler dev` run or the accountBound smoke.
+- **AC-29104-1** (DLQ landing at `max_retries + 1` with `messageDeadLettered` event and body byte-equal on DLQ inspection): proven against the in-memory realisation of the binding shape (probe `retry-and-dlq`, verdict pass with DLQ landing at attempts=4 and byte-equal body); live Queues DLQ landing via wrangler `dead_letter_queue` field and inspection via `wrangler queues consumer add --dead-letter-queue` unproven pending a reviewer `wrangler dev` run or the accountBound smoke.
+- **AC-29105-1** (batch consume: 5 messages in one batch, per-message ack semantics under `max_batch_size = 10`): proven against the in-memory realisation of the binding shape (probe `publish-to-delivery`, verdict pass); live Queues `max_batch_size` / `max_batch_timeout` behaviour on the [[queues.consumers]] block unproven pending a reviewer `wrangler dev` run or the accountBound smoke.
+- **AC-29106-1** (metadata-only event whitelist; no PII body / header value / consumer context leaks): proven end-to-end against the in-memory realisation (probe `event-secrecy`, verdict pass; the whitelist is code-enforced in `src/event-sink.mjs`, independent of transport); live-Queues run does not change the sink code path, so this AC has no live-only gap.
+- **AC-29108-1** (wrangler-dev-equivalent seam round-trip): proven end-to-end against the in-memory realisation of the binding shape (probe `publish-to-delivery`, verdict pass); a live `wrangler dev` process was not driven in this pass. Rationale: SDR-3-a on US-29107 makes the wrangler-dev-equivalent seam the shipped local seam because Cloudflare Queues does not support consumer concurrency under `wrangler dev` and does not support `wrangler dev --remote` per the local-development doc, so a live-wrangler run adds observability (a real process on port 8787) but does not add facade-contract certainty over the in-memory realisation. The gate reviewer drives one live `wrangler dev` run in their own scratch to close the observability gap.
+- **AC-29108-2** (real-account concurrency smoke: 500 messages, consumer concurrency up to 250): NOT proven at v1.0.0 without `CI_HAS_CLOUDFLARE_ACCOUNT`. The probe records `accountBoundSkipped: true` per spec section 3.5 and the per-blueprint report carries `aggregateVerdict: pass` on the skipped shape. The live 500-message run rides `deploy-cloudflare-workers`' surface (Cloudflare Queues does not support `wrangler dev --remote` per the local-development doc, so this cannot ride a local wrangler process even with the env var set); the live run is a v1.0.0 follow-up when the shared HQ queue `rcf-lite-ci-queue-smoke` (Q2 default) is provisioned on Baz's account.
+
+## Other limitations (not mechanism-reach gaps)
+
+- Cloudflare Queues per-message size cap is 128 KB per https://developers.cloudflare.com/queues/platform/limits/. A project sending larger payloads either chunks or moves the body out-of-band to `object-storage-s3`. This is a boundary the shipped facade does not police; it is a project-level concern the guide names.
+- The Miniflare Queues sub-page returned 404 during spec ratification (2026-09-06); the Cloudflare Queues local-development page above is the authoritative reference and the only URL the guide cites for the local seam.
+
+## What this blueprint does not do
+
+- No fan-out / broadcast pub-sub semantics; that lives in the parked `messaging-eventbus` candidate on a different global topic.
+- No exactly-once transport (Cloudflare Queues implements at-least-once with a stable message-id for consumer-side dedup per ADR-3002); consumer code that needs exactly-once processing dedups on the stable message-id.
+- No schema registry; message bodies are opaque to this blueprint.

package/blueprints/messaging-queue-cloudflare/blueprint.json

@@ -0,0 +1,67 @@
+{
+  "slug": "messaging-queue-cloudflare",
+  "version": "1.0.0",
+  "category": "messaging",
+  "capabilities": ["queue"],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every publish and every ack writes through the applied logger; a logging companion supplies the factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A publish failure, a DLQ overflow constructs an internal error record; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "contributions": [
+    { "id": "messaging-queue-cloudflare-REQ-001", "kind": "req", "path": "requirements/messaging-queue-cloudflare-req-001.json" },
+    { "id": "messaging-queue-cloudflare-REQ-002", "kind": "req", "path": "requirements/messaging-queue-cloudflare-req-002.json" },
+    { "id": "messaging-queue-cloudflare-REQ-003", "kind": "req", "path": "requirements/messaging-queue-cloudflare-req-003.json" },
+    { "id": "messaging-queue-cloudflare-REQ-004", "kind": "req", "path": "requirements/messaging-queue-cloudflare-req-004.json" },
+    { "id": "messaging-queue-cloudflare-REQ-005", "kind": "req", "path": "requirements/messaging-queue-cloudflare-req-005.json" },
+    { "id": "messaging-queue-cloudflare-REQ-006", "kind": "req", "path": "requirements/messaging-queue-cloudflare-req-006.json" },
+    { "id": "messaging-queue-cloudflare-US-29101", "kind": "us", "path": "user-stories/messaging-queue-cloudflare-us-29101.json" },
+    { "id": "messaging-queue-cloudflare-US-29102", "kind": "us", "path": "user-stories/messaging-queue-cloudflare-us-29102.json" },
+    { "id": "messaging-queue-cloudflare-US-29103", "kind": "us", "path": "user-stories/messaging-queue-cloudflare-us-29103.json" },
+    { "id": "messaging-queue-cloudflare-US-29104", "kind": "us", "path": "user-stories/messaging-queue-cloudflare-us-29104.json" },
+    { "id": "messaging-queue-cloudflare-US-29105", "kind": "us", "path": "user-stories/messaging-queue-cloudflare-us-29105.json" },
+    { "id": "messaging-queue-cloudflare-US-29106", "kind": "us", "path": "user-stories/messaging-queue-cloudflare-us-29106.json" },
+    { "id": "messaging-queue-cloudflare-US-29107", "kind": "us", "path": "user-stories/messaging-queue-cloudflare-us-29107.json" },
+    { "id": "messaging-queue-cloudflare-US-29108", "kind": "us", "path": "user-stories/messaging-queue-cloudflare-us-29108.json" },
+    { "id": "TAC-3001-messaging-queue-cloudflare-producer-facade", "kind": "tac", "path": "tacs/tac-3001-messaging-queue-cloudflare-producer-facade.json" },
+    { "id": "TAC-3002-messaging-queue-cloudflare-consumer-registration", "kind": "tac", "path": "tacs/tac-3002-messaging-queue-cloudflare-consumer-registration.json" },
+    { "id": "TAC-3003-messaging-queue-cloudflare-event-sink", "kind": "tac", "path": "tacs/tac-3003-messaging-queue-cloudflare-event-sink.json" },
+    {
+      "id": "ADR-3001-messaging-queue-cloudflare-adapter",
+      "kind": "adr",
+      "path": "adrs/adr-3001-messaging-queue-cloudflare-adapter.json",
+      "recommendedDefault": true,
+      "elicited": false,
+      "standardsTraceClause": "Cloudflare Queues documented per-message and per-batch limits"
+    },
+    {
+      "id": "ADR-3002-messaging-queue-cloudflare-delivery-semantics",
+      "kind": "adr",
+      "path": "adrs/adr-3002-messaging-queue-cloudflare-delivery-semantics.json",
+      "scope": "global",
+      "topic": "deliverySemantics",
+      "standardsTraceClause": "WSD-005 clauses on at-least-once and out-of-order tolerance"
+    },
+    {
+      "id": "ADR-3003-messaging-queue-cloudflare-max-attempts-floor",
+      "kind": "adr",
+      "path": "adrs/adr-3003-messaging-queue-cloudflare-max-attempts-floor.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "Cloudflare Queues default retry limit 3 and documented ceiling 100"
+    },
+    {
+      "id": "ADR-3004-messaging-queue-cloudflare-batch-defaults",
+      "kind": "adr",
+      "path": "adrs/adr-3004-messaging-queue-cloudflare-batch-defaults.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "Cloudflare Queues per-consumer batch settings"
+    }
+  ]
+}

package/blueprints/messaging-queue-cloudflare/contributions/adrs/adr-3001-messaging-queue-cloudflare-adapter.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-3001-messaging-queue-cloudflare-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Adapter: Cloudflare Queues as the shipped v1.0.0 first adapter",
+  "context": "A project deploying a directed producer-to-consumer worklist queue on Cloudflare Workers has one native shipped answer today: Cloudflare Queues. The Queues surface is bound through wrangler configuration (a [[queues.producers]] block for the producer facade to publish through, a [[queues.consumers]] block for the Worker queue handler to consume from), and the shipped Worker runtime binds env.<binding> to a Queues object with send / sendBatch on the producer side and a batch envelope with ack / retry on the consumer side per https://developers.cloudflare.com/queues/configuration/javascript-apis/. The v1.0.0 facade must hold the adapter reference opaque at the facade boundary so a future non-Cloudflare adapter (an SQS shim, the reserved messaging-queue-postgres sibling per Baz decision 7) slots in without a facade re-shape, and so a fixture-time in-memory adapter is testable without live Cloudflare Queues access.",
+  "decision": "The shipped v1.0.0 default is Cloudflare Queues, wired through wrangler config (producer binding on [[queues.producers]], consumer on [[queues.consumers]] with dead_letter_queue and max_retries per https://developers.cloudflare.com/queues/configuration/dead-letter-queues/). The producer facade module is the sole holder of the Queues binding reference per REQ-001; the consumer registration module is the sole reader of the batch envelope per REQ-002. The adapter reference is OPAQUE at this ADR: the facade dereferences the elicited binding at the top of the module and any consumer wanting a different adapter (an SQS shim, the messaging-queue-postgres sibling minted on demand) replaces the binding reference here without touching the outward interface. A fixture-time in-memory adapter (used by the local probes) implements the same binding shape (send / sendBatch on the producer side, batch with ack / retry on the consumer side) so the facade and consumer surfaces are indistinguishable from the real Queues binding at the facade boundary. The 128 KB per-message cap and 100 messages per batch cap Cloudflare documents at https://developers.cloudflare.com/queues/platform/limits/ apply to every real-Queues run.",
+  "consequences": "The project inherits the Cloudflare Queues wire-format, the platform-assigned stable message-id, and the batch envelope's per-message ack semantics. Standards trace clause: Cloudflare Queues documented per-message and per-batch limits (per https://developers.cloudflare.com/queues/platform/limits/), Cloudflare Queues Worker queue-handler contract (per https://developers.cloudflare.com/queues/configuration/javascript-apis/), and Cloudflare Queues dead-letter documentation (per https://developers.cloudflare.com/queues/configuration/dead-letter-queues/). A future non-Cloudflare adapter mints under a sibling blueprint (reserved slug messaging-queue-postgres, Baz decision 7) and conflicts by design on deliverySemantics (ADR-3002) with this blueprint; the operator picks one queue backend per project via a project-level ADR.",
+  "alternativesConsidered": [
+    {
+      "name": "External SQS or SNS as the shipped v1.0.0 default",
+      "summary": "Ship AWS SQS as the primary v1.0.0 queue backend and provide Cloudflare Queues as an elicited alternative.",
+      "reasonNotChosen": "The shelf composition target this round is a Cloudflare Workers project (deploy-cloudflare-workers is the applied deploy target on the shared fixture). Shipping SQS as the default would leave a Workers project reaching into a non-Cloudflare vendor for its main worklist, which is not the shipped-shape target of the round-5 spec section 5.3."
+    },
+    {
+      "name": "Kafka or NATS as the shipped v1.0.0 default",
+      "summary": "Ship a self-hosted Kafka or NATS backend as the primary v1.0.0 queue.",
+      "reasonNotChosen": "A self-hosted Kafka or NATS backend adds a persistent operational surface every applying project has to run; the round-5 spec section 5.3 targets a directed producer-to-consumer worklist as a shipped shape whose applying project need not host a broker. The reserved messaging-queue-postgres sibling (Baz decision 7) covers the self-hosted-transport family separately when demand mints it."
+    },
+    {
+      "name": "Ship a hand-rolled fetch client against the Queues REST API",
+      "summary": "Skip the Worker Queues binding and roll a fetch client against the Queues REST-shape endpoints.",
+      "reasonNotChosen": "The Worker binding is the shipped Cloudflare surface and the one every Queues doc references; a REST client would ship a second surface with its own auth and its own reliability envelope. The mature binding-based surface is what makes the v1.0.0 facade portable at the boundary."
+    }
+  ],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/adrs/adr-3002-messaging-queue-cloudflare-delivery-semantics.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-3002-messaging-queue-cloudflare-delivery-semantics",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Delivery semantics: at-least-once as the shipped shape (scope global, new topic deliverySemantics)",
+  "context": "A directed producer-to-consumer worklist ships one of three delivery shapes at the transport contract: at-most-once (fire and forget, dedup at the producer), at-least-once (guaranteed delivery with duplicates possible, dedup at the consumer), or exactly-once (guaranteed delivery with dedup at the transport, expensive). Cloudflare Queues implements at-least-once with a stable message-id the consumer uses for its own dedup; the WSD-005 messaging standard (operator/knowledge/wsd/wsd-standards/wsd-005-messaging.md) makes at-least-once and out-of-order tolerance the shipped default for domain event handoffs; the messaging-queue-cloudflare blueprint claims the deliverySemantics topic on the shelf so future exactly-once or at-most-once siblings surface as DELIBERATE conflicts and not silent divergences.",
+  "decision": "The shipped v1.0.0 shape is at-least-once. Every publish reaches every consumer at least once; duplicates are possible under retry-and-DLQ redelivery paths; consumer code that needs exactly-once semantics maintains its own dedup keyed on the stable message-id per REQ-002. The deliverySemantics topic scope is global on this blueprint; the topic string is deliverySemantics (lower camel case, one concept per topic, no version suffix, per the round-2 rules-for-new-topics clause on the shelf registry). Future exactly-once or at-most-once siblings would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR per the round-2 conflict pattern.",
+  "consequences": "The applying project inherits an at-least-once transport with a stable message-id it uses for consumer-side dedup when the domain calls for exactly-once processing. Standards trace clause: WSD-005 clauses on at-least-once and out-of-order tolerance (satisfied by the message-id and trace-id header contract). The reserved messaging-queue-postgres sibling (Baz decision 7) will claim deliverySemantics with an at-least-once answer too; two shipped answers on one topic surface a DELIBERATE conflict the operator resolves by picking one queue backend per project via a project-level ADR (the same shape as errorEnvelope and authModel conflicts the SPA and API-REST blueprints already carry).",
+  "alternativesConsidered": [
+    {
+      "name": "At-most-once as the shipped v1.0.0 default",
+      "summary": "Ship fire-and-forget publish semantics with producer-side dedup and no DLQ.",
+      "reasonNotChosen": "At-most-once loses the DLQ safety net and does not compose with the retry contract REQ-003 requires. The shipped shape's whole reason for existing is the guaranteed handoff for background work; at-most-once is the wrong contract for that use case."
+    },
+    {
+      "name": "Exactly-once as the shipped v1.0.0 default",
+      "summary": "Ship transport-level dedup so the consumer never sees the same message-id twice.",
+      "reasonNotChosen": "Cloudflare Queues does not implement transport-level exactly-once; shipping the label would misrepresent the transport. Consumer-side dedup keyed on the stable message-id is the shipped path when exactly-once is the domain requirement."
+    }
+  ],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/adrs/adr-3003-messaging-queue-cloudflare-max-attempts-floor.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-3003-messaging-queue-cloudflare-max-attempts-floor",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Max-attempts before DLQ: default 3, floor 1, ceiling 100 per Cloudflare Queues platform limits",
+  "context": "A retry-and-DLQ contract needs a bounded max-attempts before dead-lettering: too low leaks transient failures into the DLQ before the retry can recover them; too high wastes consumer wall-clock and keeps a permanently-broken message live indefinitely. Cloudflare Queues documents a default retry limit of 3 at https://developers.cloudflare.com/queues/configuration/dead-letter-queues/ and a documented ceiling of 100 at https://developers.cloudflare.com/queues/platform/limits/ (max retries per message). The wrangler config field on the [[queues.consumers]] block is max_retries.",
+  "decision": "The shipped v1.0.0 default is max_retries 3, matching the Cloudflare Queues documented default. The floor is 1 (a max_retries of 0 defeats the retry contract REQ-003 requires). The ceiling is 100, matching the Cloudflare Queues documented per-message max. The value is elicited at apply time under the maxAttempts parameter; the fixture wires the default 3 explicitly on the consumer block. Consumer code that needs a tighter or looser bound sets the value at apply time; the boundary check on the elicit rejects values below 1 or above 100 with a stable message id and a pointer at the Cloudflare limits doc.",
+  "consequences": "The applying project inherits a bounded retry budget matching Cloudflare's shipped defaults. Standards trace clause: Cloudflare Queues default retry limit 3 (dead-letter-queues doc) and documented ceiling 100 (platform-limits doc). The elicited value carries into the retry-and-dlq probe (SIMULATE_CONSUMER_RETRY switches the fixture to force the retry path; the probe asserts the DLQ landing at exactly the elicited max_retries).",
+  "alternativesConsidered": [
+    {
+      "name": "Hard-code max_retries 3 with no elicited parameter",
+      "summary": "Ship the Cloudflare default 3 as a hard-coded value with no project-side override.",
+      "reasonNotChosen": "A project running a downstream that recovers over minutes (rate limit, cold cache) may need a higher retry budget; a hard-coded 3 forces the project to bypass the facade to override the limit. Eliciting the value is cheaper than eliciting the escape hatch."
+    },
+    {
+      "name": "No ceiling on max_retries",
+      "summary": "Accept any max_retries value the operator hands in.",
+      "reasonNotChosen": "The Cloudflare Queues platform enforces the 100 ceiling at the transport regardless; the elicit refusing above 100 is what surfaces the failure at apply time rather than at first live redelivery."
+    }
+  ],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/adrs/adr-3004-messaging-queue-cloudflare-batch-defaults.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-3004-messaging-queue-cloudflare-batch-defaults",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Batch settings: max_batch_size default 10 ceiling 100, max_batch_timeout default 5 seconds ceiling 60 seconds",
+  "context": "The consumer reads messages in batches whose size and timeout are elicited on the wrangler [[queues.consumers]] block as max_batch_size and max_batch_timeout. Cloudflare Queues documents a max_batch_size ceiling of 100 messages per batch and a max_batch_timeout ceiling of 60 seconds at https://developers.cloudflare.com/queues/platform/limits/. A default sitting at the ceiling wastes throughput when a project's average burstiness is low; a default too far below reduces the batching benefit. The shipped defaults have to sit below the ceilings so tightening in a project is a config change, not a code change.",
+  "decision": "The shipped v1.0.0 defaults are max_batch_size 10 and max_batch_timeout 5 seconds. Both sit well below the Cloudflare-documented ceilings (100 messages, 60 seconds respectively) so a project that runs closer to the ceiling changes wrangler config only. Both values are elicited under batchSize and batchTimeoutSeconds; the elicit refuses values above the Cloudflare ceiling with a stable message id and a pointer at the Cloudflare limits doc.",
+  "consequences": "The applying project inherits a modest batch envelope that suits most background-work traffic; a project needing near-ceiling batching sets the wrangler config values at apply time. Standards trace clause: Cloudflare Queues per-consumer batch settings, per the limits doc. The publish-to-delivery probe drives 5 messages and asserts the consumer sees them in one batch (5 < the shipped 10, so the batch fills by timeout).",
+  "alternativesConsidered": [
+    {
+      "name": "Ship max_batch_size 100 as the default",
+      "summary": "Ship the Cloudflare ceiling as the default so no operator elicits.",
+      "reasonNotChosen": "A ceiling default hides the batching decision from the operator and wastes wall-clock on a low-burst project. The elicited 10 is a signal to think about the shape of the project's traffic."
+    },
+    {
+      "name": "Ship max_batch_size 1 to force per-message invocation",
+      "summary": "Skip batching altogether and invoke the consumer once per message.",
+      "reasonNotChosen": "Per-message invocation defeats the reason batching exists and puts every project at the Worker invocation limit."
+    }
+  ],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/probes/event-secrecy.mjs

@@ -0,0 +1,137 @@
+/**
+ * Event-secrecy probe.
+ *
+ * Drives publish and ack with a PII fixture body ({userId: 1234, ssn:
+ * "123-45-6789"}) and asserts every event record on the sink carries
+ * only the whitelist ({event, ts, messageId, queueName, attempts}) and
+ * no PII fixture text. The sink adapter (event-sink.mjs) is what
+ * enforces the whitelist; this probe proves the enforcement by driving
+ * the pattern the induced-failure switch SIMULATE_PII_IN_BODY names.
+ *
+ * Anchors AC-29106-1.
+ */
+
+import { createQueuePair } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/queue-driver.mjs';
+import { createProducer, queueConfigFromEnv } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/producer.mjs';
+import { createConsumer, drainLoop } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/consumer.mjs';
+import { createSinkAdapter } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/event-sink.mjs';
+
+const PII_STRINGS = ['123-45-6789', '1234'];
+const FORBIDDEN_KEYS = ['body', 'headers', 'userId', 'ssn', 'consumerContext', 'producerContext'];
+
+/**
+ * Event-secrecy probe (with teeth per PR #159 gate finding 2).
+ *
+ * Two layers of assertion so the whitelist is exercised at the actual
+ * boundary AC-29106-1 claims, not only observed via the shipped code
+ * path that never hands the sink a body-bearing payload:
+ *
+ * (1) Direct-boundary assertion: construct a PII-bearing caller record
+ *     locally, hand it to createSinkAdapter (the exact TAC-3003 boundary
+ *     the AC claims), assert the forwarded record is stripped to the
+ *     whitelist and carries no PII substring.
+ *
+ * (2) Consumer-driven assertion: turn on SIMULATE_LEAK_BODY_TO_SINK on
+ *     the consumer so the shipped consumer path itself hands the sink
+ *     a body-bearing payload (body, headers, userId, ssn,
+ *     consumerContext), then drive publish and ack of a PII fixture
+ *     body and assert every event record observed on the sink carries
+ *     only the whitelist and no PII substring survives.
+ *
+ * A reviewer who disables the whitelist in src/event-sink.mjs and reruns
+ * this probe observes it FAIL on both layers: layer (1) surfaces
+ * forbidden keys on the direct record; layer (2) surfaces the leaked
+ * body / userId / ssn on the acked event. That mutation-run failure is
+ * what proves the probe has teeth (the shipped code, with the whitelist
+ * in place, passes cleanly on the shipped head).
+ */
+export default async function runProbe() {
+  const results = [];
+
+  // Layer (1): direct-boundary assertion at createSinkAdapter.
+  const directCaptured = [];
+  const directSink = createSinkAdapter({ onEvent: (rec) => directCaptured.push(rec) });
+  directSink({
+    event: 'messageAcked',
+    ts: new Date().toISOString(),
+    messageId: 'direct-boundary-msg-001',
+    queueName: 'rcf-test-queue',
+    attempts: 1,
+    body: { userId: 1234, ssn: '123-45-6789', note: 'direct probe leak attempt' },
+    headers: { 'x-trace-id': 'trace-direct', authorization: 'Bearer secret-value' },
+    userId: 1234,
+    ssn: '123-45-6789',
+    consumerContext: { workerId: 'direct-probe', handlerName: 'directHandler' },
+    producerContext: { host: 'direct-probe-host' },
+  });
+  const directSerialised = JSON.stringify(directCaptured);
+  const directAllowed = new Set(['event', 'ts', 'messageId', 'queueName', 'attempts']);
+  const directForbiddenKeys = directCaptured.length === 1
+    ? Object.keys(directCaptured[0]).filter((k) => !directAllowed.has(k))
+    : ['record-count-mismatch'];
+  const directPiiHits = PII_STRINGS.filter((s) => directSerialised.includes(s));
+  const directForbiddenKeyHits = FORBIDDEN_KEYS.filter((k) => directSerialised.includes(`"${k}"`));
+  const directPass = directCaptured.length === 1 && directForbiddenKeys.length === 0 && directPiiHits.length === 0 && directForbiddenKeyHits.length === 0;
+  results.push({
+    anchorAcId: 'AC-29106-1',
+    verdict: directPass ? 'pass' : 'fail',
+    detail: directPass
+      ? `direct-boundary: PII-bearing caller record stripped by createSinkAdapter to ${Object.keys(directCaptured[0]).join(',')}; no PII / forbidden-key substring survived`
+      : `direct-boundary breach: forwardedKeys=${JSON.stringify(directCaptured.map((r) => Object.keys(r)))} piiHits=${JSON.stringify(directPiiHits)} forbiddenKeyHits=${JSON.stringify(directForbiddenKeyHits)}`,
+  });
+
+  // Layer (2): consumer-driven assertion with SIMULATE_LEAK_BODY_TO_SINK.
+  const cfg = queueConfigFromEnv();
+  const pair = createQueuePair({ queueName: cfg.queueName, dlqName: cfg.dlqName, maxRetries: cfg.maxRetries });
+  const events = [];
+  const producer = createProducer({
+    binding: pair.producer,
+    queueName: cfg.queueName,
+    onEvent: (e) => events.push(e),
+  });
+  await producer.ready;
+
+  const body = { userId: 1234, ssn: '123-45-6789', note: 'secret payload' };
+  await producer.publish(body, { headers: { 'x-trace-id': 'trace-event-secrecy', authorization: 'Bearer secret-value' } });
+
+  const consumer = createConsumer({
+    handler: async (_msg) => 'ack',
+    onEvent: (e) => events.push(e),
+    env: { SIMULATE_PII_IN_BODY: 'true', SIMULATE_LEAK_BODY_TO_SINK: 'true' },
+  });
+  await drainLoop({ consumer, driver: pair, dlqSink: { baseline: [], onEvent: (e) => events.push(e) } });
+
+  const allowedKeys = new Set(['event', 'ts', 'messageId', 'queueName', 'attempts']);
+  let recordsWithForbiddenKeys = 0;
+  for (const rec of events) {
+    for (const k of Object.keys(rec)) {
+      if (!allowedKeys.has(k)) {
+        recordsWithForbiddenKeys += 1;
+        break;
+      }
+    }
+  }
+  const serialised = JSON.stringify(events);
+  const piiHits = PII_STRINGS.filter((s) => serialised.includes(s));
+  const forbiddenKeyHits = FORBIDDEN_KEYS.filter((k) => serialised.includes(`"${k}"`));
+
+  // Also confirm SIMULATE_LEAK_BODY_TO_SINK actually fired: the consumer
+  // hands the sink a body-bearing record on messageAcked, and the sink
+  // adapter must have received the body for the whitelist to strip it.
+  // We prove the leak-path was taken by observing at least one
+  // messageAcked event in the captured records (a probe run where the
+  // consumer switch was silently unwired would surface no messageAcked
+  // and the assertion falls over even before the whitelist check).
+  const ackedCount = events.filter((e) => e.event === 'messageAcked').length;
+
+  const consumerPass = ackedCount >= 1 && recordsWithForbiddenKeys === 0 && piiHits.length === 0 && forbiddenKeyHits.length === 0;
+  results.push({
+    anchorAcId: 'AC-29106-1',
+    verdict: consumerPass ? 'pass' : 'fail',
+    detail: consumerPass
+      ? `consumer-driven leak-path: SIMULATE_LEAK_BODY_TO_SINK on, ${ackedCount} messageAcked events observed on the sink; whitelist stripped all forbidden fields; no PII substring survived on ${events.length} events total`
+      : `consumer-driven breach: ackedCount=${ackedCount} recordsWithForbiddenKeys=${recordsWithForbiddenKeys} piiHits=${JSON.stringify(piiHits)} forbiddenKeyHits=${JSON.stringify(forbiddenKeyHits)}`,
+  });
+
+  return results;
+}

package/blueprints/messaging-queue-cloudflare/contributions/probes/probe-utils.mjs

@@ -0,0 +1,82 @@
+/**
+ * Shared helpers for messaging-queue-cloudflare probes.
+ *
+ * Runtime-dependency posture: probes import the fixture's in-memory
+ * queue-driver, producer facade, consumer registration, and DLQ
+ * inspector from the sample-app fixture's src/ tree so rcf-lite itself
+ * gains no new runtime dependency (round-5 spec section 5, brief
+ * section 4). The wrangler.toml alongside declares the real Queues
+ * binding shape a project would receive when composing against live
+ * Cloudflare Queues; the in-memory driver realises the same binding
+ * shape (send / sendBatch on the producer side, batch envelope with
+ * ack / retry per message on the consumer side) so the facade module
+ * is indistinguishable from a live-Queues run at the facade boundary.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// Project root four levels above blueprints/messaging-queue-cloudflare/contributions/probes/
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/infra-s3-and-queue');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/messaging-queue-cloudflare');
+
+/**
+ * Compute the aggregate verdict per spec section 3.4:
+ * - fail if any result carries verdict fail
+ * - warn if any result carries verdict warn and no fail
+ * - pass otherwise
+ */
+export function aggregate(results) {
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+
+/**
+ * Write the per-blueprint probe report at
+ * .rcf/reports/blueprints/messaging-queue-cloudflare/<probeName>.json
+ * per spec section 3.4.
+ */
+export async function writeReport({ probeName, engine, results }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const report = {
+    slug: 'messaging-queue-cloudflare',
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict: aggregate(results),
+  };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2), 'utf8');
+  return { report, path };
+}
+
+/**
+ * Drive an async main() and exit 0 on aggregate pass, 1 otherwise.
+ * Prints the report JSON to stdout for the gate-reviewer to read.
+ */
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const results = await mainFn();
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stdout.write(`report written to ${path}\n`);
+    process.exit(report.aggregateVerdict === 'pass' ? 0 : 1);
+  } catch (err) {
+    const results = [{
+      anchorAcId: 'unknown',
+      verdict: 'fail',
+      detail: `probe threw: ${err && err.message ? err.message : String(err)}`,
+    }];
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${err && err.stack ? err.stack : String(err)}\n`);
+    process.stderr.write(`report written to ${path}\n`);
+    process.exit(1);
+  }
+}

package/blueprints/messaging-queue-cloudflare/contributions/probes/producer-facade-ready.mjs

@@ -0,0 +1,35 @@
+/**
+ * Producer-facade-ready probe.
+ *
+ * Opens the fixture's producer facade against the in-memory queue driver
+ * (the wrangler-dev-equivalent seam per US-29107, SDR-3-a), asserts
+ * producerReady fires on the injected event sink with queueName.
+ *
+ * Anchors AC-29101-1.
+ */
+
+import { createQueuePair } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/queue-driver.mjs';
+import { createProducer, queueConfigFromEnv } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/producer.mjs';
+
+export default async function runProbe() {
+  const cfg = queueConfigFromEnv();
+  const pair = createQueuePair({ queueName: cfg.queueName, dlqName: cfg.dlqName, maxRetries: cfg.maxRetries });
+  const events = [];
+  const producer = createProducer({
+    binding: pair.producer,
+    queueName: cfg.queueName,
+    onEvent: (e) => events.push(e),
+  });
+  const results = [];
+  await producer.ready;
+  const ready = events.find((e) => e.event === 'producerReady');
+  const pass = !!ready && ready.queueName === cfg.queueName && producer.isReady();
+  results.push({
+    anchorAcId: 'AC-29101-1',
+    verdict: pass ? 'pass' : 'fail',
+    detail: pass
+      ? `producerReady fired with queueName=${ready.queueName}; producer.isReady()=true`
+      : `producerReady missing or wrong; events=${JSON.stringify(events)}`,
+  });
+  return results;
+}