rcf-lite 0.22.0 → 0.24.0

package/blueprints/jobs-background/README.md

@@ -0,0 +1,105 @@
+# jobs-background v1.0.0
+
+Background-jobs discipline over an applied `queue` capability. Ships a job-definition contract, a POSIX-cron plus one-shot-delayed scheduler, a retry contract that inherits the applied queue's max-attempts ceiling, and a metadata-only run-log event stream at four moments. Composes on the T-5 capability-consumer mechanism from the visual round; refuses apply on a bare project with exit 3 and the stable message id `jobs-background-no-queue` per Baz decision 5 on the ratified round-5 spec.
+
+## What this gives you
+
+- A job-definition module shape you export from `./jobs/*.mjs`: `{ name, handler, inputSchema, retryPolicy, timeoutMs }`.
+- A scheduler with POSIX cron and one-shot-delayed shapes, elicited across `inProcess` (a Node long-lived process), `workerCron` (Cloudflare Cron Triggers) and `external` (a Kubernetes CronJob, a systemd timer, GitHub Actions schedule). A `workflows` mode is reserved for the v1.1.0 minor per section 5.7 of the spec.
+- A retry contract that inherits the applied queue's max-attempts ceiling (Cloudflare Queues at 100 per the T-3 messaging-queue-cloudflare ADR-3003) and expresses the elicited backoff shape (`exponential`, `constant`, `linear`).
+- A metadata-only run-log at four moments (`jobScheduled`, `jobStarted`, `jobCompleted`, `jobFailed`). Record whitelist: `{ jobId, jobName, attempts, duration, timestamp }` plus optional `terminalErrorCode`. No job input, no handler output, no user id, no email, no SSN, ever.
+- An operator-facing surface elicited across `cli`, `httpEndpoint`, or `none`. The blueprint ships the contract; the applying project builds the thin shim.
+
+## The six REQs
+
+| REQ | Contract |
+|---|---|
+| `jobs-background-REQ-001` | Requires an applied `queue` capability; refuses apply on a bare project with exit 3 and the stable message id `jobs-background-no-queue`. |
+| `jobs-background-REQ-002` | Job-definition contract: name, handler, input schema (opaque per project), retry policy, timeout. |
+| `jobs-background-REQ-003` | Scheduler contract: POSIX cron string and one-shot delayed. |
+| `jobs-background-REQ-004` | Retry contract: handler throws retryable error re-delivers via the applied queue; max-attempts elicited within the applied queue's own ceiling. |
+| `jobs-background-REQ-005` | Job-run event log: `jobScheduled`, `jobStarted`, `jobCompleted`, `jobFailed`; metadata-only whitelist. |
+| `jobs-background-REQ-006` | Operator-facing surface (elicited): `cli`, `httpEndpoint`, or `none`. |
+
+## Capability composition
+
+`requiresAppliedCapabilities` on `blueprint.json`:
+
+```json
+{
+  "capabilities": ["queue"],
+  "allowSkipFlag": "allow-no-queue-yet",
+  "refusalMessageId": "jobs-background-no-queue"
+}
+```
+
+Apply refuses on a bare project (no applied blueprint declares `capabilities: ["queue"]`) with exit 3 and the stable first-line tag `[jobs-background-no-queue]`. The refusal message explicitly names `messaging-queue-cloudflare` as the shipped provider and `--allow-no-queue-yet` as the override.
+
+The `--allow-no-queue-yet` override records a note on the sidecar `rcf/blueprints/jobs-background.applied.json` (`notes: "no queue yet: applied under --allow-no-queue-yet; surfaces gated on queue will refuse at runtime until a queue blueprint is applied."`). Note: the spec section 5.4 prose reference to `manifest.blueprints[jobs-background].source.notes` is superseded by the shipped T-5 mechanism which writes the note on the sidecar because the applied-blueprint-record schema in rcf-schemas 0.6.1 is closed and cannot carry a `notes` field. `rcf define validate` reads the sidecar to flag surfaces that never activated.
+
+## Scheduler mode ADR (ADR-3102)
+
+Scheduler mode is elicited across three values at v1.0.0 and reserves a fourth for v1.1.0:
+
+- `inProcess`: a long-lived Node process holding `setInterval` per cron string and `setTimeout` per one-shot delay. Fits Node-server deploys; unsuitable for Cloudflare Workers.
+- `workerCron`: Cloudflare Cron Triggers wire the scheduled event to a Worker handler that publishes to the applied queue, per the Cloudflare Cron Triggers documentation. Cron-trigger semantics are per-cron-string on the Worker's wrangler config, not per-job-cron on the runtime; the guide names the alignment. Refuses `workerCron` when the applied queue has no cron surface.
+- `external`: an external cron runner (Kubernetes CronJob, GitHub Actions schedule, systemd timer) invokes an operator surface with a fire-now command.
+- Reserved `workflows` (v1.1.0): wraps the same job-definition contract with Cloudflare Workflows `step.do` orchestration per section 5.7 of the spec and the round-6 proposal decision (b). Adds one enum value at ADR-3102 and one section to the guide; no facade re-shape.
+
+## Timeout ceiling (ADR-3104)
+
+Default handler `timeoutMs` is 60000 (60 seconds); floor is 1000 (1 second); ceiling is bounded by the applied queue's consumer wall-clock. Cloudflare Queues caps consumer wall-clock at 15 minutes per the platform limits documentation; a job-definition module declaring a `timeoutMs` above the ceiling refuses at boot with a clear error naming the ceiling and the applied provider.
+
+## Companions and capabilities
+
+- `capabilities: ["backgroundJobs"]` (per section 6a of `packages/rcf-lite/docs/blueprint-authoring.md`; a consumer blueprint reads this capability to obtain the job-definition and scheduler surfaces at apply time).
+- `providesRoles`: absent.
+- `suggestedCompanions`:
+  - `logging`: every `jobStarted` / `jobCompleted` / `jobFailed` event writes through the applied logger; a logging companion supplies the factory.
+  - `errorHandling`: a `jobFailed` constructs an internal error record with the terminal error code and the correlation id; an error-handling companion supplies the record factory and the boundary.
+
+## The five probes
+
+Each probe module lives under `contributions/probes/` and exports the spec section 3.2 verdict envelope with an `anchorAcId` matching a contributed AC id on the blueprint. Each has a matching `run-<probe-name>.mjs` shim writing a per-blueprint report at `.rcf/reports/blueprints/jobs-background/<probe-name>.json` per spec section 3.4.
+
+- `apply-time-refusal.mjs` (anchors `AC-jobs-requiresQueue`): invokes `rcf define blueprint add ./blueprints/jobs-background` against a bare Node scratch fixture with NO queue applied; asserts exit 3, greps stderr for the first-line tag `[jobs-background-no-queue]`, greps stderr for the explicit provider name `messaging-queue-cloudflare` and the override flag `--allow-no-queue-yet`. Q3 default per spec section 10: asserts BOTH exit code AND stable message id.
+- `apply-time-override.mjs` (anchors `AC-jobs-overrideRecorded`): same bare scratch fixture, but with `--allow-no-queue-yet`; asserts exit 0 and the sidecar `rcf/blueprints/jobs-background.applied.json` records `slug: jobs-background`, `allowNoAuthYet: true`, `appliedCapabilities: []`, and a `notes` field containing `no queue yet` and `--allow-no-queue-yet` and `queue` (but not the auth or secrets-management family words).
+- `fake-clock-cron.mjs` (anchors `AC-jobs-scheduledRunsOnCron`): with `messaging-queue-cloudflare` and `jobs-background` both applied on the shared sample-app fixture, drives the fixture's fake-clock scheduler through one POSIX cron minute for the refresh-cache job; asserts `jobStarted` fires within the elicited `fireToleranceMs` window (default 30000 ms) and `jobCompleted` fires within the elicited `timeoutMs` (10000 ms for refresh-cache).
+- `retry-and-fail.mjs` (anchors `AC-jobs-retryOnHandlerFailure`): with `SIMULATE_HANDLER_THROW=true` on the fixture, schedules a send-welcome-email job (`maxAttempts: 3`), drives the queue through re-deliveries; asserts three `jobStarted` events fire with the same `jobId` and attempts counter 1, 2, 3, followed by a terminal `jobFailed` with a `terminalErrorCode`.
+- `event-secrecy.mjs` (anchors `AC-jobs-eventSecrecy`): with `SIMULATE_PII_IN_JOB_INPUT=true` on the fixture, schedules a job with a PII fixture input `{ userId: 1234, ssn: "123-45-6789", email: "test@example.com" }`; drives to completion; asserts every event record carries only the whitelist `{ event, jobId, jobName, attempts, duration, timestamp }` (plus optional `terminalErrorCode`) and NO PII literal.
+
+## Running the probes
+
+The probes drive against the shared sample-app fixture at `packages/rcf-lite/test/fixtures/infra-s3-and-queue/` (extended with `jobs/`, `src/jobs-runtime.mjs`, `src/scheduler.mjs`, `src/job-run-log.mjs`). No Docker, no `wrangler dev` process required; the T-3 in-memory queue-driver seam is the shipped local seam per SDR-3-a.
+
+Two-line boot for the two headline probes:
+
+```sh
+node ../../../../blueprints/jobs-background/contributions/probes/run-apply-time-refusal.mjs
+node ../../../../blueprints/jobs-background/contributions/probes/run-fake-clock-cron.mjs
+```
+
+The remaining three shims (`run-apply-time-override.mjs`, `run-retry-and-fail.mjs`, `run-event-secrecy.mjs`) follow the same pattern.
+
+## Elicited parameters
+
+- `jobsDir` (default `./jobs/`).
+- `defaultRetryPolicy` (`{ maxAttempts: 3, backoff: "exponential" }`).
+- `defaultTimeoutMs` (60000).
+- `schedulerMode` (`inProcess` | `workerCron` | `external`; reserved `workflows` at v1.1.0).
+- `operatorSurface` (`cli` | `httpEndpoint` | `none`).
+- `fireToleranceMs` (default 30000).
+
+## Known limitations (per-AC mechanism-reach form, round-3 checklist 6.g)
+
+- AC-jobs-requiresQueue: PROVEN via `apply-time-refusal.mjs` against a bare scratch project on the shipped head (exit code and message id assertions run in-process). No live-only gap.
+- AC-jobs-overrideRecorded: PROVEN via `apply-time-override.mjs` on the shipped head (sidecar note grep asserts `no queue yet`, `--allow-no-queue-yet`, and family word `queue`). No live-only gap.
+- AC-jobs-scheduledRunsOnCron: PROVEN via `fake-clock-cron.mjs` on the shipped head against the in-memory queue-driver seam plus the injected fake-clock scheduler seam. LIVE `wrangler dev` cron-trigger firing under `workerCron` scheduler mode is the HQ gate reviewer's follow-up run per SDR-3-a; the shipped local seam proves the scheduler and runtime dispatch chain without a Cloudflare Queues account.
+- AC-jobs-retryOnHandlerFailure: PROVEN via `retry-and-fail.mjs` on the shipped head (three `jobStarted` records at attempts 1, 2, 3 followed by terminal `jobFailed`). The in-memory queue-driver's re-delivery loop matches Cloudflare Queues' retry semantics per T-3's opaque-adapter clause; a live-account run against Cloudflare Queues is the T-3 real-account concurrency smoke's territory, not T-4's.
+- AC-jobs-eventSecrecy: PROVEN via `event-secrecy.mjs` on the shipped head (grep on the serialised run-log stream returns zero matches for every PII fixture literal). No live-only gap; the whitelist enforcement lives in code, not in a runtime environment.
+- `workerCron` refuses on an applied queue with no cron surface: DOCUMENTED at ADR-3102 in this blueprint's contribution set; not exercised at v1.0.0 because the shipped provider (`messaging-queue-cloudflare` v1.0.0) does not itself claim a cron surface (the cron surface is Workers-side per Cloudflare Cron Triggers, not Queues-side). A follow-up train fires the refusal live once a `queue`-capability provider with a cron surface ships.
+- Reserved v1.1.0 `workflows` scheduler mode: DOCUMENTED at ADR-3102; the `fake-clock-cron.mjs` probe grows a `workflows-scheduler` variant when the v1.1.0 minor lands per section 5.7 of the spec.
+
+## Reserved v1.1.0 minor: Workflows adapter
+
+The v1.1.0 minor adds a fourth `scheduler` value (`workflows`) at ADR-3102, wrapping the same job-definition contract with Cloudflare Workflows `step.do` orchestration per section 5.7 of the spec. No topic conflict (the `backgroundJobModel` topic answer stays retry-and-schedule), no facade re-shape. Adds one section to this guide.

