rcf-lite 0.22.0 → 0.24.0

package/blueprints/messaging-queue-cloudflare/contributions/probes/retry-and-dlq.mjs

@@ -0,0 +1,87 @@
+/**
+ * Retry-and-dlq probe.
+ *
+ * Publishes 1 message with SIMULATE_CONSUMER_RETRY forcing the consumer
+ * to return retry on every delivery. Drives the loop through max_retries
+ * redeliveries, asserts DLQ landing at attempt count 4 (attempts=4 on
+ * the DLQ entry because retry increments the counter before overflow),
+ * asserts messageDeadLettered fires with the same stable message-id,
+ * inspects the DLQ contents, asserts body byte-equal.
+ *
+ * Anchors AC-29103-1, AC-29104-1.
+ *
+ * Q3 default per spec section 10: this refusal-style probe asserts
+ * BOTH exit code AND stable message id. Exit code lands via the shim's
+ * aggregate-verdict->exit mapping; message-id equality lands here.
+ */
+
+import { createQueuePair } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/queue-driver.mjs';
+import { createProducer, queueConfigFromEnv } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/producer.mjs';
+import { createConsumer, drainLoop } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/consumer.mjs';
+import { createDlqInspector } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/dlq-inspector.mjs';
+
+export default async function runProbe() {
+  const cfg = queueConfigFromEnv();
+  const maxRetries = cfg.maxRetries;
+  const pair = createQueuePair({ queueName: cfg.queueName, dlqName: cfg.dlqName, maxRetries });
+  const events = [];
+  const producer = createProducer({
+    binding: pair.producer,
+    queueName: cfg.queueName,
+    onEvent: (e) => events.push(e),
+  });
+  await producer.ready;
+
+  const body = { note: 'permanent-failure' };
+  const { id: publishedId } = await producer.publish(body, { headers: { 'x-trace-id': 'trace-retry-and-dlq' } });
+
+  const seenAttempts = [];
+  const consumer = createConsumer({
+    handler: async (msg) => {
+      seenAttempts.push({ id: msg.id, attempts: msg.attempts });
+      return 'retry';
+    },
+    onEvent: (e) => events.push(e),
+    env: { SIMULATE_CONSUMER_RETRY: 'true' },
+  });
+  await drainLoop({ consumer, driver: pair, dlqSink: { baseline: [], onEvent: (e) => events.push(e) } });
+
+  const inspector = createDlqInspector({ driver: pair });
+  const dlqEntries = await inspector.list();
+
+  const results = [];
+
+  // AC-29103-1: attempts observed 1..maxRetries with same stable message-id.
+  const idsAcrossAttempts = seenAttempts.map((a) => a.id);
+  const attemptsSeq = seenAttempts.map((a) => a.attempts);
+  const ac29103Pass = idsAcrossAttempts.every((id) => id === publishedId) &&
+    attemptsSeq.length === maxRetries &&
+    attemptsSeq.every((a, i) => a === i + 1);
+  results.push({
+    anchorAcId: 'AC-29103-1',
+    verdict: ac29103Pass ? 'pass' : 'fail',
+    detail: ac29103Pass
+      ? `same messageId=${publishedId} seen across attempts ${attemptsSeq.join(',')}`
+      : `retry-trajectory wrong: ids=${JSON.stringify(idsAcrossAttempts)} attempts=${JSON.stringify(attemptsSeq)}`,
+  });
+
+  // AC-29104-1: DLQ landing at overflow (attempts > maxRetries),
+  //             messageDeadLettered event fires with same stable id,
+  //             DLQ contents match body.
+  const deadLetterEvents = events.filter((e) => e.event === 'messageDeadLettered');
+  const dlqEntry = dlqEntries.find((e) => e.id === publishedId);
+  const ac29104Pass = deadLetterEvents.length === 1 &&
+    deadLetterEvents[0].messageId === publishedId &&
+    deadLetterEvents[0].attempts === maxRetries + 1 &&
+    !!dlqEntry &&
+    JSON.stringify(dlqEntry.body) === JSON.stringify(body);
+  results.push({
+    anchorAcId: 'AC-29104-1',
+    verdict: ac29104Pass ? 'pass' : 'fail',
+    detail: ac29104Pass
+      ? `DLQ landing observed: messageDeadLettered messageId=${publishedId} attempts=${deadLetterEvents[0].attempts}; DLQ contents body byte-equal`
+      : `DLQ landing wrong: deadLetterEvents=${JSON.stringify(deadLetterEvents)} dlqEntries=${JSON.stringify(dlqEntries)}`,
+  });
+
+  return results;
+}

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

