rcf-lite 0.22.0 → 0.24.0

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

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30103",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Scheduler accepts POSIX cron string and one-shot delayed",
+  "asA": "developer scheduling a job to run every minute (POSIX cron) or once after a delay",
+  "iWant": "the scheduler surface to accept both a POSIX cron string and a one-shot delayed shape (delayMs or fireAt) and publish the corresponding message to the applied queue at the elicited fire time",
+  "soThat": "one contract covers both recurring and deferred sends without a second scheduler surface",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-30103-1",
+      "description": "The scheduler under packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/scheduler.mjs accepts a POSIX cron string on a job definition (refresh-cache.mjs carries cron: '* * * * *') and publishes a message to the applied queue when the fake-clock advances past the fire time. The scheduler also accepts a one-shot delayed schedule (delayMs) and publishes when the fake-clock advances past the fireAt time.",
+      "given": "the fixture scheduler booted in inProcess mode with a fake-clock seam",
+      "when": "the fake clock advances one POSIX cron minute or past a scheduled delayMs",
+      "then": "one message per fire lands on the applied in-memory queue with the target job.name and an ISO-8601 timestamp",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3102-jobs-background-scheduler"],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30104",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Retry: handler throws retryable error re-delivers via applied queue with attempts counter",
+  "asA": "developer authoring a job that can fail transiently",
+  "iWant": "the applied queue to redeliver a failed message per the job's elicited retryPolicy within the applied queue's max-attempts ceiling, with the attempt counter incrementing on each jobStarted event",
+  "soThat": "transient failures self-heal within maxAttempts and terminal failures are recorded once via jobFailed with a terminal error code",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-jobs-retryOnHandlerFailure",
+      "description": "With SIMULATE_HANDLER_THROW=true set on the shared sample-app fixture, the retry-and-fail probe schedules a job whose handler throws a retryable error; the applied in-memory queue redelivers the message per retryPolicy.maxAttempts. Three jobStarted events fire on the sink with the same jobId and attempts counter 1, 2, 3; after the third failure jobFailed fires with a terminal error code and no further re-delivery follows.",
+      "given": "the fixture with SIMULATE_HANDLER_THROW=true and the retry-and-fail probe running against the in-memory queue seam",
+      "when": "the failing job is scheduled",
+      "then": "three jobStarted records with the same jobId and attempts 1,2,3; one jobFailed with a terminalErrorCode; no fourth jobStarted",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3101-jobs-background-job-definition", "TAC-3103-jobs-background-run-log"],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30105",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Job-run event log: four moments with metadata-only whitelist",
+  "asA": "operator observing background-job activity through the run log",
+  "iWant": "each event record to carry only the whitelisted metadata fields { jobId, jobName, attempts, duration, timestamp } (plus terminalErrorCode on jobFailed), and NO job input, NO handler output, NO user id, NO email, NO SSN",
+  "soThat": "domain PII cannot leak through the run log by accident even if the job carries PII in its input by design",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-jobs-eventSecrecy",
+      "description": "With SIMULATE_PII_IN_JOB_INPUT=true set on the shared sample-app fixture, the event-secrecy probe schedules a job whose input carries a PII fixture body { userId: 1234, ssn: '123-45-6789', email: 'test@example.com' } and drives it through completion. Every event record on the sink (jobScheduled, jobStarted, jobCompleted) carries the whitelist { jobId, jobName, attempts, duration, timestamp } and NO input fields, NO output fields, NO literal 1234, NO literal '123-45-6789', NO literal 'test@example.com'.",
+      "given": "the fixture with SIMULATE_PII_IN_JOB_INPUT=true and the event-secrecy probe running against the in-memory queue seam",
+      "when": "the PII-input job is scheduled",
+      "then": "every event record whitelisted; grep on the serialised event stream returns zero matches for the PII fixture text",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3103-jobs-background-run-log"],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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