package/blueprints/jobs-background/blueprint.json

@@ -0,0 +1,149 @@
+{
+  "slug": "jobs-background",
+  "version": "1.0.0",
+  "category": "jobs",
+  "capabilities": [
+    "backgroundJobs"
+  ],
+  "requiresAppliedCapabilities": {
+    "capabilities": [
+      "queue"
+    ],
+    "allowSkipFlag": "allow-no-queue-yet",
+    "refusalMessageId": "jobs-background-no-queue"
+  },
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every jobStarted / jobCompleted / jobFailed event writes through the applied logger; a logging companion supplies the factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A jobFailed constructs an internal error record with the terminal error code and the correlation id; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "contributions": [
+    {
+      "id": "jobs-background-REQ-001",
+      "kind": "req",
+      "path": "requirements/jobs-background-req-001.json"
+    },
+    {
+      "id": "jobs-background-REQ-002",
+      "kind": "req",
+      "path": "requirements/jobs-background-req-002.json"
+    },
+    {
+      "id": "jobs-background-REQ-003",
+      "kind": "req",
+      "path": "requirements/jobs-background-req-003.json"
+    },
+    {
+      "id": "jobs-background-REQ-004",
+      "kind": "req",
+      "path": "requirements/jobs-background-req-004.json"
+    },
+    {
+      "id": "jobs-background-REQ-005",
+      "kind": "req",
+      "path": "requirements/jobs-background-req-005.json"
+    },
+    {
+      "id": "jobs-background-REQ-006",
+      "kind": "req",
+      "path": "requirements/jobs-background-req-006.json"
+    },
+    {
+      "id": "jobs-background-US-30101",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30101.json"
+    },
+    {
+      "id": "jobs-background-US-30102",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30102.json"
+    },
+    {
+      "id": "jobs-background-US-30103",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30103.json"
+    },
+    {
+      "id": "jobs-background-US-30104",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30104.json"
+    },
+    {
+      "id": "jobs-background-US-30105",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30105.json"
+    },
+    {
+      "id": "jobs-background-US-30106",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30106.json"
+    },
+    {
+      "id": "jobs-background-US-30107",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30107.json"
+    },
+    {
+      "id": "jobs-background-US-30108",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30108.json"
+    },
+    {
+      "id": "jobs-background-US-30109",
+      "kind": "us",
+      "path": "user-stories/jobs-background-us-30109.json"
+    },
+    {
+      "id": "TAC-3101-jobs-background-job-definition",
+      "kind": "tac",
+      "path": "tacs/tac-3101-jobs-background-job-definition.json"
+    },
+    {
+      "id": "TAC-3102-jobs-background-scheduler",
+      "kind": "tac",
+      "path": "tacs/tac-3102-jobs-background-scheduler.json"
+    },
+    {
+      "id": "TAC-3103-jobs-background-run-log",
+      "kind": "tac",
+      "path": "tacs/tac-3103-jobs-background-run-log.json"
+    },
+    {
+      "id": "ADR-3101-jobs-background-model",
+      "kind": "adr",
+      "path": "adrs/adr-3101-jobs-background-model.json",
+      "scope": "global",
+      "topic": "backgroundJobModel",
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-3102-jobs-background-scheduler-mode",
+      "kind": "adr",
+      "path": "adrs/adr-3102-jobs-background-scheduler-mode.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "Cloudflare Cron Triggers documented worker cron surface"
+    },
+    {
+      "id": "ADR-3103-jobs-background-requires-applied-capabilities",
+      "kind": "adr",
+      "path": "adrs/adr-3103-jobs-background-requires-applied-capabilities.json",
+      "recommendedDefault": true,
+      "elicited": false,
+      "standardsTraceClause": "visual round spec section 5.5.2 (the T-5 capability-consumer mechanism)"
+    },
+    {
+      "id": "ADR-3104-jobs-background-timeout-floor",
+      "kind": "adr",
+      "path": "adrs/adr-3104-jobs-background-timeout-floor.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "Cloudflare Queues consumer wall-clock ceiling per platform limits doc"
+    }
+  ]
+}