@@ -0,0 +1,5 @@
+import runProbe from './event-secrecy.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'queues', image: 'cloudflare/wrangler-dev-equivalent (in-memory driver)', healthy: true };
+runShim('event-secrecy', engine, runProbe);

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

@@ -0,0 +1,11 @@
+/**
+ * Shim: run producer-facade-ready against the fixture's in-memory
+ * queue-driver seam and write
+ * .rcf/reports/blueprints/messaging-queue-cloudflare/producer-facade-ready.json.
+ */
+
+import runProbe from './producer-facade-ready.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'queues', image: 'cloudflare/wrangler-dev-equivalent (in-memory driver)', healthy: true };
+runShim('producer-facade-ready', engine, runProbe);

package/blueprints/messaging-queue-cloudflare/contributions/probes/run-publish-to-delivery.mjs

@@ -0,0 +1,5 @@
+import runProbe from './publish-to-delivery.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'queues', image: 'cloudflare/wrangler-dev-equivalent (in-memory driver)', healthy: true };
+runShim('publish-to-delivery', engine, runProbe);

package/blueprints/messaging-queue-cloudflare/contributions/probes/run-real-account-concurrency-smoke.mjs

@@ -0,0 +1,5 @@
+import runProbe from './real-account-concurrency-smoke.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'queues', image: 'cloudflare/queues (accountBound)', healthy: true };
+runShim('real-account-concurrency-smoke', engine, runProbe);

package/blueprints/messaging-queue-cloudflare/contributions/probes/run-retry-and-dlq.mjs

@@ -0,0 +1,5 @@
+import runProbe from './retry-and-dlq.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'queues', image: 'cloudflare/wrangler-dev-equivalent (in-memory driver)', healthy: true };
+runShim('retry-and-dlq', engine, runProbe);

