rcf-lite 0.22.0 → 0.23.0

package/blueprints/jobs-background/contributions/user-stories/jobs-background-us-30106.json

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30106",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Operator-facing surface elicited between cli, httpEndpoint and none",
+  "asA": "operator picking how ad-hoc runs and re-drives are invoked",
+  "iWant": "the elicited operator surface (cli, httpEndpoint or none) recorded at apply time",
+  "soThat": "the applying project builds one thin shim against the jobs-runtime contract without the blueprint prescribing a CLI framework or an HTTP router",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-30106-1",
+      "description": "The blueprint declares an elicited parameter operatorSurface with the three enum values cli, httpEndpoint, none in the ADR contribution set (implicit through ADR-3102 elicits section not shipped as a separate ADR because the operator-surface choice does not conflict on a shipped topic); the guide names all three values and the default posture (none for a fresh scaffold; the applying project promotes to cli or httpEndpoint under its own decision). The blueprint does NOT ship the CLI or the HTTP endpoint itself.",
+      "given": "the shipped blueprint files after this train lands",
+      "when": "grep queries walk the guide and README",
+      "then": "guide/jobs-background.md contains the substring operator-facing surface and names all three values cli, httpEndpoint, none; README.md names the same three values; neither ships a CLI binary nor an HTTP router",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3103-jobs-background-run-log"],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/user-stories/jobs-background-us-30107.json

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30107",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Cross-cutting: --allow-no-queue-yet override records a sidecar note",
+  "asA": "operator scaffolding a project that will apply the queue later",
+  "iWant": "the --allow-no-queue-yet override to write a sidecar note under the queue family so rcf define validate later flags surfaces that never activated",
+  "soThat": "a scaffolding pass is possible without silently shipping an ungated jobs surface",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-jobs-overrideRecorded",
+      "description": "On a fresh init scratch project with NO queue provider applied, rcf define blueprint add ./blueprints/jobs-background --allow-no-queue-yet exits 0 and writes the sidecar rcf/blueprints/jobs-background.applied.json with slug jobs-background, allowNoAuthYet true, appliedCapabilities [], and a notes field containing the substring 'no queue yet' and the substring '--allow-no-queue-yet' and the substring 'queue'. The notes must NOT contain the substring 'no auth yet' nor 'no secrets-management yet' (the family derivation on the flag name must resolve to queue, not the auth or secrets families).",
+      "given": "a fresh rcf init scratch project with no applied blueprints",
+      "when": "rcf define blueprint add ./blueprints/jobs-background --allow-no-queue-yet runs",
+      "then": "exit code is 0; rcf/blueprints/jobs-background.applied.json exists; slug is jobs-background; allowNoAuthYet is true; appliedCapabilities is []; notes contains 'no queue yet', '--allow-no-queue-yet' and 'queue'; notes does NOT contain 'no auth yet' nor 'no secrets-management yet'",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3101-jobs-background-job-definition"],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/user-stories/jobs-background-us-30108.json

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30108",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Cross-cutting: scheduled fire on cron drives jobStarted through the elicited fire tolerance window",
+  "asA": "developer relying on a cron-scheduled job",
+  "iWant": "the scheduler to fire the message and the runtime to dispatch it within the elicited fire tolerance window (default 30 seconds), producing jobStarted and jobCompleted on the sink",
+  "soThat": "cron drift is bounded and observable",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-jobs-scheduledRunsOnCron",
+      "description": "With messaging-queue-cloudflare and jobs-background both applied on the shared sample-app fixture, the fake-clock-cron probe advances the fixture's fake clock forward through one POSIX cron minute for the refresh-cache job. Within the elicited fireToleranceMs window (default 30000 ms), a jobStarted event fires on the sink with jobName 'refresh-cache' and attempts 1; within the elicited timeoutMs (10000 ms for refresh-cache), a jobCompleted event fires.",
+      "given": "the fixture with the queue and jobs applied and the fake clock at second 0 of an every-minute POSIX cron",
+      "when": "the fake clock advances 60 seconds",
+      "then": "one jobStarted event fires within fireToleranceMs; one jobCompleted event fires within timeoutMs; both records match the whitelist",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3102-jobs-background-scheduler", "TAC-3103-jobs-background-run-log"],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/user-stories/jobs-background-us-30109.json

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30109",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Cross-cutting: retry-then-DLQ handoff when maxAttempts is exhausted",
+  "asA": "operator observing a terminally failing job",
+  "iWant": "the applied queue's DLQ to receive the message after maxAttempts is exhausted, and jobFailed to fire on the sink with a terminal error code",
+  "soThat": "a terminally failing job lands on the queue's DLQ (as ratified by the T-3 messaging-queue-cloudflare DLQ contract) and the run log records the terminal event",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-30109-1",
+      "description": "The retry-and-fail probe's report, after the three failing jobStarted events and the terminal jobFailed event, records that the underlying in-memory queue driver invoked the DLQ producer path (dlqOverflow flag on the driver's introspection API) for the failing message id. The DLQ handoff is a T-3 concern; jobs-background only asserts the terminal jobFailed event fires and the DLQ path is exercised, not the DLQ delivery contents (T-3 covers that).",
+      "given": "the fixture with SIMULATE_HANDLER_THROW=true and the T-3 in-memory queue seam active",
+      "when": "the retry-and-fail probe runs to completion",
+      "then": "the probe report carries dlqInvoked true; the sink shows jobFailed with terminalErrorCode; the retry-and-fail run report at .rcf/reports/blueprints/jobs-background/retry-and-fail.json carries aggregateVerdict pass",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3103-jobs-background-run-log"],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/docs/topics.md