package/blueprints/jobs-background/contributions/adrs/adr-3101-jobs-background-model.json

@@ -0,0 +1,27 @@
+{
+  "adrId": "ADR-3101-jobs-background-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "scope": "global",
+  "topic": "backgroundJobModel",
+  "title": "Background-job model: retry-and-schedule as the shipped shape (scope global, new topic backgroundJobModel)",
+  "context": "A background-job discipline ships one of several models at the shipped-shape boundary: retry-and-schedule (cron + one-shot delayed, per-message retry, terminal DLQ) as this blueprint ships; stateful-workflow (Temporal-shape or Airflow-shape durable execution with multi-step state); durable-execution (Cloudflare Workflows step.do orchestration). The retry-and-schedule model composes cleanly on an applied queue capability; a stateful-workflow sibling would own its own persistent state store and its own scheduling contract. jobs-background claims the backgroundJobModel topic at scope global so future stateful-workflow siblings (a Temporal-shape or Airflow-shape blueprint) surface a DELIBERATE conflict and the operator picks one per project via a project-level ADR.",
+  "decision": "The shipped v1.0.0 shape is retry-and-schedule. The scheduler contract (POSIX cron plus one-shot delayed per REQ-003) and the retry contract (per-message re-delivery within the applied queue's max-attempts ceiling per REQ-004) are the two axes; the run-log at four moments per REQ-005 is the observability surface. The backgroundJobModel topic scope is global on this blueprint; the topic string is backgroundJobModel (lower camel case, one concept per topic, no version suffix, per the round-2 rules-for-new-topics clause). The round-6 Workflows adapter (per spec section 5.7 and round-6 decision (b)) lives INSIDE this blueprint as a v1.1.0 minor scheduler-mode value (workflows) at ADR-3102, not as a sibling; the topic backgroundJobModel is NOT re-claimed by the workflows mode. A future stateful-workflow sibling (a Temporal-shape blueprint) claims backgroundJobModel with a different answer and forces a DELIBERATE conflict.",
+  "consequences": "The applying project gets a retry-and-schedule background-job surface with metadata-only observability. Standards trace clause: generic enterprise practice for the job-definition and scheduler contracts. Future stateful-workflow siblings (Temporal-shape, Airflow-shape) will surface DELIBERATE conflicts on this topic; the operator resolves by picking one background-job model per project via a project-level ADR. The round-6 Workflows minor bump inside jobs-background is NOT a sibling; it is an elicited scheduler-mode value at ADR-3102 that keeps the backgroundJobModel topic answer unchanged.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship stateful-workflow as the v1.0.0 default",
+      "summary": "Ship a Temporal-shape durable execution model as the primary v1.0.0 background-job surface with multi-step state.",
+      "reasonNotChosen": "Temporal-shape workflows require a persistent state store the applying project has to host; the round-5 shipped shape targets a directed producer-to-consumer worklist behind an applied queue. Stateful-workflow is a future sibling on the same topic, not the v1.0.0 default."
+    },
+    {
+      "name": "Ship durable-execution (Cloudflare Workflows) as the v1.0.0 default",
+      "summary": "Ship Cloudflare Workflows step.do as the primary v1.0.0 scheduler.",
+      "reasonNotChosen": "Cloudflare Workflows is a Cloudflare-only orchestration; the round-5 shipped shape targets a portable retry-and-schedule model over an applied queue capability that any queue provider can supply. Workflows is a scheduler-mode alternative at ADR-3102 (reserved for v1.1.0), not a topic-claim alternative."
+    }
+  ],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/adrs/adr-3102-jobs-background-scheduler-mode.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-3102-jobs-background-scheduler-mode",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Scheduler mode elicited: inProcess, workerCron, external (workflows reserved for v1.1.0)",
+  "context": "The scheduler surface can be realised in three shipped shapes today and a fourth shipped shape at v1.1.0. inProcess: a long-lived Node process (setInterval per cron string, setTimeout per one-shot delay) publishing to the applied queue. workerCron: Cloudflare Cron Triggers wire the scheduled event to a Worker handler that publishes to the applied queue (see the Cloudflare Cron Triggers documentation as the vendor reference for the fields at Cron Triggers, worker-side scheduled handler surface). external: an external cron runner (a Kubernetes CronJob, a GitHub Actions schedule, a systemd timer) invokes an operator surface (or the Node process boot line) with a fire-now command. The v1.1.0 minor per section 5.7 of the spec adds a workflows value that wraps the job-definition contract inside Cloudflare Workflows step.do orchestration; the v1.0.0 facade keeps the mode ELICITED so the fourth enum value slots in without a facade re-shape.",
+  "decision": "The scheduler mode is elicited at apply time between inProcess, workerCron and external. The default recommendation (recommendedDefault: true, elicited: true) is inProcess for a Node long-lived server, workerCron for a Cloudflare Worker deploy, and external for a fleet of short-lived containers already carrying an external cron runner. When the applied queue provider has no cron surface at all (which Cloudflare Queues does not directly; the cron surface is on Cloudflare Workers, not on Queues), workerCron mode refuses at apply time and the guide names the alignment. The v1.1.0 minor bump adds a workflows value; the standardsTraceClause of the contribution entry cites the Cloudflare Cron Triggers documented worker cron surface.",
+  "consequences": "The applying project picks a scheduler mode per environment. Standards trace clause: Cloudflare Cron Triggers documented worker cron surface. workerCron mode inherits Cloudflare cron-trigger semantics (per-cron-string on the Worker's wrangler config, not per-job-cron on the runtime); the guide names this alignment. external mode carries no lock-in but shifts the schedule discipline into the external runner; the guide names the trade-off. The reserved v1.1.0 workflows value carries the durable-execution semantics per the round-6 Workflows adapter proposal.",
+  "alternativesConsidered": [
+    {
+      "name": "Hard-code inProcess as the shipped v1.0.0 default with no elicit",
+      "summary": "Ship inProcess as the only supported scheduler mode at v1.0.0.",
+      "reasonNotChosen": "A Cloudflare Worker deploy has no long-lived setInterval; hard-coding inProcess would refuse composition on the applied deploy-cloudflare-workers target the shared fixture uses. The elicited mode makes the shipped facade portable across the Node long-lived and Worker-cron shapes."
+    },
+    {
+      "name": "Ship the reserved workflows mode at v1.0.0",
+      "summary": "Include the Cloudflare Workflows step.do orchestration inline in the v1.0.0 shipped shape.",
+      "reasonNotChosen": "The round-6 Workflows adapter is on Baz per section 5.7 of the spec; v1.0.0 keeps the mode ELICITED at three values and the v1.1.0 minor adds workflows as the fourth. No topic conflict, no facade re-shape."
+    }
+  ],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/adrs/adr-3103-jobs-background-requires-applied-capabilities.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-3103-jobs-background-requires-applied-capabilities",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Requires capabilities: [queue] with allowSkipFlag allow-no-queue-yet and refusalMessageId jobs-background-no-queue",
+  "context": "jobs-background composes on an applied queue capability. Applying on a bare project (no queue provider applied) has two possible shapes: refuse-with-message (the T-5 capability-consumer mechanism, ratified for application-admin-console and object-storage-s3), or silently apply with a stub queue (which would leave the applying project with an unactivated job dispatch surface). Baz decision 5 (verbatim): jobs requires an applied queue and refuses on a bare project, with an override flag.",
+  "decision": "The blueprint declares requiresAppliedCapabilities { capabilities: [queue], allowSkipFlag: allow-no-queue-yet, refusalMessageId: jobs-background-no-queue }. The apply verb refuses with exit 3 and the first-line stderr tag [jobs-background-no-queue] when no applied blueprint declares capabilities: [queue]. The refusal message names the shipped provider messaging-queue-cloudflare and the override flag --allow-no-queue-yet explicitly per Q3 default. The override writes a sidecar note under the queue family on rcf/blueprints/jobs-background.applied.json so rcf define validate later flags surfaces that never activated. Because the applied-blueprint-record schema in rcf-schemas 0.6.1 is closed, the note lives on the sidecar (rcf/blueprints/<slug>.applied.json), not on manifest.blueprints[].source.notes; the shipped T-5 mechanism (T-2 precedent for object-storage-s3) is the source of truth for that placement.",
+  "consequences": "The applying project's apply-time behaviour is predictable: refuse on bare, override-with-note or apply-with-queue. Standards trace clause: visual round spec section 5.5.2 (the T-5 capability-consumer mechanism). Dashboards and lints bind to the stable message id jobs-background-no-queue. The queue-family family derivation in the sidecar-notes construction (packages/rcf-lite/src/blueprint/apply.js buildOverrideNote) is extended to detect queue from the flag name so the note reads 'no queue yet' (not 'no auth yet' or 'no secrets-management yet').",
+  "alternativesConsidered": [
+    {
+      "name": "Silently apply on a bare project with a stub queue",
+      "summary": "Ship a no-op in-memory queue as the default when no queue capability is applied.",
+      "reasonNotChosen": "A silent stub loses the observability the T-5 mechanism gives; a project would ship jobs against a no-op queue without realising it. Baz decision 5 (verbatim) forecloses this."
+    },
+    {
+      "name": "Refuse on a bare project without an override flag",
+      "summary": "Refuse composition and require the applied queue before any apply call succeeds.",
+      "reasonNotChosen": "The scaffolding case (a project mid-migration that wants the jobs surface staged before the queue provider is picked) needs a documented escape hatch; the sidecar note lets rcf define validate later flag the gap so the scaffolding stays honest."
+    }
+  ],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/adrs/adr-3104-jobs-background-timeout-floor.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-3104-jobs-background-timeout-floor",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Handler timeout: default 60 seconds, floor 1 second, ceiling bounded by the applied queue's consumer wall-clock",
+  "context": "A background-job handler has a bounded wall-clock in the applied queue's consumer. Cloudflare Queues caps consumer wall-clock at 15 minutes (900 seconds) per the platform limits documentation; a handler that runs past that mark is force-killed by the platform regardless of what timeoutMs the job-definition module declared. The jobs runtime enforces its own timeoutMs on the handler and treats a timed-out handler as a retryable error (a jobStarted followed by a jobFailed with retryable code, and the applied queue re-delivers per the retry contract).",
+  "decision": "The default handler timeoutMs is 60000 (60 seconds); the floor is 1000 (1 second); the ceiling is elicited per applied queue provider. For Cloudflare Queues the ceiling is 900000 (15 minutes) per the platform limits documentation. Job-definition modules that declare a timeoutMs above the ceiling refuse at boot with a clear error naming the ceiling and the applied provider. The elicited timeoutMs on a job definition is applied within the ceiling.",
+  "consequences": "The applying project inherits a handler-timeout discipline that respects the applied queue's own wall-clock. Standards trace clause: Cloudflare Queues consumer wall-clock ceiling per platform limits doc. A handler that needs longer than the applied provider's ceiling is a shape mismatch; the answer is either to split the handler into a state-machine driven by re-enqueues, or (at v1.1.0) adopt the workflows scheduler mode which lifts the per-run wall-clock via durable execution.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship a fixed 5-minute default timeout with no elicit",
+      "summary": "Hard-code a 5-minute default timeout on every job definition.",
+      "reasonNotChosen": "A shipped default of 60 seconds forces the applying project to make timeout an explicit choice on any long-running handler, which is the right posture for a shipped facade. 60 seconds is a common-enough handler wall-clock that most simple handlers do not need to opt out."
+    },
+    {
+      "name": "Ceiling as a global constant per shipped provider",
+      "summary": "Bake the 15-minute Cloudflare Queues ceiling into the blueprint code.",
+      "reasonNotChosen": "The ceiling depends on the applied queue provider; a future messaging-queue-postgres sibling would carry a different consumer wall-clock. The elicited ceiling per provider keeps the answer where the transport authority lives."
+    }
+  ],
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/probes/apply-time-override.mjs

