rcf-lite 0.21.0 → 0.23.0

package/blueprints/messaging-queue-cloudflare/contributions/user-stories/messaging-queue-cloudflare-us-29103.json

@@ -0,0 +1,25 @@
+{
+  "usId": "messaging-queue-cloudflare-US-29103",
+  "prdId": "PRD-001",
+  "reqId": "messaging-queue-cloudflare-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Consumer returning retry re-delivers the same message-id with an incremented attempt counter",
+  "asA": "developer whose consumer needs to handle transient failures without human intervention",
+  "iWant": "a consumer that returns retry to observe the same message-id on the next delivery with an incremented attempt counter",
+  "soThat": "policy decisions like log at attempt 2, alert at attempt N-1 are trivially expressed in code",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-29103-1",
+      "description": "Given the SIMULATE_CONSUMER_RETRY=true induced-failure switch on the fixture, when the consumer returns retry on the first delivery, then the second delivery observes the same stable message-id with attempts incremented to 2; the same holds on the third delivery with attempts 3. The retry-and-dlq probe records the full trajectory 1 to 3 attempts on the same message-id.",
+      "given": "a message published with the SIMULATE_CONSUMER_RETRY switch true on the fixture",
+      "when": "the consumer is invoked across successive deliveries",
+      "then": "the message-id is stable across attempts 1 to 3; the attempt counter increments on each delivery; body, headers and producer-supplied trace-id remain byte-equal across attempts",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3002-messaging-queue-cloudflare-consumer-registration"],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/user-stories/messaging-queue-cloudflare-us-29104.json

@@ -0,0 +1,25 @@
+{
+  "usId": "messaging-queue-cloudflare-US-29104",
+  "prdId": "PRD-001",
+  "reqId": "messaging-queue-cloudflare-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "After max-attempts the message lands on the DLQ with messageDeadLettered and the DLQ contents match",
+  "asA": "developer whose consumer needs a receipt for permanent failures without blocking the queue",
+  "iWant": "a message that fails past max-attempts to land on the configured DLQ with a lifecycle event and inspectable DLQ contents",
+  "soThat": "operational triage of a bad message is a matter of reading the DLQ, not of grepping application logs",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-29104-1",
+      "description": "Given a message that returns retry across max_retries deliveries (default 3), when the third delivery returns retry, then a messageDeadLettered event fires on the sink with the stable message-id, the queue name, and attempts equal to the terminal attempt count. The message is present on the DLQ; inspecting the DLQ through the fixture DLQ-inspector helper returns the body byte-equal to the original publish.",
+      "given": "the fixture with max_retries 3 and SIMULATE_CONSUMER_RETRY=true published once",
+      "when": "the delivery loop runs to exhaustion",
+      "then": "the retry-and-dlq probe records attempts 1, 2, 3 with the same message-id; messageDeadLettered fires with attempts equal to the terminal count; the DLQ-inspector reads the message body back byte-equal",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3002-messaging-queue-cloudflare-consumer-registration", "TAC-3003-messaging-queue-cloudflare-event-sink"],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/user-stories/messaging-queue-cloudflare-us-29105.json

@@ -0,0 +1,25 @@
+{
+  "usId": "messaging-queue-cloudflare-US-29105",
+  "prdId": "PRD-001",
+  "reqId": "messaging-queue-cloudflare-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Batch consume bounded by Cloudflare limits with per-message ack semantics",
+  "asA": "developer publishing bursty traffic",
+  "iWant": "the consumer to process a batch of messages in one Worker invocation with the elicited batch size and batch timeout, acking each message individually",
+  "soThat": "one bad message in a batch does not roll back the twenty good ones behind it",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-29105-1",
+      "description": "Given the fixture consumer configured with max_batch_size 10 and max_batch_timeout 5, when 5 messages are published in rapid succession, then the consumer receives them in one batched invocation and acknowledges each per message; every message is delivered exactly to the count published (barring redeliveries the AC does not test); no batch-level rollback fires on a per-message retry.",
+      "given": "the fixture consumer with the elicited batch settings",
+      "when": "the publish-to-delivery probe publishes 5 messages",
+      "then": "the consumer receives them in one batch; per-message ack fires 5 times; the messageAcked events on the sink number 5",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3002-messaging-queue-cloudflare-consumer-registration"],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/user-stories/messaging-queue-cloudflare-us-29106.json

@@ -0,0 +1,25 @@
+{
+  "usId": "messaging-queue-cloudflare-US-29106",
+  "prdId": "PRD-001",
+  "reqId": "messaging-queue-cloudflare-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every lifecycle event carries a metadata-only whitelist with no body bytes, no header values and no consumer context",
+  "asA": "developer whose queue traffic may carry PII bodies",
+  "iWant": "the lifecycle event whitelist to be enforced in code so my consumer logging cannot accidentally leak a body byte, a header value, or a consumer-context field",
+  "soThat": "the shipped shape composes with a PII-bearing body without redaction gymnastics at every log site",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-29106-1",
+      "description": "Given the SIMULATE_PII_IN_BODY=true induced-failure switch driving publish and ack with a PII fixture body (userId 1234, ssn 123-45-6789), when the event-secrecy probe captures the events, then every event record carries exactly the whitelist fields (event, messageId, queueName, attempts, timestamp) and no more; no body bytes, no header value, no userId string, no ssn string, no consumer-context field appears in any record, verified by JSON-stringify substring grep.",
+      "given": "the PII fixture body driven through publish, consume and ack",
+      "when": "the event-secrecy probe reads the captured event records",
+      "then": "every record carries only the whitelist; JSON-stringify substring grep for the fixture PII strings returns no match on any record",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3003-messaging-queue-cloudflare-event-sink"],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/user-stories/messaging-queue-cloudflare-us-29107.json

@@ -0,0 +1,25 @@
+{
+  "usId": "messaging-queue-cloudflare-US-29107",
+  "prdId": "PRD-001",
+  "reqId": "messaging-queue-cloudflare-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Wrangler-dev round-trip: full publish-to-delivery cycle observable under wrangler dev",
+  "asA": "developer running the fixture under wrangler dev on my laptop",
+  "iWant": "the producer-facade-ready and publish-to-delivery cycles to complete inside the fixture wrangler-dev seam without a real Cloudflare account",
+  "soThat": "I can iterate on the facade contract without a live account and CI can gate a change without live-account access",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-29108-1",
+      "description": "Given the fixture booted with the in-memory queue-driver mode (the wrangler-dev-equivalent seam the probes drive), when the producer-facade-ready and publish-to-delivery probes run in sequence, then producerReady fires with the queueName, publish delivers all 5 messages to the consumer with body byte-equal, and the per-blueprint reports at .rcf/reports/blueprints/messaging-queue-cloudflare/producer-facade-ready.json and publish-to-delivery.json each carry aggregateVerdict pass.",
+      "given": "the fixture with the in-memory queue-driver mode active (SDR-3-a: wrangler-dev-equivalent seam per the local-development doc's stated limitations)",
+      "when": "the producer-facade-ready and publish-to-delivery run-shims execute",
+      "then": "each shim exits 0; the per-blueprint reports carry aggregateVerdict pass; the event records observed include producerReady with queueName and 5 messageAcked events with matching messageIds",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3001-messaging-queue-cloudflare-producer-facade", "TAC-3002-messaging-queue-cloudflare-consumer-registration"],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/user-stories/messaging-queue-cloudflare-us-29108.json

@@ -0,0 +1,25 @@
+{
+  "usId": "messaging-queue-cloudflare-US-29108",
+  "prdId": "PRD-001",
+  "reqId": "messaging-queue-cloudflare-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Real-account concurrency smoke: 500 messages processed concurrently up to the 250 cap",
+  "asA": "developer verifying the facade works against a real Cloudflare account",
+  "iWant": "a smoke test that publishes 500 messages against the shared HQ queue rcf-lite-ci-queue-smoke and asserts the consumer processes them concurrently up to the documented 250-invocation cap",
+  "soThat": "the shipped shape's compatibility with the real Cloudflare Queues surface is proven end-to-end at least once per release, without requiring every CI run to be account-bound",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-29108-2",
+      "description": "Given CI_HAS_CLOUDFLARE_ACCOUNT=1 and the credentials for the shared HQ queue rcf-lite-ci-queue-smoke wired via security-secrets-management, when the real-account-concurrency-smoke probe runs against the real queue, then 500 messages are published, the consumer processes them concurrently up to the 250 push-based invocation cap Cloudflare documents at https://developers.cloudflare.com/queues/platform/limits/, and the smoke drains the queue on exit. Without CI_HAS_CLOUDFLARE_ACCOUNT the probe records accountBoundSkipped true per spec section 3.5 and the per-blueprint report carries aggregateVerdict pass.",
+      "given": "the shared HQ queue rcf-lite-ci-queue-smoke on Baz's account, or the env var unset",
+      "when": "the real-account-concurrency-smoke run-shim executes",
+      "then": "with the env var set, 500 messages round-trip with observed concurrency below or equal to 250; with the env var unset, the report carries accountBoundSkipped true and aggregateVerdict pass; the shim exits 0 in both paths",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3001-messaging-queue-cloudflare-producer-facade", "TAC-3002-messaging-queue-cloudflare-consumer-registration"],
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/docs/topics.md

@@ -0,0 +1,62 @@
+# messaging-queue-cloudflare blueprint coordination vocabulary
+
+This file is the messaging-queue-cloudflare 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 | messaging-queue-cloudflare contribution | Origin | Composition note |
+|---|---|---|---|
+| `deliverySemantics` | ADR-3002-messaging-queue-cloudflare-delivery-semantics | Minted by this blueprint. Names the wire-shape contract for message-delivery guarantees; the shipped answer is at-least-once (Cloudflare Queues implements at-least-once with a stable message-id the consumer uses for its own dedup per https://developers.cloudflare.com/queues/configuration/javascript-apis/, and WSD-005 makes at-least-once and out-of-order tolerance the shipped default for domain event handoffs). | The one project-wide decision on delivery semantics for the primary worklist queue. A future exactly-once or at-most-once sibling would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR |
+
+The messaging-queue-cloudflare blueprint claims one global topic. Every other contribution is scope-local (ADR-3001 adapter, ADR-3003 max-attempts floor, ADR-3004 batch defaults 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 29101-29108 sit at the LOW end of the 29101-29899 band on purpose (watchpost run-4 lesson). A project-side story mechanically derived from a messaging-queue-cloudflare REQ id into the number 29110 would collide against a shipped US-29110; band headroom (29109-29899) leaves that space.
+
+ADR/TAC suffixes for this blueprint use the 3001-3099 block, continuing the shelf pattern.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `deliverySemantics` exactly as spelled here when your blueprint holds an opinion on the delivery-guarantee contract for the primary worklist queue; contribute your own scope:global ADR on that string and let composition surface the pairing.
+- A future exactly-once, at-most-once, or `messaging-queue-postgres` sibling mints on demand; each claims `deliverySemantics` and conflicts by design.
+- `jobs-background` (round-5 track T-4) reads the `queue` capability declared on `blueprint.json` per section 6a of `blueprint-authoring.md` to obtain the producer facade at apply time via the T-5 visual-round capability-declaration mechanism.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-3002 on `deliverySemantics` is a first shipped answer to a topic that will conflict, by design, with future exactly-once or at-most-once siblings, and with the reserved `messaging-queue-postgres` sibling (Baz decision 7). Applying `messaging-queue-cloudflare` alongside a hypothetical `messaging-queue-postgres` 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).

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

@@ -0,0 +1,110 @@
+# messaging-queue-cloudflare guide
+
+## What this blueprint gets you
+
+A directed producer-to-consumer worklist queue on Cloudflare Queues: publish, consume, ack, retry, DLQ. The producer facade is the sole reader of the Queues binding declared in your wrangler config (a `[[queues.producers]]` block); the consumer registration attaches to the Worker's `queue` handler through the paired `[[queues.consumers]]` block. Consumer code calls typed named domain verbs on the facade (`publish`, `publishBatch`) and never touches the raw binding. Every publish attaches a producer-supplied trace-id header so downstream consumers stitch the enqueue-to-process boundary; every consumer receipt records `messageAcked` on the sink with the stable platform-assigned message-id.
+
+Four lifecycle events fire on the injected event sink with a rigid metadata-only whitelist (`event`, `ts`, `messageId`, `queueName`, `attempts`); consumer logging cannot leak object body bytes, header values, consumer-context fields or PII from the message body. The whitelist is enforced in code by the sink adapter (`event-sink.mjs`), not just documented.
+
+The reserved sibling `messaging-queue-postgres` (Baz decision 7, deferred v1.0.0 pending demand) mints on demand and conflicts by design on `deliverySemantics` with this blueprint; the operator picks one queue backend per project via a project-level ADR.
+
+## Apply this blueprint
+
+`deploy-cloudflare-workers` is the composition target this blueprint expects on a Workers project. The v1.0.0 shipped shape does NOT declare a `requiresAppliedCapabilities` block: the queue binding is wired through wrangler config (not through the capability mechanism), and `jobs-background` composes on the `queue` capability this blueprint provides (per spec section 5.6).
+
+```sh
+rcf define blueprint add messaging-queue-cloudflare
+```
+
+Exits 0 on any Workers-adjacent project. Contributes ADR-3002 on `scope: global` topic `deliverySemantics` (at-least-once as the shipped shape); a project that already declares a different answer on `deliverySemantics` (an exactly-once or at-most-once sibling minted on demand) surfaces a DELIBERATE conflict for operator resolution.
+
+## Producer facade shape
+
+```js
+import { createProducer, queueConfigFromEnv } from './producer.mjs';
+
+const cfg = queueConfigFromEnv();
+const producer = createProducer({
+  binding: env.RCF_TEST_QUEUE, // the wrangler-bound Queues producer
+  queueName: cfg.queueName,
+  onEvent: (record) => logger.log('messaging-queue', record),
+});
+
+await producer.ready;
+
+// publish one message with a producer-supplied trace-id
+const { id } = await producer.publish({ userId: '42', action: 'sendConfirmation' }, {
+  headers: { 'x-trace-id': crypto.randomUUID() },
+});
+
+// publish a batch
+await producer.publishBatch([
+  { body: { seq: 1 }, headers: { 'x-trace-id': 't-1' } },
+  { body: { seq: 2 }, headers: { 'x-trace-id': 't-2' } },
+]);
+```
+
+The facade is the sole holder of the queue binding reference per REQ-001. A call site that reaches into `env.<binding>.send()` directly is refused at author-side review.
+
+## Consumer registration shape
+
+```js
+import { createConsumer } from './consumer.mjs';
+
+export default {
+  queue: createConsumer({
+    handler: async (msg) => {
+      // msg.id, msg.body, msg.headers, msg.attempts, msg.timestamp
+      try {
+        await processBackgroundWork(msg.body);
+        return 'ack';
+      } catch (err) {
+        // Return 'retry' to redeliver with an incremented attempt counter;
+        // after max_retries the message lands on the DLQ per REQ-004.
+        return 'retry';
+      }
+    },
+    onEvent: (record) => logger.log('messaging-queue', record),
+    env: process.env,
+  }),
+};
+```
+
+## Wrangler dev section
+
+Local iteration on the fixture uses `wrangler dev` (v3.1.0+ per the Cloudflare Queues local-development doc). The wrangler-dev seam brings up producer and consumer in a single command with `--persist-to` for reproducible state:
+
+```sh
+cd packages/rcf-lite/test/fixtures/infra-s3-and-queue
+npx wrangler dev --persist-to .wrangler-state
+```
+
+Consumer concurrency is NOT supported under `wrangler dev` per https://developers.cloudflare.com/queues/configuration/local-development/; the local run proves the facade contract, publish, consume, ack, retry, and DLQ landing, but does not exercise the 250-invocation concurrency cap. That assertion is the accountBound `real-account-concurrency-smoke` probe. Similarly, Cloudflare Queues does not support `wrangler dev --remote` per the same page.
+
+The shipped v1.0.0 probes drive the wrangler-dev-equivalent seam (in-memory queue driver realising the same binding shape) so CI stays reproducible without a live Cloudflare account; the boundary at the facade is indistinguishable from a live-Queues run.
+
+## Miniflare in CI section
+
+Miniflare (`https://developers.cloudflare.com/workers/testing/miniflare/`, fetched 2026-09-06 status 200) documents itself as full-featured and supports KV, Durable Objects, WebSockets, modules, and more, without listing Queues explicitly. The Miniflare Queues sub-page returned 404 during spec ratification, so no citation ships at that URL. In CI, the wrangler-dev-equivalent seam the fixture ships is the reference; a project that needs the full Miniflare surface for a broader integration test wires it separately and defers to the Cloudflare Queues local-development page above for the Queues-specific behaviour.
+
+## Real-account smoke section
+
+`node ../../../../blueprints/messaging-queue-cloudflare/contributions/probes/run-real-account-concurrency-smoke.mjs` is the accountBound probe. Without `CI_HAS_CLOUDFLARE_ACCOUNT` it exits 0 with `accountBoundSkipped: true` per spec section 3.5 and the per-blueprint report reads `aggregateVerdict: pass`. With `CI_HAS_CLOUDFLARE_ACCOUNT=1` plus credentials for the shared HQ queue `rcf-lite-ci-queue-smoke` (Q2 default) wired via `security-secrets-management`, a live-account run is queued as a v1.0.0 follow-up: the run itself rides `deploy-cloudflare-workers`' surface (not a Node probe module) since Cloudflare Queues does not support `wrangler dev --remote`, and the v1.0.0 probe stops short of driving deployment machinery.
+
+## Retry and DLQ discipline
+
+ADR-3003 sets `max_retries` to 3 (matching the Cloudflare Queues documented default at https://developers.cloudflare.com/queues/configuration/dead-letter-queues/) with a floor of 1 and a ceiling of 100 (matching the Cloudflare Queues documented per-message max at https://developers.cloudflare.com/queues/platform/limits/). On overflow, the message lands on the elicited DLQ declared via the `dead_letter_queue` field on the wrangler `[[queues.consumers]]` block; the DLQ has its own retention (4 days when no active consumer is attached per the DLQ doc). A DLQ inspector helper (`src/dlq-inspector.mjs` in the fixture; `wrangler queues consumer add --dead-letter-queue` in production per the DLQ doc's CLI form) reads the DLQ contents for triage.
+
+## Batch consume discipline
+
+ADR-3004 sets `max_batch_size` to 10 (ceiling 100) and `max_batch_timeout` to 5 seconds (ceiling 60 seconds) per the Cloudflare Queues platform limits. Batch settings live on the `[[queues.consumers]]` block in wrangler config; a project running closer to the ceiling changes the config values, not the code. Per-message ack semantics keep one bad message in a batch from rolling back its peers.
+
+## Composition with jobs-background
+
+`jobs-background` (round-5 track T-4) declares `requiresAppliedCapabilities: ["queue"]`; applying `jobs-background` on a project that already applied `messaging-queue-cloudflare` gets the T-4 apply-time capability check to pass with the `queue` capability discovered on the applied manifest. The T-4 blueprint enqueues jobs through the producer facade this blueprint exposes; the retry-and-DLQ trajectory is what turns transient job failures into eventual success and permanent failures into a DLQ receipt.
+
+## What this blueprint does not do
+
+- No exactly-once transport (Cloudflare Queues does not implement transport-level dedup); consumer code that needs exactly-once processing dedups on the stable message-id.
+- No fan-out / broadcast pub-sub; that shape lives in the parked `messaging-eventbus` candidate on a different global topic.
+- No schema registry on the message bodies (they are opaque to the blueprint boundary).

package/blueprints/object-storage-s3/CHANGELOG.md

@@ -0,0 +1,13 @@
+# object-storage-s3 changelog
+
+## 1.0.0 - 2026-09-06
+
+Initial release. Contract for S3-shape object storage on any S3-compatible endpoint (Cloudflare R2 first, MinIO for local dev, AWS S3, Backblaze B2, Wasabi, self-hosted). Accessed through a store facade that is the sole reader of the S3 client (`@aws-sdk/client-s3` on Node targets or `aws4fetch` on Workers targets). Landed via the infra round 5 spec (ratified 2026-09-06) as track T-2.
+
+- 21 contributions: 6 REQs on facade sole-reader / put-get-delete-list / presigned URL / multipart / lifecycle events / credential-pair discipline; 8 USs at 28101-28108; 3 TACs (2901 facade, 2902 multipart uploader, 2903 event sink); 4 ADRs (2901 adapter elicited between AWS SDK and aws4fetch, 2902 presigned TTL default 15 minutes floor 1 minute, 2903 multipart threshold default 8 MiB, 2904 objectStorageContract with scope global).
+- Six Node-only probes under `contributions/probes/` proven against a live MinIO container: `facade-round-trip`, `put-get-round-trip`, `presigned-url`, `multipart-upload`, `event-secrecy`, and the accountBound `r2-real-account-smoke`. The R2 smoke records `accountBoundSkipped: true` when `CI_HAS_CLOUDFLARE_ACCOUNT` is unset per spec section 3.5.
+- T-2 slice of the shared sample-app fixture at `packages/rcf-lite/test/fixtures/infra-s3-and-queue/` boots MinIO via docker compose, exposes the facade over `@aws-sdk/client-s3`, ships a security-secrets-management shim realising the `secretRef` opaque-string contract, and hosts four wired induced-failure switches for the negative-run paths (SIMULATE_MINIO_DOWN, SIMULATE_403_ON_GET, SIMULATE_PART_UPLOAD_FAIL, SIMULATE_PRESIGN_MALFORMED).
+- Declares `capabilities: ["objectStorage"]`, `suggestedCompanions: [{role: "logging"}, {role: "errorHandling"}]`, `providesRoles` absent, `requiresAppliedCapabilities` absent.
+- Contributes ADR-2904 as `scope: global` on new topic `objectStorageContract`. Future non-S3-shape siblings (`object-storage-native-gcs`, `object-storage-native-azure`, reserved slugs) conflict here by design.
+- Refuses composition when `security-secrets-management` v1.0.1+ is not applied. Declares `requiresAppliedCapabilities: {capabilities: ["secretsProvider"], allowSkipFlag: "allow-no-secrets-yet", refusalMessageId: "object-storage-s3-no-secrets"}` per the T-5 capability mechanism. `rcf define blueprint add object-storage-s3` on a bare project exits 3 with `[object-storage-s3-no-secrets]` on stderr, names the shipped predecessor, and points at the override. `--allow-no-secrets-yet` records a `notes` line on `rcf/blueprints/object-storage-s3.applied.json` for later reconciliation. Companion runner extensions (added by this PR to keep the mechanism whole): `src/blueprint/capabilities.js` `buildRefusalMessage` gains a bespoke template branch for `object-storage-s3-no-secrets` (echoes the message id as the first-line tag; other refusalMessageId values also gain a `[<id>]` tag on the first line of the generic fallback for dashboards/lint); `src/cli/blueprint.js` accepts the new `--allow-no-secrets-yet` flag; `src/blueprint/apply.js` sidecar `notes` prose derives predecessor family from the `allowSkipFlag` name (auth vs secrets-management) so the note reads sensibly for either predecessor.
+- Every ADR contribution entry on `blueprint.json` carries a `standardsTraceClause` per section 8a.2 (per HQ mid-flight ruling after PR #154 gate).

package/blueprints/object-storage-s3/README.md

@@ -0,0 +1,108 @@
+# object-storage-s3
+
+Object storage on the S3 API, accessed through a store facade that is the sole reader of the S3 client. Cloudflare R2 is the first adapter, MinIO is the local dev target, any S3-compatible remote (AWS S3, Backblaze B2, Wasabi, self-hosted) composes cleanly. Ships put / get / delete / list, presigned GET URLs with a bounded TTL, and multipart-upload above an elicited threshold, plus a lifecycle-event sink with a metadata-only field discipline. Refuses composition without `security-secrets-management` applied (Baz decision 6): the credential pair is a `secretRef`, never a value.
+
+## What this blueprint gives you
+
+- **A store facade** (TAC-2901) that is the sole importer of the S3 client (`@aws-sdk/client-s3` on Node targets or `aws4fetch` on Workers targets per ADR-2901) in your source tree, opens the client on boot, and exposes typed named domain verbs. Emits `facadeReady` on the first successful ready-check.
+- **A multipart uploader** (TAC-2902) that the facade delegates to for payloads above the elicited threshold (default 8 MiB per ADR-2903); initiates, part-uploads, completes; aborts in-flight on any part-upload failure so no orphan multipart uploads remain on the bucket.
+- **An event sink** (TAC-2903) with a metadata-only field discipline: `facadeReady`, `objectPut`, `objectDeleted`, `presignedIssued`; no body bytes, no user id, no PII drawn from the object body.
+- **Six Node-only probes** proving every runtime observable: five against a real MinIO container (facade round-trip, put/get, presigned URL, multipart 10 MiB, event secrecy against a PII fixture) plus one accountBound R2 real-account smoke that skips cleanly without `CI_HAS_CLOUDFLARE_ACCOUNT`.
+
+## The six REQs
+
+| REQ | What it commits |
+|---|---|
+| REQ-001 | Facade module is the sole reader of the S3 client; opens on boot; emits `facadeReady`. |
+| REQ-002 | Put / get / delete / list contract on typed keys with `objectPut` and `objectDeleted` events. |
+| REQ-003 | Presigned GET URL with bounded TTL (floor 1 minute, default 15 minutes per ADR-2902); 200 within TTL, 403 after. |
+| REQ-004 | Multipart-upload above the ADR-2903 threshold (default 8 MiB); abort-on-failure with no orphan in-flight uploads. |
+| REQ-005 | Four lifecycle events with metadata-only fields; event-secrecy probe asserts against a PII fixture. |
+| REQ-006 | Credential-pair discipline via `security-secrets-management`; refuses composition without with stable message id `object-storage-s3-no-secrets`. |
+
+## The three TACs
+
+- **TAC-2901 facade**: the object-storage S3 facade module.
+- **TAC-2902 multipart uploader**: initiate/part-upload/complete with abort-on-failure.
+- **TAC-2903 event sink**: metadata-only lifecycle event contract.
+
+## The four ADRs
+
+- **ADR-2901 adapter**: `@aws-sdk/client-s3` on Node targets, `aws4fetch` on Workers targets; elicited, `recommendedDefault: true`. Standards trace clause: AWS S3 API and R2 S3-compatibility notes.
+- **ADR-2902 presigned URL TTL**: default 15 minutes, floor 1 minute; elicited ceiling. Standards trace clause: generic enterprise practice.
+- **ADR-2903 multipart threshold**: default 8 MiB, elicited. Standards trace clause: generic enterprise practice.
+- **ADR-2904 object storage contract** (scope: global, topic `objectStorageContract`): S3 API as the shipped shape; conflicts by design with future non-S3-shape siblings. Standards trace clause: AWS S3 API and R2 S3-compatibility notes.
+
+## Elicited parameters
+
+Endpoint URL (R2 `https://<account-id>.r2.cloudflarestorage.com`, AWS S3 `https://s3.<region>.amazonaws.com`, MinIO `http://localhost:9000`, any S3-compatible remote); bucket name; credential-pair reference via `security-secrets-management` (never value); adapter (`awsSdk` or `aws4fetch`); presigned-URL default TTL (default 15 minutes); presigned-URL ceiling (elicited, no shipped default, S3 API 7-day outer bound); multipart-upload threshold (default 8 MiB); force path style (`true` for MinIO, `false` for AWS/R2 with virtual-hosted style); server-side encryption default (`sseNone` on R2 per the R2 compatibility notes; `sseS3` on AWS S3 when the operator elicits it).
+
+## Companions
+
+- **logging**: every lifecycle event (facadeReady, objectPut, objectDeleted, presignedIssued) writes through the applied logger; a logging companion supplies the factory.
+- **errorHandling**: a put failure, a get 404, a presigned-URL malformed request constructs an internal error record; an error-handling companion supplies the record factory and the boundary.
+
+## Composition and conflicts
+
+Consumes `security-secrets-management` v1.0.1+ for the credential pair. Declares `requiresAppliedCapabilities: {capabilities: ["secretsProvider"], allowSkipFlag: "allow-no-secrets-yet", refusalMessageId: "object-storage-s3-no-secrets"}` per the T-5 capability mechanism (visual round spec 5.5.1). The apply verb refuses on a project without `secretsProvider` (exit 3, stderr carries `[object-storage-s3-no-secrets]` as the first-line tag and names the required capability, the shipped predecessor, and the override flag). `--allow-no-secrets-yet` overrides for a scaffolding pass and records a `notes` line on `rcf/blueprints/object-storage-s3.applied.json` for later reconciliation. Contributes ADR-2904 as `scope: global` on new topic `objectStorageContract`; future `object-storage-native-gcs` or `object-storage-native-azure` siblings would conflict here by design. `capabilities: ["objectStorage"]`; `providesRoles: []`.
+
+## 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 and writes the per-blueprint report at `.rcf/reports/blueprints/object-storage-s3/<probe-name>.json`.
+
+| Probe | Anchor AC | What it proves | accountBound |
+|---|---|---|---|
+| `facade-round-trip` | AC-28101-1 | Facade opens against MinIO; `facadeReady` fires with endpointHost and bucketName. | false |
+| `put-get-round-trip` | AC-28102-1, AC-28102-2, AC-28102-3 | 1 KiB round-trip byte-equal; delete and list round-trip; `objectPut` and `objectDeleted` fire. | false |
+| `presigned-url` | AC-28103-1 | Presign at 60 s TTL returns 200 within TTL, 403 on tampered signature (or full TTL wall-clock with `SIMULATE_PRESIGN_EXPIRE=true`); floor refusal at 30 s. | false |
+| `multipart-upload` | AC-28104-1, AC-28104-2 | 10 MiB payload above the 8 MiB threshold round-trips byte-equal via multipart; no orphan in-flight uploads after complete; abort-on-failure with `SIMULATE_PART_UPLOAD_FAIL=true`. | false |
+| `event-secrecy` | AC-28105-1 | Every event record carries only whitelisted metadata fields; no PII fixture text; no forbidden field name. | false |
+| `r2-real-account-smoke` | AC-28108-1 | Real R2 round-trip when `CI_HAS_CLOUDFLARE_ACCOUNT` is set; records `accountBoundSkipped: true` when it is not. | true |
+
+## How to run the probes locally
+
+```sh
+cd packages/rcf-lite/test/fixtures/infra-s3-and-queue
+docker compose up -d minio
+sleep 4
+npm install --silent
+node src/create-bucket.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-facade-round-trip.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-put-get-round-trip.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-presigned-url.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-multipart-upload.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-event-secrecy.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-r2-real-account-smoke.mjs
+docker compose down -v
+```
+
+Each shim exits 0 on aggregate pass and 1 otherwise; every per-blueprint report at `.rcf/reports/blueprints/object-storage-s3/<probe-name>.json` carries `aggregateVerdict pass` on the canonical fixture state. The R2 smoke exits 0 with `accountBoundSkipped: true` when `CI_HAS_CLOUDFLARE_ACCOUNT` is unset.
+
+## R2 deviations from full S3
+
+Cloudflare R2 is S3-compatible per https://developers.cloudflare.com/r2/api/s3/api/ but explicitly does not implement:
+
+- **ACLs**: no per-object or per-bucket ACLs; permissions go through Cloudflare account roles and bucket-level API tokens.
+- **Bucket policies**: no S3-style JSON bucket policies.
+- **Object Lock**: no WORM or retention hold surface.
+- **Versioning**: no object versioning; a put replaces the object.
+- **Lifecycle policies**: R2 marks lifecycle-configuration surface as "feature implementation is currently in progress"; do not depend on time-based expiration or class transitions on R2 at v1.0.0.
+
+An operator relying on any of the four either picks a different endpoint (AWS S3 covers all four) or handles the equivalent semantics application-side. The guide's "R2 deviations" section names each and points at the vendor doc.
+
+## The multipart re-upload gotcha
+
+Per the R2 doc: re-uploading to the same part number replaces the previous part with loss-on-fail semantics. If a re-upload fails, the original part is gone. The facade avoids the case in the shipped path (part uploads are single-attempt; abort-on-failure covers the mid-multipart failure), but a project that layers its own retry on top of the facade's `putObject` should retry the whole put, not a partial multipart.
+
+## Known mechanism-reach gaps
+
+- **Adapter choice (ADR-2901)** is elicited at apply time; the facade's public surface is adapter-neutral so a consumer cannot tell at import time which adapter was picked. Mitigation: the checklist row on the applied blueprint records the adapter chosen; the shipped Node fixture uses `@aws-sdk/client-s3` for probe verifiability.
+- **Server-side encryption default (elicited)** is set at apply time; the facade does not enforce a shipped default because R2 differs from AWS S3 here (R2: SSE-C only, no AWS KMS; AWS: sseS3 available). Mitigation: the guide's "Encryption at rest" section names the two per-target defaults and the applied ADR records the operator choice.
+- **Multipart part re-upload loss-on-fail** per the R2 doc: the facade avoids the case internally but a consumer-side retry loop can walk into it. Mitigation: the README calls it out; the guide's "Retry semantics" section names the shipped-path guarantees.
+
+## Standards trace
+
+- Cloudflare R2 S3-compatibility surface: https://developers.cloudflare.com/r2/api/s3/api/ (documents supported ops and the four deviations enumerated above; SSE-C only; auto region only).
+- Cloudflare R2 overview and presigned URLs: https://developers.cloudflare.com/r2/ (S3 API, zero egress fees, presigned URLs).
+- MinIO S3 compatibility for local dev: https://docs.min.io/community/minio-object-store/administration/object-management/object-lifecycle-management.html.
+- GitHub Actions service container shape (for the CI seam): https://docs.github.com/en/actions/using-containerized-services/about-service-containers.

package/blueprints/object-storage-s3/blueprint.json

@@ -0,0 +1,72 @@
+{
+  "slug": "object-storage-s3",
+  "version": "1.0.0",
+  "category": "object-storage",
+  "capabilities": ["objectStorage"],
+  "requiresAppliedCapabilities": {
+    "capabilities": ["secretsProvider"],
+    "allowSkipFlag": "allow-no-secrets-yet",
+    "refusalMessageId": "object-storage-s3-no-secrets"
+  },
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every lifecycle event (facadeReady, objectPut, objectDeleted, presignedIssued) writes through the applied logger; a logging companion supplies the factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A put failure, a get 404, a presigned-URL malformed request constructs an internal error record; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "contributions": [
+    { "id": "object-storage-s3-REQ-001", "kind": "req", "path": "requirements/object-storage-s3-req-001.json" },
+    { "id": "object-storage-s3-REQ-002", "kind": "req", "path": "requirements/object-storage-s3-req-002.json" },
+    { "id": "object-storage-s3-REQ-003", "kind": "req", "path": "requirements/object-storage-s3-req-003.json" },
+    { "id": "object-storage-s3-REQ-004", "kind": "req", "path": "requirements/object-storage-s3-req-004.json" },
+    { "id": "object-storage-s3-REQ-005", "kind": "req", "path": "requirements/object-storage-s3-req-005.json" },
+    { "id": "object-storage-s3-REQ-006", "kind": "req", "path": "requirements/object-storage-s3-req-006.json" },
+    { "id": "object-storage-s3-US-28101", "kind": "us", "path": "user-stories/object-storage-s3-us-28101.json" },
+    { "id": "object-storage-s3-US-28102", "kind": "us", "path": "user-stories/object-storage-s3-us-28102.json" },
+    { "id": "object-storage-s3-US-28103", "kind": "us", "path": "user-stories/object-storage-s3-us-28103.json" },
+    { "id": "object-storage-s3-US-28104", "kind": "us", "path": "user-stories/object-storage-s3-us-28104.json" },
+    { "id": "object-storage-s3-US-28105", "kind": "us", "path": "user-stories/object-storage-s3-us-28105.json" },
+    { "id": "object-storage-s3-US-28106", "kind": "us", "path": "user-stories/object-storage-s3-us-28106.json" },
+    { "id": "object-storage-s3-US-28107", "kind": "us", "path": "user-stories/object-storage-s3-us-28107.json" },
+    { "id": "object-storage-s3-US-28108", "kind": "us", "path": "user-stories/object-storage-s3-us-28108.json" },
+    { "id": "TAC-2901-object-storage-s3-facade", "kind": "tac", "path": "tacs/tac-2901-object-storage-s3-facade.json" },
+    { "id": "TAC-2902-object-storage-s3-multipart-uploader", "kind": "tac", "path": "tacs/tac-2902-object-storage-s3-multipart-uploader.json" },
+    { "id": "TAC-2903-object-storage-s3-event-sink", "kind": "tac", "path": "tacs/tac-2903-object-storage-s3-event-sink.json" },
+    {
+      "id": "ADR-2901-object-storage-s3-adapter",
+      "kind": "adr",
+      "path": "adrs/adr-2901-object-storage-s3-adapter.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "AWS S3 API and Cloudflare R2 S3-compatibility notes"
+    },
+    {
+      "id": "ADR-2902-object-storage-s3-presigned-ttl-floor",
+      "kind": "adr",
+      "path": "adrs/adr-2902-object-storage-s3-presigned-ttl-floor.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2903-object-storage-s3-multipart-threshold",
+      "kind": "adr",
+      "path": "adrs/adr-2903-object-storage-s3-multipart-threshold.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2904-object-storage-s3-contract",
+      "kind": "adr",
+      "path": "adrs/adr-2904-object-storage-s3-contract.json",
+      "scope": "global",
+      "topic": "objectStorageContract",
+      "standardsTraceClause": "AWS S3 API and Cloudflare R2 S3-compatibility notes"
+    }
+  ]
+}

package/blueprints/object-storage-s3/contributions/adrs/adr-2901-object-storage-s3-adapter.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-2901-object-storage-s3-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "S3 client adapter: @aws-sdk/client-s3 on Node targets; aws4fetch on Workers targets; elicited",
+  "context": "A project deploying object storage on an S3-shape endpoint has two mainstream client choices for the two dominant deploy targets. On Node targets, @aws-sdk/client-s3 (the modular AWS JavaScript SDK v3) is the reference client with a mature multipart transferer, presigned URL helper, and Cloudflare R2 compatibility. On Cloudflare Workers targets, aws4fetch is the lightweight fetch-native client that avoids the AWS SDK's Node polyfills and ships tiny. Both speak the S3 wire protocol; both handle SigV4; both cover the ops the v1.0.0 facade surface needs (PutObject, GetObject, DeleteObject, ListObjectsV2, presigned URL via query-string, CreateMultipartUpload / UploadPart / CompleteMultipartUpload / AbortMultipartUpload). The v1.0.0 facade design has to hold the adapter reference opaque at the facade boundary so the operator picks per deploy target and a future adapter (a GCS shim, an Azure Blob shim under a sibling blueprint) slots in without a facade re-shape.",
+  "decision": "The shipped v1.0.0 default on a Node target is @aws-sdk/client-s3 (AWS SDK v3, modular client-s3 package). The shipped v1.0.0 default on a Workers target is aws4fetch. Both are elicited at apply time under the adapter parameter; the operator picks based on the deploy target. Every S3 request goes through the elicited client; the facade module is the sole importer of either package in the source tree per REQ-001. The adapter reference is OPAQUE at this ADR: the facade imports the elicited adapter at the top of the module and any consumer wanting a different adapter (a GCS shim, an Azure Blob shim inside a sibling blueprint that mints on demand) replaces the import here without touching the outward interface.",
+  "consequences": "The project inherits the elicited adapter's mature request-signing surface, its presigned-URL helper, and its multipart-upload transferer. Standards trace clause: AWS S3 API (the de facto interop standard, no single normative RFC) and the Cloudflare R2 S3-compatibility notes at https://developers.cloudflare.com/r2/api/s3/api/ enumerating the supported ops (PutObject, GetObject, DeleteObject, ListObjectsV2, HeadObject, HeadBucket, CopyObject, multipart upload, ListMultipartUploads) and the deviations (no ACLs, no bucket policies, no Object Lock, no versioning, no lifecycle policies, SSE-C only). Projects deploying to MinIO for local dev pick the AWS SDK adapter transparently; MinIO covers the S3 surface for the shipped ops per the MinIO S3 compatibility posture at https://docs.min.io/community/minio-object-store/administration/object-management/object-lifecycle-management.html. A future GCS or Azure Blob sibling mints on demand under a different global topic on objectStorageContract (ADR-2904); the operator resolution surfaces as a topic conflict per the round-2 pattern.",
+  "alternativesConsidered": [
+    {
+      "name": "aws-sdk v2 as the shipped Node default",
+      "summary": "Ship the monolithic aws-sdk v2 npm package as the Node default.",
+      "reasonNotChosen": "aws-sdk v2 is in maintenance mode as of 2024; the modular v3 package @aws-sdk/client-s3 is the recommended surface for new work and ships smaller. Choosing v2 would drag every consumer to a maintenance-mode dependency at v1.0.0."
+    },
+    {
+      "name": "aws4fetch as the shipped Node default too",
+      "summary": "Ship aws4fetch on both Node and Workers targets to shrink the dependency footprint.",
+      "reasonNotChosen": "aws4fetch is fetch-native and Workers-friendly but lacks the presigned-URL helper and the multipart transferer the v1.0.0 REQ-003 and REQ-004 need out of the box; a Node target picking aws4fetch would need consumer-side glue for both, defeating the value of the shipped facade."
+    },
+    {
+      "name": "Ship a hand-rolled SigV4 signer with fetch",
+      "summary": "Roll our own SigV4 signer as the v1.0.0 default and skip both AWS SDK and aws4fetch.",
+      "reasonNotChosen": "SigV4 is well-specified but the surface area (request signing, presigned URL, multipart) exceeds a shelf blueprint's maintenance envelope. Two mature adapters exist; picking one per target and eliciting is the shelf pattern."
+    }
+  ],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/adrs/adr-2902-object-storage-s3-presigned-ttl-floor.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2902-object-storage-s3-presigned-ttl-floor",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Presigned-URL default TTL 15 minutes, floor 1 minute, ceiling elicited",
+  "context": "A presigned URL is the S3-shape mechanism for delegating read access to an object without handing out credentials. The URL carries a bounded TTL after which the storage endpoint refuses the request with 403 (S3 AccessDenied; MinIO returns a 403 XML with AccessDenied code; the R2 shape matches). Too-short a TTL and legitimate readers miss the window; too-long a TTL and a leaked URL becomes a persistent breach. The AWS SDK's default expires-in value is 900 seconds (15 minutes) which most enterprises match; the S3 API caps SigV4 presigned URLs at 604800 seconds (7 days) though few callers reach that ceiling. Local dev with MinIO handles the full range identically.",
+  "decision": "The shipped default TTL is 15 minutes (900 seconds). The floor is 1 minute (60 seconds); the facade refuses a presign request below the floor with a value error. The ceiling is elicited at apply time (no shipped default) with the S3 API's own 7-day ceiling as the outer bound; the operator picks a shorter cap when their threat model calls for it. Every presignedIssued event carries the ttl value used so downstream logging can flag long-lived URLs.",
+  "consequences": "The default is the AWS SDK's own default; most consumer code needs no override. Standards trace clause: generic enterprise practice (no single normative RFC for presigned URL TTL; the S3 API's 7-day ceiling is the outer bound). The 1-minute floor is a defensive against copy-paste ADRs that drift TTL toward seconds; a legitimate short-TTL use case (a 30-second CDN-signed URL) is handled by a dedicated CDN blueprint, not by object-storage-s3. Operators who want a longer default author a project-level ADR overriding the elicited ceiling; the shipped default stays at 15 minutes.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship a shorter default (5 minutes)",
+      "summary": "Ship 5 minutes as the default TTL, matching the tightest common threat model.",
+      "reasonNotChosen": "5 minutes trips legitimate browser-side retries and long-form downloads on slow connections; the AWS SDK's own default of 15 minutes has years of production burn-in without visible complaints."
+    },
+    {
+      "name": "Ship no floor",
+      "summary": "Let the operator set any TTL >= 1 second, matching the SDK's own minimum.",
+      "reasonNotChosen": "A 1-second TTL is a footgun for the copy-paste ADR class of failure; the 1-minute floor is a small defensive with no measured cost."
+    }
+  ],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}