@@ -0,0 +1,62 @@
+# jobs-background blueprint coordination vocabulary
+
+This file is the jobs-background half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | jobs-background contribution | Origin | Composition note |
+|---|---|---|---|
+| `backgroundJobModel` | ADR-3101-jobs-background-model | Minted by this blueprint. Names the shipped background-job model; the shipped answer is retry-and-schedule (per-message re-delivery on failure inheriting the applied queue's max-attempts ceiling; POSIX cron plus one-shot delayed schedules; metadata-only run-log at four moments). | The one project-wide decision on what background-job discipline the project ships. A future stateful-workflow sibling (Temporal-shape, Airflow-shape) would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR. The round-6 Workflows adapter (per Baz section 5.7 and round-6 decision (b)) lives INSIDE this blueprint as a v1.1.0 minor scheduler-mode value at ADR-3102 and does NOT re-claim this topic. |
+
+The jobs-background blueprint claims one global topic. Every other contribution is scope-local (ADR-3102 scheduler mode, ADR-3103 requires-applied-capabilities, ADR-3104 timeout floor do not contribute global topics; a composing blueprint that holds an opinion on any of them authors its own project-level ADR).
+
+Rules for new topics: lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer.
+
+## Id number bands (registry bootstrap)
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
+| application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+| messaging-queue-cloudflare | 29101-29899 | 30xx | shipped v1.0.0 | `deliverySemantics` |
+| jobs-background | 30101-30899 | 31xx | shipped v1.0.0 | `backgroundJobModel` |
+
+US 30101-30109 sit at the LOW end of the 30101-30899 band on purpose (watchpost run-4 lesson). A project-side story mechanically derived from a jobs-background REQ id into the number 30110 would collide against a shipped US-30110; band headroom (30110-30899) leaves that space.
+
+ADR/TAC suffixes for this blueprint use the 3101-3199 block, continuing the shelf pattern.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `backgroundJobModel` exactly as spelled here when your blueprint holds an opinion on the shipped background-job discipline; contribute your own scope:global ADR on that string and let composition surface the pairing.
+- A future stateful-workflow sibling (Temporal-shape, Airflow-shape) mints on demand; each claims `backgroundJobModel` and conflicts by design.
+- A consumer blueprint that surfaces "run this later" or "run this on a schedule" reads the `backgroundJobs` capability declared on `blueprint.json` per section 6a of `blueprint-authoring.md` to obtain the job-definition and scheduler surfaces at apply time via the T-5 capability-declaration mechanism.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-3101 on `backgroundJobModel` is a first shipped answer to a topic that will conflict, by design, with future stateful-workflow siblings. Applying `jobs-background` alongside a hypothetical Temporal-shape or Airflow-shape sibling raises one `globalAdrTopic` conflict the operator resolves via one of the four documented resolutions per topic (adopt one, keep the existing one, author a project-level supersede ADR, or `--resolve <topic>=project:<ADR-id>` on the add). The reserved v1.1.0 `workflows` scheduler mode inside this blueprint does NOT trigger this conflict because it lives at ADR-3102 (scope-local) and preserves ADR-3101's answer on `backgroundJobModel`.

package/blueprints/jobs-background/guide/jobs-background.md

@@ -0,0 +1,147 @@
+# jobs-background guide
+
+The v1.0.0 background-jobs discipline. Composes on any applied blueprint declaring `capabilities: ["queue"]`; the shipped provider today is `messaging-queue-cloudflare` v1.0.0. Refuses apply on a bare project.
+
+## When to apply this
+
+You have background work that runs asynchronously from a request boundary, in-process on a Node server or in a Cloudflare Worker: welcome emails, cache refreshes, reindexing, receipt PDF generation. You want:
+
+- A uniform job-definition shape so every module in `./jobs/` follows one contract.
+- A scheduler that ships POSIX cron plus one-shot-delayed shapes and elicits the runtime placement (`inProcess`, `workerCron`, `external`).
+- Retry that inherits the applied queue's max-attempts ceiling; no hand-rolled retry loops.
+- Metadata-only observability by default; the domain PII on the job body cannot leak through the run log even by accident.
+
+You do NOT want:
+
+- A stateful multi-step workflow orchestration with durable execution and rollbacks. That is either a future Temporal-shape or Airflow-shape sibling (conflicts on `backgroundJobModel`), or the reserved v1.1.0 `workflows` scheduler mode inside this blueprint.
+- A pub-sub broadcast surface. That is a queue with fan-out semantics; this blueprint composes on a directed producer-to-consumer worklist queue.
+
+## Apply
+
+On a fresh project with `messaging-queue-cloudflare` already applied:
+
+```sh
+rcf define blueprint add jobs-background
+```
+
+Applies 22 contributions and writes the sidecar `rcf/blueprints/jobs-background.applied.json` with `appliedCapabilities: ["queue"]` (discovered through the T-5 capability mechanism).
+
+On a bare project (no queue provider applied), apply refuses:
+
+```sh
+rcf define blueprint add jobs-background
+# exit 3
+# [jobs-background-no-queue] jobs-background requires an applied blueprint declaring
+# at least one of: queue.
+# ...
+# Or override for a scaffolding pass (records a note on source.notes so
+# later validation flags the surface as not-yet-activated):
+#     rcf define blueprint add jobs-background --allow-no-queue-yet
+```
+
+Override:
+
+```sh
+rcf define blueprint add jobs-background --allow-no-queue-yet
+```
+
+Exits 0 and writes the sidecar with `allowNoAuthYet: true`, `appliedCapabilities: []`, `notes: "no queue yet: applied under --allow-no-queue-yet; surfaces gated on queue will refuse at runtime until a queue blueprint is applied."`.
+
+## Writing a job
+
+Every job module in `./jobs/` exports a plain object:
+
+```js
+export default {
+  name: 'send-welcome-email',
+  inputSchema: mySchemaLibrary.object({ userId: mySchemaLibrary.number(), email: mySchemaLibrary.string() }),
+  retryPolicy: { maxAttempts: 3, backoff: 'exponential' },
+  timeoutMs: 60000,
+  async handler(input, ctx) {
+    await ctx.logger.info('sending welcome email', { userId: input.userId });
+    await ctx.http.post('/api/mail', input);
+    return { sent: true };
+  },
+};
+```
+
+Backoff shapes:
+
+- `exponential`: base * 2^(attempts - 1), capped at 10 minutes.
+- `constant`: base seconds between every attempt.
+- `linear`: base * attempts.
+
+The `retryPolicy.maxAttempts` must not exceed the applied queue's ceiling; Cloudflare Queues caps at 100 per ADR-3003 in the messaging-queue-cloudflare blueprint.
+
+## Scheduling
+
+Two shipping shapes at REQ-003:
+
+```js
+// POSIX cron, every minute:
+export default {
+  name: 'refresh-cache',
+  cron: '* * * * *',
+  // ...
+};
+
+// One-shot delayed, invoked from application code:
+await scheduler.delayed({ jobName: 'send-welcome-email', delayMs: 5 * 60 * 1000, input: { userId, email } });
+```
+
+## Running with Cloudflare Queues
+
+The shipped composition target is a Cloudflare Worker deploy with `messaging-queue-cloudflare` applied. The `workerCron` scheduler mode wires Cloudflare Cron Triggers to a Worker handler that publishes to the applied queue; the same Worker consumes the queue and dispatches to registered job handlers.
+
+Wrangler config (extract):
+
+```toml
+[triggers]
+crons = ["* * * * *"]
+
+[[queues.producers]]
+binding = "RCF_TEST_QUEUE"
+queue = "rcf-test-queue"
+
+[[queues.consumers]]
+queue = "rcf-test-queue"
+dead_letter_queue = "rcf-test-dlq"
+max_retries = 3
+```
+
+Boot line for local development against the T-3 in-memory queue-driver seam:
+
+```sh
+node ../../../../blueprints/jobs-background/contributions/probes/run-fake-clock-cron.mjs
+```
+
+## Operator-facing surface (REQ-006)
+
+Elicited between `cli`, `httpEndpoint`, or `none` at apply time.
+
+- `cli`: the applying project builds a thin Node CLI shim against the jobs-runtime that supports `jobs list`, `jobs run <name>`, `jobs status <jobId>`.
+- `httpEndpoint`: the applying project mounts a small HTTP surface through its own HTTP shape (`GET /jobs`, `POST /jobs/:name/run`, `GET /jobs/status/:jobId`).
+- `none`: no operator surface; the run log is the only observability. Default for fresh scaffolds.
+
+The blueprint ships the contract these shims build against; the shim itself is the applying project's concern.
+
+## Reserved v1.1.0 Workflows adapter
+
+The `workflows` scheduler mode arrives at v1.1.0 per Baz section 5.7 and round-6 decision (b). It wraps the same job-definition contract with Cloudflare Workflows `step.do` orchestration, adding durable multi-step execution without changing the outward job-definition shape. What changes:
+
+- One new enum value at ADR-3102: `scheduler: "workflows"`.
+- One new section in this guide covering how to declare durable steps through the workflow adapter.
+- The `fake-clock-cron.mjs` probe gains a `workflows-scheduler` variant.
+
+What does NOT change:
+
+- The `backgroundJobModel` topic answer (still retry-and-schedule at ADR-3101).
+- The job-definition module shape (`name`, `handler`, `inputSchema`, `retryPolicy`, `timeoutMs`).
+- The run-log envelope whitelist (`event`, `jobId`, `jobName`, `attempts`, `duration`, `timestamp`, optional `terminalErrorCode`).
+- The `requiresAppliedCapabilities` block on the applying blueprint.
+
+## Composition with other blueprints
+
+- `observability-logging` (companion): supplies the run-log upstream so the four lifecycle events flow through the applied logger's channel policy.
+- `application-error-handling` (companion): supplies the error record factory a `jobFailed` constructs on the terminal path.
+- `messaging-queue-cloudflare`: the shipped `queue` capability provider today. The `messaging-queue-postgres` sibling (reserved slug per Baz decision 7 in the T-3 documentation) mints on demand and composes here without any change to `jobs-background`.

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

@@ -0,0 +1,15 @@
+# messaging-queue-cloudflare changelog
+
+## 1.0.0 - 2026-09-06
+
+Initial release. Directed producer-to-consumer worklist queue on Cloudflare Queues; first shipped adapter with the reserved `messaging-queue-postgres` sibling (Baz decision 7) named beside it in the section 6a capability table. Accessed through a producer facade that is the sole reader of the Cloudflare Queues binding (`env.RCF_TEST_QUEUE` in the fixture). Landed via the infra round 5 spec (ratified 2026-09-06) as track T-3.
+
+- 21 contributions: 6 REQs on producer facade sole-reader / publish-consume-ack / retry / dead-letter / batch / lifecycle events; 8 USs at 29101-29108; 3 TACs (3001 producer facade, 3002 consumer registration, 3003 event sink); 4 ADRs (3001 adapter Cloudflare Queues shipped, 3002 `deliverySemantics` scope global at-least-once, 3003 max_retries default 3 floor 1 ceiling 100, 3004 batch size default 10 batch timeout default 5 seconds).
+- Five Node-only probes under `contributions/probes/` proven against the wrangler-dev-equivalent seam (in-memory queue driver realising the Cloudflare Queues binding shape per SDR-3-a on US-29107): `producer-facade-ready`, `publish-to-delivery`, `retry-and-dlq`, `event-secrecy`, and the accountBound `real-account-concurrency-smoke`. The real-account smoke records `accountBoundSkipped: true` when `CI_HAS_CLOUDFLARE_ACCOUNT` is unset per spec section 3.5.
+- T-3 slice of the shared sample-app fixture at `packages/rcf-lite/test/fixtures/infra-s3-and-queue/` adds a `wrangler.toml` declaring the queue binding (`RCF_TEST_QUEUE`), DLQ binding (`RCF_TEST_DLQ`), `dead_letter_queue = "rcf-test-dlq"`, `max_retries = 3`, `max_batch_size = 10`, `max_batch_timeout = 5`; plus `src/queue-driver.mjs`, `src/producer.mjs`, `src/consumer.mjs`, `src/dlq-inspector.mjs`, `src/event-sink.mjs`. Three wired induced-failure switches (`SIMULATE_CONSUMER_RETRY`, `SIMULATE_DLQ_OVERFLOW`, `SIMULATE_PII_IN_BODY`) drive the negative-run paths.
+- Declares `capabilities: ["queue"]`, `suggestedCompanions: [{role: "logging"}, {role: "errorHandling"}]`, `providesRoles` absent, `requiresAppliedCapabilities` absent. Composes on `deploy-cloudflare-workers` transitively via the wrangler binding (not through the capability mechanism), so `jobs-background` reads the `queue` capability at apply time via the T-5 mechanism from the visual round.
+- Contributes ADR-3002 as `scope: global` on new topic `deliverySemantics`. Future exactly-once, at-most-once or `messaging-queue-postgres` siblings conflict here by design.
+- Every ADR contribution entry on `blueprint.json` carries a `standardsTraceClause` per section 8a.2 (mandatory per HQ mid-flight ruling after PR #154 gate).
+- Extends `packages/rcf-lite/docs/blueprint-authoring.md` section 6a capability-declaration table with one row for `queue` naming the reserved `messaging-queue-postgres` sibling per Baz decision 7 and spec section 5.6.
+- The Miniflare Queues sub-page under the workers testing miniflare storage tree is NOT cited: the ratified round-5 spec's status block records it returning 404 on 2026-09-06. The Cloudflare Queues local-development page (`https://developers.cloudflare.com/queues/configuration/local-development/`) is the sole citation for the local seam.
+- Lifecycle event whitelist reuses T-2 object-storage-s3's `{event, ts, ...}` common envelope prefix (per PR #157 gate reviewer note 2026-09-06) so a future v1.1 minor can promote one shared shape to schema enforcement.

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"
+}