@@ -0,0 +1,95 @@
+/**
+ * Apply-time override probe.
+ *
+ * Invokes rcf define blueprint add ./blueprints/jobs-background
+ * --allow-no-queue-yet on a fresh scratch project WITH NO applied queue
+ * provider. Asserts exit 0, asserts rcf/blueprints/jobs-background
+ * .applied.json exists with allowNoAuthYet true, appliedCapabilities [],
+ * and notes containing 'no queue yet' + '--allow-no-queue-yet' + 'queue'
+ * (but NOT 'no auth yet' nor 'no secrets-management yet').
+ *
+ * Anchors AC-jobs-overrideRecorded.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { PROJECT_ROOT } from './probe-utils.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BLUEPRINT_DIR = resolve(HERE, '..', '..');
+const RCF_BIN = resolve(PROJECT_ROOT, 'packages/rcf-lite/bin/rcf.js');
+
+function runNode(args, opts = {}) {
+  return new Promise((resolveP) => {
+    const child = spawn(process.execPath, args, { stdio: ['ignore', 'pipe', 'pipe'], ...opts });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
+    child.stderr.on('data', (b) => { stderr += b.toString('utf8'); });
+    child.on('close', (code) => resolveP({ code, stdout, stderr }));
+  });
+}
+
+export default async function runProbe() {
+  const scratch = await mkdtemp(join(tmpdir(), 'jobs-bg-override-'));
+  try {
+    const init = await runNode([RCF_BIN, 'init'], { cwd: scratch });
+    if (init.code !== 0) {
+      return [{
+        anchorAcId: 'AC-jobs-overrideRecorded',
+        verdict: 'fail',
+        detail: `rcf init failed exit=${init.code} stderr=${init.stderr}`,
+      }];
+    }
+    const apply = await runNode(
+      [RCF_BIN, 'define', 'blueprint', 'add', BLUEPRINT_DIR, '--allow-no-queue-yet'],
+      { cwd: scratch },
+    );
+    if (apply.code !== 0) {
+      return [{
+        anchorAcId: 'AC-jobs-overrideRecorded',
+        verdict: 'fail',
+        detail: `apply --allow-no-queue-yet expected exit 0; got exit=${apply.code} stderr=${apply.stderr}`,
+      }];
+    }
+    // Sidecar path.
+    const sidecarPath = join(scratch, 'rcf', 'blueprints', 'jobs-background.applied.json');
+    try { await stat(sidecarPath); } catch {
+      return [{
+        anchorAcId: 'AC-jobs-overrideRecorded',
+        verdict: 'fail',
+        detail: `sidecar ${sidecarPath} missing after --allow-no-queue-yet apply`,
+      }];
+    }
+    const doc = JSON.parse(await readFile(sidecarPath, 'utf8'));
+    const results = [];
+    const notes = typeof doc.notes === 'string' ? doc.notes : '';
+    const checks = {
+      slug: doc.slug === 'jobs-background',
+      allowNoAuthYet: doc.allowNoAuthYet === true,
+      appliedCapabilitiesEmpty: Array.isArray(doc.appliedCapabilities) && doc.appliedCapabilities.length === 0,
+      notesQueueFamily: notes.includes('no queue yet'),
+      notesOverrideFlag: notes.includes('--allow-no-queue-yet'),
+      notesNamesCapability: notes.includes('queue'),
+      notesNotAuthFamily: !notes.includes('no auth yet'),
+      notesNotSecretsFamily: !notes.includes('no secrets-management yet'),
+    };
+    const pass = Object.values(checks).every(Boolean);
+    results.push({
+      anchorAcId: 'AC-jobs-overrideRecorded',
+      verdict: pass ? 'pass' : 'fail',
+      detail: pass
+        ? `exit=0; sidecar recorded slug=jobs-background allowNoAuthYet=true appliedCapabilities=[]; notes carry 'no queue yet' + '--allow-no-queue-yet' + 'queue' and none of the auth/secrets family words`
+        : `checks=${JSON.stringify(checks)}; notes='${notes}'`,
+    });
+    // Do NOT include the sidecarPath (a per-run tmp path) in the report;
+    // the sidecar contents (doc) is the load-bearing evidence.
+    return { results, extra: { sidecar: doc } };
+  } finally {
+    try { await rm(scratch, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}

package/blueprints/jobs-background/contributions/probes/apply-time-refusal.mjs

@@ -0,0 +1,82 @@
+/**
+ * Apply-time refusal probe.
+ *
+ * Invokes rcf define blueprint add ./blueprints/jobs-background on a
+ * fresh scratch project WITH NO applied queue provider. Asserts exit 3,
+ * greps stderr for [jobs-background-no-queue] tag on the first line,
+ * greps stderr for the explicit provider name messaging-queue-cloudflare,
+ * and greps stderr for the override flag --allow-no-queue-yet.
+ *
+ * Anchors AC-jobs-requiresQueue.
+ *
+ * Q3 default per spec section 10: asserts BOTH exit code AND stable
+ * message id.
+ *
+ * The bare scratch project is created under a scratch tmp directory
+ * (not committed). rcf-lite is invoked via its bin script.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { PROJECT_ROOT } from './probe-utils.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BLUEPRINT_DIR = resolve(HERE, '..', '..');
+const RCF_BIN = resolve(PROJECT_ROOT, 'packages/rcf-lite/bin/rcf.js');
+
+function runNode(args, opts = {}) {
+  return new Promise((resolveP) => {
+    const child = spawn(process.execPath, args, { stdio: ['ignore', 'pipe', 'pipe'], ...opts });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
+    child.stderr.on('data', (b) => { stderr += b.toString('utf8'); });
+    child.on('close', (code) => resolveP({ code, stdout, stderr }));
+  });
+}
+
+export default async function runProbe() {
+  const scratch = await mkdtemp(join(tmpdir(), 'jobs-bg-refuse-'));
+  try {
+    // 1. Init a bare rcf project (no applied blueprints).
+    const init = await runNode([RCF_BIN, 'init'], { cwd: scratch });
+    if (init.code !== 0) {
+      return [{
+        anchorAcId: 'AC-jobs-requiresQueue',
+        verdict: 'fail',
+        detail: `rcf init failed exit=${init.code} stderr=${init.stderr}`,
+      }];
+    }
+    // 2. Attempt to apply jobs-background on the bare project.
+    const apply = await runNode(
+      [RCF_BIN, 'define', 'blueprint', 'add', BLUEPRINT_DIR],
+      { cwd: scratch },
+    );
+    const results = [];
+    const firstLine = apply.stderr.split('\n')[0] ?? '';
+    const tagMatch = firstLine.includes('[jobs-background-no-queue]');
+    const providerMatch = apply.stderr.includes('messaging-queue-cloudflare');
+    const overrideMatch = apply.stderr.includes('--allow-no-queue-yet');
+    const codeMatch = apply.code === 3;
+    const pass = codeMatch && tagMatch && providerMatch && overrideMatch;
+    results.push({
+      anchorAcId: 'AC-jobs-requiresQueue',
+      verdict: pass ? 'pass' : 'fail',
+      detail: pass
+        ? `exit=${apply.code}; stderr first line carries [jobs-background-no-queue] tag; stderr names messaging-queue-cloudflare; stderr names --allow-no-queue-yet`
+        : `expected exit=3 AND first-line tag [jobs-background-no-queue] AND messaging-queue-cloudflare AND --allow-no-queue-yet; got exit=${apply.code}; firstLine='${firstLine}'; tagMatch=${tagMatch}; providerMatch=${providerMatch}; overrideMatch=${overrideMatch}`,
+    });
+    // Do NOT include the scratch dir path in the committed report; it is
+    // a per-run tmp path and would leak the machine's tmp naming into the
+    // gate-time evidence file.
+    return { results, extra: { exitCode: apply.code, stderrFirstLine: firstLine } };
+  } finally {
+    // rm -rf the scratch dir (deletion discipline: literal absolute
+    // scratch path created this call).
+    try { await rm(scratch, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}

package/blueprints/jobs-background/contributions/probes/event-secrecy.mjs

@@ -0,0 +1,69 @@
+/**
+ * Event-secrecy probe.
+ *
+ * Schedules a job whose input carries a PII fixture body
+ * { userId: 1234, ssn: '123-45-6789', email: 'test@example.com' }.
+ * Drives the job through completion. Grep the serialised run-log event
+ * stream for every PII literal; asserts zero matches.
+ *
+ * Anchors AC-jobs-eventSecrecy.
+ */
+
+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 { createRunLog } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/job-run-log.mjs';
+import { loadJobs, createJobsRuntime } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/jobs-runtime.mjs';
+import { createScheduler, createFakeClock } from '../../../../packages/rcf-lite/test/fixtures/infra-s3-and-queue/src/scheduler.mjs';
+import { PROJECT_ROOT } from './probe-utils.mjs';
+import { resolve } from 'node:path';
+
+const PII_LITERALS = ['1234', '123-45-6789', 'test@example.com'];
+const EVENT_WHITELIST = new Set(['event', 'jobId', 'jobName', 'attempts', 'duration', 'timestamp', 'terminalErrorCode']);
+
+export default async function runProbe() {
+  const cfg = queueConfigFromEnv();
+  const pair = createQueuePair({ queueName: cfg.queueName, dlqName: cfg.dlqName, maxRetries: cfg.maxRetries });
+  const events = [];
+  const runLog = createRunLog({ upstream: (e) => events.push(e) });
+  const producer = createProducer({
+    binding: pair.producer,
+    queueName: cfg.queueName,
+    onEvent: () => {},
+  });
+  await producer.ready;
+  const jobsDir = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/infra-s3-and-queue/jobs');
+  const registry = await loadJobs(jobsDir);
+  const runtime = createJobsRuntime({
+    jobRegistry: registry,
+    runLog,
+    env: { SIMULATE_PII_IN_JOB_INPUT: 'true' },
+  });
+  const clock = createFakeClock(0);
+  const scheduler = createScheduler({ mode: 'inProcess', clock, publisher: producer, runLog });
+  scheduler.delayed({
+    jobName: 'send-welcome-email',
+    delayMs: 0,
+    input: { userId: 1234, ssn: '123-45-6789', email: 'test@example.com' },
+  });
+  clock.advance(1);
+  await scheduler.tick();
+  await runtime.drain({ driverState: pair.state, maxIterations: 8 });
+  const serialised = JSON.stringify(events);
+  const leaks = PII_LITERALS.filter((lit) => serialised.includes(lit));
+  const wrongKeys = new Set();
+  for (const ev of events) {
+    for (const k of Object.keys(ev)) {
+      if (!EVENT_WHITELIST.has(k)) wrongKeys.add(k);
+    }
+  }
+  const results = [];
+  const pass = leaks.length === 0 && wrongKeys.size === 0 && events.some((e) => e.event === 'jobCompleted');
+  results.push({
+    anchorAcId: 'AC-jobs-eventSecrecy',
+    verdict: pass ? 'pass' : 'fail',
+    detail: pass
+      ? `no PII literal appears in the serialised run-log stream; every event carries only whitelisted keys ${JSON.stringify([...EVENT_WHITELIST])}; ${events.length} events recorded`
+      : `leaks=${JSON.stringify(leaks)}; wrongKeys=${JSON.stringify([...wrongKeys])}; events=${JSON.stringify(events)}`,
+  });
+  return { results, extra: { events, piiLiterals: PII_LITERALS } };
+}