package/blueprints/messaging-queue-cloudflare/contributions/requirements/messaging-queue-cloudflare-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "messaging-queue-cloudflare-REQ-001",
+  "prdId": "PRD-001",
+  "title": "One producer facade module is the sole reader of the Cloudflare Queues binding and opens on boot with producerReady",
+  "description": "The application publishes to the queue through a single producer facade module in the project's source tree that is the ONLY module holding a reference to the Cloudflare Queues binding (env.RCF_TEST_QUEUE in the fixture; the elicited binding name in a real project). Every other module that publishes reads the facade and calls its typed domain verbs (publish, publishBatch); no other module dereferences the raw Queues binding. On process boot, the facade opens against the bound queue and, once ready, emits a producerReady lifecycle event carrying the queue name. The queue name (or the binding name in a Workers deploy) is elicited at apply time under the Queues binding declared in wrangler config.",
+  "category": "functional",
+  "domain": "messaging",
+  "priority": "must",
+  "rationale": "One producer facade means one place to hold the vendor surface (the Queues binding), one place to serialise pre-ready publishes, one place to wire the lifecycle-event sink, and one place a future adapter swap (a native postgres-shape queue, an AWS SQS shim under a sibling blueprint) lands without moving any AC. Multiple call sites reaching into the raw binding produces a codebase where the ready-check semantics, the message-id contract, and the trace-id propagation are all diffused across the tree.",
+  "tags": [
+    "blueprint:messaging-queue-cloudflare",
+    "category:01-facade"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/requirements/messaging-queue-cloudflare-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "messaging-queue-cloudflare-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Publish, consume and ack with stable message-id and producer-supplied trace-id",
+  "description": "The producer facade publishes messages with a stable message-id assigned by the Cloudflare Queues platform on send and a producer-supplied trace-id carried in the message headers. The consumer, registered on the Worker's queue handler, reads a batch of messages, dispatches each to the registered handler, acknowledges each per message on successful return, and returns retry when the handler throws a retryable error. The received body equals the published body byte-for-byte; the received headers include both the stable message-id and the producer-supplied trace-id. Publish is idempotent from the producer's point of view within a single facade instance (an application layer that reissues a publish for the same domain event gets a new message-id, per the at-least-once shape).",
+  "category": "functional",
+  "domain": "messaging",
+  "priority": "must",
+  "rationale": "Publish, consume, ack is the minimum useful contract for a directed producer-to-consumer worklist. The stable message-id enables the consumer to record what it processed for downstream dedup; the producer-supplied trace-id crosses process boundaries so the request that enqueued a job is stitchable to the run that processed it, which the observability-logging companion consumes when applied.",
+  "tags": [
+    "blueprint:messaging-queue-cloudflare",
+    "category:02-transport"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/requirements/messaging-queue-cloudflare-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "messaging-queue-cloudflare-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Retry contract: consumer returning retry re-delivers with an incremented attempt counter",
+  "description": "When the registered consumer returns retry on a message (or when the handler throws a retryable error the facade classifies as such), Cloudflare Queues re-delivers the same stable message-id, and every subsequent delivery observes an incremented attempt counter on the message envelope. Consumer code inspects the attempt counter through the facade's consumer surface and can decide policy (log a warning at attempt 2, alert at attempt N-1). Re-delivery preserves body, headers and trace-id byte-for-byte; the same message-id is what identifies the same message across attempts.",
+  "category": "functional",
+  "domain": "messaging",
+  "priority": "must",
+  "rationale": "A retry contract with an observable attempt counter is what turns transient failures (a downstream 502, a database deadlock, a rate-limit) into eventual success without human intervention, and what turns permanent failures into dead-lettering with an evidence trail. Without the attempt counter, either the consumer retries forever silently or the consumer gives up on the first failure; both are worse than the shipped shape.",
+  "tags": [
+    "blueprint:messaging-queue-cloudflare",
+    "category:03-retry"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/requirements/messaging-queue-cloudflare-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "messaging-queue-cloudflare-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Dead-letter contract: elicited max-attempts default 3, DLQ retention 4 days, dead_letter_queue field on the consumer",
+  "description": "After the elicited max-attempts (default 3 per the Cloudflare Queues documented default) is reached on a message, the message lands on the configured dead-letter queue (DLQ) and the facade fires messageDeadLettered on the sink with the stable message-id, the queue name, and the terminal attempt count. The DLQ is declared per-consumer in wrangler config through the dead_letter_queue field (per https://developers.cloudflare.com/queues/configuration/dead-letter-queues/); the field syntax in wrangler.toml is dead_letter_queue = \"<dlq-queue-name>\" alongside max_retries on the [[queues.consumers]] block. The DLQ retention defaults to 4 days when no active consumer is attached per the same Cloudflare DLQ documentation. Consumer code can attach a DLQ consumer to drain the DLQ (via wrangler queues consumer add) for inspection or replay per the same Cloudflare DLQ documentation.",
+  "category": "functional",
+  "domain": "messaging",
+  "priority": "must",
+  "rationale": "A DLQ contract with a bounded retention and an observable landing event is what stops a bad message from blocking the queue indefinitely, and gives the operator a receipt for the failure. The 4-day retention default matches the Cloudflare Queues DLQ documentation and is long enough for a human to inspect, short enough that the DLQ does not become a silent archive.",
+  "tags": [
+    "blueprint:messaging-queue-cloudflare",
+    "category:04-dead-letter"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/requirements/messaging-queue-cloudflare-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "messaging-queue-cloudflare-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Batch consume: elicited batch size default 10 max 100, batch timeout default 5 seconds max 60 seconds",
+  "description": "The consumer reads messages in batches whose size is elicited (default 10, bounded above by the Cloudflare max 100 messages per batch per https://developers.cloudflare.com/queues/platform/limits/) and whose batch-timeout (batch wait) is elicited (default 5 seconds, bounded above by the Cloudflare max 60 seconds per the same limits doc). Batch settings live on the [[queues.consumers]] block in wrangler config as max_batch_size and max_batch_timeout. When the batch is full or the timeout fires, the Worker's queue handler receives the whole batch in one invocation; the facade dispatches per-message to the registered handler and acknowledges per-message. A batch member returning retry does not roll the whole batch back; only that message is redelivered.",
+  "category": "functional",
+  "domain": "messaging",
+  "priority": "must",
+  "rationale": "Per-message ack in a batch invocation is what enables the retry-and-DLQ contract to compose with batched delivery; without it a single bad message poisons the whole batch. The elicited defaults sit well below the Cloudflare maxes so the facade shape stays composable when a project runs closer to the ceiling.",
+  "tags": [
+    "blueprint:messaging-queue-cloudflare",
+    "category:05-batch"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/requirements/messaging-queue-cloudflare-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "messaging-queue-cloudflare-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Lifecycle events with metadata-only fields: producerReady, messagePublished, messageAcked, messageDeadLettered",
+  "description": "The facade fires four lifecycle events on the injected event sink: producerReady (once per facade instance, on the first successful ready-check), messagePublished (once per successful publish), messageAcked (once per successful ack), messageDeadLettered (once per DLQ landing). Every event record carries a metadata-only field whitelist: messageId, queueName, attempts (integer, 0 for producerReady and messagePublished), timestamp (ISO 8601 UTC). No event record contains the message body, any header value, any consumer-context field, or any producer-context field. The whitelist is enforced in code (the sink adapter refuses forbidden fields); a call site that hands a body-bearing payload to the sink is refused at author-side review.",
+  "category": "functional",
+  "domain": "messaging",
+  "priority": "must",
+  "rationale": "A metadata-only event whitelist is what turns the event sink into a leak-proof observability seam. The applied logging companion writes these records verbatim; the applied error-handling companion constructs error records from messageDeadLettered records. Neither ever sees the message body through this surface, which is what allows the shipped shape to compose with a PII-bearing body without redaction gymnastics at every log site.",
+  "tags": [
+    "blueprint:messaging-queue-cloudflare",
+    "category:06-events"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/tacs/tac-3001-messaging-queue-cloudflare-producer-facade.json

@@ -0,0 +1,56 @@
+{
+  "tacId": "TAC-3001-messaging-queue-cloudflare-producer-facade",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Messaging-queue-cloudflare producer facade",
+  "purpose": "The single project-side module that dereferences the Cloudflare Queues binding (env.<queueBinding>), exposes narrow named domain verbs (publish, publishBatch) to consumer code, and emits structured lifecycle events to the event sink (TAC-3003). Consumers never touch the raw binding outside this module; the facade is the one place the vendor surface lives. The adapter reference is opaque at this boundary so a Workers-side native adapter, a future sibling (an SQS shim, the reserved messaging-queue-postgres sibling) or a fixture-time in-memory adapter slots in without a facade re-shape.",
+  "responsibilities": [
+    "Open the producer on boot against the elicited queue binding; hold no other reference to the Queues vendor surface; export no symbol that leaks the raw binding (AC-29101-1, AC-29101-2).",
+    "Expose named domain verbs (publish, publishBatch) as named exports with typed parameters; refuse a raw-binding passthrough on the public surface (AC-29102-1).",
+    "Emit producerReady exactly once per facade instance on the injected event sink with the queueName (AC-29101-1); serialise pre-ready publishes behind the ready-check.",
+    "Emit messagePublished per publish and messageAcked per successful consumer return, both metadata-only per TAC-3003 (AC-29102-1, AC-29102-2, AC-29105-1).",
+    "Attach a producer-supplied trace-id to the message headers on every publish so downstream consumers can stitch enqueue-to-process (AC-29102-1)."
+  ],
+  "internalStructure": "One module exporting a createProducer({ binding, queueName, adapter, onEvent }) factory returning a Producer whose methods are the named domain verbs. The binding dereference lives at the top of this module; the factory captures the binding, wires the sink, and hands back closures. Consumers destructure the verbs they need at their top level and hold the facade reference for the process lifetime.",
+  "interfaces": [
+    {
+      "name": "createProducer",
+      "kind": "factory",
+      "description": "createProducer({ binding, queueName, adapter, onEvent }) -> Producer. The sole entry point every publisher calls. Opens against the binding; wires the sink; hands back a Producer whose methods are the named domain verbs."
+    },
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with { event, ts, messageId, queueName, attempts } for producerReady, messagePublished, messageAcked, messageDeadLettered events. Never invoked with message body values, header values or consumer-context fields."
+    },
+    {
+      "name": "producer.verbs",
+      "kind": "read-write-api",
+      "description": "The named domain verbs the facade exposes: publish(body, headers), publishBatch(messages)."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Consumer registration",
+      "kind": "tac",
+      "tacId": "TAC-3002-messaging-queue-cloudflare-consumer-registration",
+      "description": "The consumer surface on the Worker queue handler that pairs with this producer; both share the sink and the queueName."
+    },
+    {
+      "name": "Event sink",
+      "kind": "tac",
+      "tacId": "TAC-3003-messaging-queue-cloudflare-event-sink",
+      "description": "The lifecycle-event sink contract the facade emits through with metadata-only field discipline."
+    },
+    {
+      "name": "Queue binding via deploy-cloudflare-workers",
+      "kind": "external",
+      "description": "The applied deploy-cloudflare-workers blueprint supplies the wrangler config in which the queue binding is declared; the facade reads the binding at boot. Composition is transitive through the wrangler binding, not through the capability mechanism, so no requiresAppliedCapabilities block is declared."
+    }
+  ],
+  "tradeoffs": "The facade holds a single Producer instance per queue at v1.0.0; a project publishing to multiple queues creates multiple facade instances. The adapter reference is opaque at ADR-3001 so a future SQS shim, an in-memory adapter, or the reserved messaging-queue-postgres sibling slots in as a per-target module swap; the outward interface stays unchanged.",
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/tacs/tac-3002-messaging-queue-cloudflare-consumer-registration.json

@@ -0,0 +1,40 @@
+{
+  "tacId": "TAC-3002-messaging-queue-cloudflare-consumer-registration",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Messaging-queue-cloudflare consumer registration on the Worker queue handler",
+  "purpose": "The consumer registration surface on the Worker's queue handler that pairs with the producer facade (TAC-3001). Reads a batch of messages from the batch envelope, dispatches per-message to the registered handler, acknowledges per-message on success, returns retry on retryable failure, and drives the retry-to-DLQ trajectory bounded by the elicited max-attempts (ADR-3003) and batch settings (ADR-3004).",
+  "responsibilities": [
+    "Provide createConsumer({ handler, onEvent }) returning a queue-handler function (env, ctx) that reads the batch envelope, dispatches per-message, and acks or retries per return (AC-29102-2, AC-29103-1, AC-29105-1).",
+    "Expose the elicited batch size (max_batch_size default 10, ceiling 100) and batch timeout (max_batch_timeout default 5 seconds, ceiling 60 seconds) as parameters realised through wrangler config on the [[queues.consumers]] block (AC-29105-1).",
+    "Classify a handler throw as retryable or terminal and re-deliver retryable throws via return retry with the attempt counter increment observable on subsequent deliveries (AC-29103-1).",
+    "Emit messageDeadLettered on the sink when the DLQ landing observation surfaces (via a Worker DLQ-consumer wiring the fixture DLQ-inspector helper exercises for the shipped shape) (AC-29104-1)."
+  ],
+  "internalStructure": "One module exporting createConsumer({ handler, onEvent }) that returns a queue handler (batch, env, ctx). The handler shape matches the Cloudflare Queues Worker queue-handler contract per https://developers.cloudflare.com/queues/configuration/javascript-apis/#consumer. Per-message ack semantics come from the message envelope's ack and retry methods.",
+  "interfaces": [
+    {
+      "name": "createConsumer",
+      "kind": "factory",
+      "description": "createConsumer({ handler, onEvent }) -> (batch, env, ctx) => Promise<void>. The exported queue handler the Worker registers under the [triggers] queue binding. The handler is invoked once per delivered message and returns a value used to classify success/retry/terminal."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Producer facade",
+      "kind": "tac",
+      "tacId": "TAC-3001-messaging-queue-cloudflare-producer-facade",
+      "description": "The producer this consumer pairs with; both share the sink and the queueName."
+    },
+    {
+      "name": "Event sink",
+      "kind": "tac",
+      "tacId": "TAC-3003-messaging-queue-cloudflare-event-sink",
+      "description": "The lifecycle-event sink contract the consumer emits through with metadata-only field discipline."
+    }
+  ],
+  "tradeoffs": "Per-message ack over batch-level ack matches Cloudflare's Queues Worker queue-handler contract; a batch-level rollback would be simpler but would poison-batch every peer of a single bad message and defeat the DLQ contract. The elicited batch defaults sit well below Cloudflare's maxes so tightening in a project is a config change, not a code change.",
+  "createdAt": "2026-09-06T21:00:00.000Z",
+  "updatedAt": "2026-09-06T21:00:00.000Z"
+}

package/blueprints/messaging-queue-cloudflare/contributions/tacs/tac-3003-messaging-queue-cloudflare-event-sink.json

@@ -0,0 +1,39 @@
+{
+  "tacId": "TAC-3003-messaging-queue-cloudflare-event-sink",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Messaging-queue-cloudflare lifecycle event sink",
+  "purpose": "The metadata-only lifecycle event sink surface both the producer facade (TAC-3001) and the consumer registration (TAC-3002) emit through. Fires four events (producerReady, messagePublished, messageAcked, messageDeadLettered) with a rigid field whitelist; the whitelist is enforced in code so a call site handing a body-bearing payload to the sink is refused by the sink adapter before the record leaves the module.",
+  "responsibilities": [
+    "Expose an onEvent callback shape { event, ts, messageId, queueName, attempts } to the facade and consumer registration (AC-29106-1).",
+    "Enforce the field whitelist: exactly {event, ts, messageId, queueName, attempts} are allowed on every record; any additional field on the payload is stripped at the sink boundary and the sink adapter surfaces a soft warning if a caller attempts to hand it a body-bearing payload (AC-29106-1).",
+    "Never invoke the callback with body bytes, header values, consumer-context fields, producer-context fields, or PII from the fixture body (AC-29106-1)."
+  ],
+  "internalStructure": "One module exporting createSinkAdapter({ onEvent }) that wraps the caller's onEvent with the field-whitelist filter. The wrapped adapter is what the producer facade and the consumer registration receive; the raw onEvent is never invoked from inside the facade or the consumer.",
+  "interfaces": [
+    {
+      "name": "createSinkAdapter",
+      "kind": "factory",
+      "description": "createSinkAdapter({ onEvent }) -> (record) => void. Filters record fields to the whitelist and passes the filtered record to the caller-supplied onEvent."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Producer facade",
+      "kind": "tac",
+      "tacId": "TAC-3001-messaging-queue-cloudflare-producer-facade",
+      "description": "Emits producerReady, messagePublished, messageAcked through the sink adapter."
+    },
+    {
+      "name": "Consumer registration",
+      "kind": "tac",
+      "tacId": "TAC-3002-messaging-queue-cloudflare-consumer-registration",
+      "description": "Emits messageDeadLettered through the sink adapter after the DLQ landing observation surfaces."
+    }
+  ],
+  "tradeoffs": "A hard whitelist in code beats a documented-only convention: the sink cannot be misused because the boundary strips forbidden fields before they reach the caller's log. The trade-off is that adding a new whitelist field is a v1.1.0 minor bump, not a project-side config; the shipped shape is deliberate to keep the leak-proof property.",
+  "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-29101.json

@@ -0,0 +1,34 @@
+{
+  "usId": "messaging-queue-cloudflare-US-29101",
+  "prdId": "PRD-001",
+  "reqId": "messaging-queue-cloudflare-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One producer facade module opens the Queues binding on boot and emits producerReady with the queue name",
+  "asA": "developer whose Worker or Node service needs a directed producer-to-consumer worklist behind a swappable boundary",
+  "iWant": "one producer facade module to hold the Cloudflare Queues binding reference and expose typed domain verbs (publish, publishBatch), with a producerReady lifecycle event on the first successful ready-check",
+  "soThat": "the boundary between my domain and the Queues vendor surface is the only place that has to move when the adapter changes, and boot ordering is observable via the event",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-29101-1",
+      "description": "On process boot, the facade opens against the elicited queue binding (env.RCF_TEST_QUEUE on the fixture); once the first successful ready-check returns, a producerReady event fires on the injected event sink with a payload containing queueName. The facade exposes typed named domain verbs (publish, publishBatch) and does not re-export the raw Queues binding.",
+      "given": "a Worker or Node process with the facade module imported and its factory invoked with the elicited binding and queue name",
+      "when": "the process boots and the facade ready-check returns",
+      "then": "a producerReady event fires on the injected event sink with a payload containing queueName; the facade exposes named domain verbs (publish, publishBatch) and does not re-export the raw Queues binding",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-29101-2",
+      "description": "Exactly one source-tree module inside the facade directory holds the reference to the Cloudflare Queues binding (env.RCF_TEST_QUEUE in the fixture); every other module that publishes imports the facade and calls its named domain verbs, verified by a targeted grep on the applied fixture.",
+      "given": "the applied project's source tree after apply",
+      "when": "grep for a Queues binding dereference walks the tree outside the facade directory",
+      "then": "no match is found outside the facade directory; the facade's public surface exports named domain verbs only, no raw binding reference",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3001-messaging-queue-cloudflare-producer-facade"],
+  "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-29102.json

@@ -0,0 +1,34 @@
+{
+  "usId": "messaging-queue-cloudflare-US-29102",
+  "prdId": "PRD-001",
+  "reqId": "messaging-queue-cloudflare-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Publish delivers to the consumer with matching body, message-id and producer-supplied trace-id",
+  "asA": "developer publishing a domain event through the producer facade",
+  "iWant": "a message published through publish() to reach the registered consumer with body byte-equal and headers including a stable message-id and my producer-supplied trace-id",
+  "soThat": "downstream traceability across the enqueue-to-process boundary is a byte-for-byte property, not a hopeful convention",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-29102-1",
+      "description": "Given a message published through the facade with a producer-supplied trace-id in headers, when the consumer subscribes on the same queue, then the received body equals the published body byte-for-byte and the received headers include the stable message-id assigned by the platform on send plus the producer-supplied trace-id, verified across all five messages in the publish-to-delivery probe.",
+      "given": "5 messages published through the facade with producer-supplied trace-ids",
+      "when": "the consumer processes the queue batch",
+      "then": "all 5 messages are received with body byte-equal, message-id present and stable per message across the delivery, and the producer-supplied trace-id present on the message headers",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-29102-2",
+      "description": "Given a successful consumer return on a message, when the facade dispatches the batch, then a messageAcked event fires on the injected sink with messageId and queueName matching the received message; the message is not redelivered on subsequent batches.",
+      "given": "a message delivered to the registered consumer",
+      "when": "the consumer returns success",
+      "then": "a messageAcked event fires with messageId and queueName; the message is not redelivered",
+      "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-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"
+}