rcf-lite 0.22.0 → 0.23.0

package/blueprints/jobs-background/contributions/probes/probe-utils.mjs

@@ -0,0 +1,91 @@
+/**
+ * Shared helpers for jobs-background probes.
+ *
+ * Runtime-dependency posture: probes import the fixture's in-memory
+ * queue-driver plus the T-4 jobs-runtime, scheduler and run-log from the
+ * sample-app fixture's src/ tree so rcf-lite itself gains no new runtime
+ * dependency (round-5 spec section 5, brief section 4). The T-3
+ * in-memory queue-driver realises the Cloudflare Queues binding shape;
+ * the T-4 jobs-runtime consumes messages from the driver, dispatches to
+ * job-definition modules, and fires the four lifecycle events on the
+ * T-4-owned run-log sink (whitelist { event, jobId, jobName, attempts,
+ * duration, timestamp } plus optional terminalErrorCode).
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// Project root four levels above blueprints/jobs-background/contributions/probes/
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/infra-s3-and-queue');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/jobs-background');
+
+/**
+ * Compute the aggregate verdict per spec section 3.4:
+ * - fail if any result carries verdict fail
+ * - warn if any result carries verdict warn and no fail
+ * - pass otherwise
+ */
+export function aggregate(results) {
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+
+/**
+ * Write the per-blueprint probe report at
+ * .rcf/reports/blueprints/jobs-background/<probeName>.json
+ * per spec section 3.4.
+ */
+export async function writeReport({ probeName, engine, results, extra = {} }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const report = {
+    slug: 'jobs-background',
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict: aggregate(results),
+    ...extra,
+  };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2), 'utf8');
+  return { report, path };
+}
+
+/**
+ * Drive an async main() and exit 0 on aggregate pass, 1 otherwise.
+ * Prints the report JSON to stdout for the gate-reviewer to read.
+ */
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const { results, extra } = normaliseMain(await mainFn());
+    const { report, path } = await writeReport({ probeName, engine, results, extra });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stdout.write(`report written to ${path}\n`);
+    process.exit(report.aggregateVerdict === 'pass' ? 0 : 1);
+  } catch (err) {
+    const results = [{
+      anchorAcId: 'unknown',
+      verdict: 'fail',
+      detail: `probe threw: ${err && err.message ? err.message : String(err)}`,
+    }];
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${err && err.stack ? err.stack : String(err)}\n`);
+    process.stderr.write(`report written to ${path}\n`);
+    process.exit(1);
+  }
+}
+
+function normaliseMain(value) {
+  if (Array.isArray(value)) return { results: value, extra: {} };
+  if (value && Array.isArray(value.results)) {
+    const { results, ...extra } = value;
+    return { results, extra };
+  }
+  throw new Error('probe main must return an array or an object with a results[] field');
+}

package/blueprints/jobs-background/contributions/probes/retry-and-fail.mjs

@@ -0,0 +1,65 @@
+/**
+ * Retry-and-fail probe.
+ *
+ * With SIMULATE_HANDLER_THROW=true on the shared fixture, the jobs-runtime
+ * throws a retryable error on every dispatch. Schedules a one-shot job
+ * with send-welcome-email's maxAttempts=3. Drives the driver's delivery
+ * loop until the message either terminals or DLQs. Asserts three
+ * jobStarted events with the same jobId and attempts 1, 2, 3 followed by
+ * a terminal jobFailed with a terminalErrorCode.
+ *
+ * Anchors AC-jobs-retryOnHandlerFailure.
+ */
+
+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';
+
+export default async function runProbe() {
+  const cfg = queueConfigFromEnv();
+  // maxRetries on the driver matches send-welcome-email.maxAttempts=3.
+  const pair = createQueuePair({ queueName: cfg.queueName, dlqName: cfg.dlqName, maxRetries: 3 });
+  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_HANDLER_THROW: 'true' },
+  });
+  const clock = createFakeClock(0);
+  const scheduler = createScheduler({ mode: 'inProcess', clock, publisher: producer, runLog });
+  scheduler.delayed({ jobName: 'send-welcome-email', delayMs: 0, input: { userId: 7, email: 'ok@example.com' } });
+  clock.advance(1);
+  await scheduler.tick();
+  await runtime.drain({ driverState: pair.state, maxIterations: 32 });
+  const jobStartedEvents = events.filter((e) => e.event === 'jobStarted' && e.jobName === 'send-welcome-email');
+  const jobFailed = events.find((e) => e.event === 'jobFailed' && e.jobName === 'send-welcome-email');
+  const attemptsSeq = jobStartedEvents.map((e) => e.attempts);
+  const jobIds = new Set(jobStartedEvents.map((e) => e.jobId));
+  const dlqInvoked = pair.state.dlq.length > 0;
+  const results = [];
+  const attemptsOk = attemptsSeq.length === 3 && attemptsSeq[0] === 1 && attemptsSeq[1] === 2 && attemptsSeq[2] === 3;
+  const oneJobId = jobIds.size === 1;
+  const failedOk = !!jobFailed && typeof jobFailed.terminalErrorCode === 'string';
+  const pass = attemptsOk && oneJobId && failedOk;
+  results.push({
+    anchorAcId: 'AC-jobs-retryOnHandlerFailure',
+    verdict: pass ? 'pass' : 'fail',
+    detail: pass
+      ? `three jobStarted events attempts=[1,2,3] same jobId; jobFailed carries terminalErrorCode=${jobFailed.terminalErrorCode}`
+      : `attemptsSeq=${JSON.stringify(attemptsSeq)}; jobIds.size=${jobIds.size}; jobFailed=${JSON.stringify(jobFailed)}`,
+  });
+  return { results, extra: { events, dlqInvoked, attemptsSeq } };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Shim: run apply-time-override against a scratch bare project and
+ * write .rcf/reports/blueprints/jobs-background/apply-time-override.json.
+ */
+
+import runProbe from './apply-time-override.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'cli', tool: 'rcf define blueprint add --allow-no-queue-yet (bare scratch project)', healthy: true };
+runShim('apply-time-override', engine, runProbe);

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

@@ -0,0 +1,11 @@
+/**
+ * Shim: run apply-time-refusal against a scratch project (bare init, no
+ * applied blueprints) and write
+ * .rcf/reports/blueprints/jobs-background/apply-time-refusal.json.
+ */
+
+import runProbe from './apply-time-refusal.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'cli', tool: 'rcf define blueprint add (bare scratch project)', healthy: true };
+runShim('apply-time-refusal', engine, runProbe);

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

@@ -0,0 +1,11 @@
+/**
+ * Shim: run event-secrecy against the fixture jobs-runtime + in-memory
+ * queue seam with a PII fixture input and write
+ * .rcf/reports/blueprints/jobs-background/event-secrecy.json.
+ */
+
+import runProbe from './event-secrecy.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'queues+jobs', image: 'cloudflare/wrangler-dev-equivalent (in-memory driver) + jobs-runtime SIMULATE_PII_IN_JOB_INPUT=true', healthy: true };
+runShim('event-secrecy', engine, runProbe);

package/blueprints/jobs-background/contributions/probes/run-fake-clock-cron.mjs

@@ -0,0 +1,11 @@
+/**
+ * Shim: run fake-clock-cron against the fixture's in-memory queue seam +
+ * fake-clock scheduler + jobs-runtime and write
+ * .rcf/reports/blueprints/jobs-background/fake-clock-cron.json.
+ */
+
+import runProbe from './fake-clock-cron.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'queues+scheduler', image: 'cloudflare/wrangler-dev-equivalent (in-memory driver) + inProcess scheduler with injected fake clock', healthy: true };
+runShim('fake-clock-cron', engine, runProbe);

package/blueprints/jobs-background/contributions/probes/run-retry-and-fail.mjs

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

package/blueprints/jobs-background/contributions/requirements/jobs-background-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "jobs-background-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Requires an applied queue capability; refuses apply on a bare project with exit 3 and the stable message id jobs-background-no-queue",
+  "description": "The jobs-background blueprint composes on an applied queue capability via the T-5 mechanism from the visual round. The apply verb refuses on a bare project (no applied blueprint declares capabilities: [queue]) with exit code 3 and a stable, dashboard-friendly message id jobs-background-no-queue on the first stderr line. The refusal message also names the shipped provider messaging-queue-cloudflare and the override flag --allow-no-queue-yet explicitly, per infra round 5 spec section 10 Q3 default asserting BOTH exit code AND stable message id. The override flag records a note on the sidecar rcf/blueprints/jobs-background.applied.json under the queue family so rcf define validate later flags surfaces gated on queue that never activated.",
+  "category": "functional",
+  "domain": "jobs",
+  "priority": "must",
+  "rationale": "A stable message id is the operator-facing surface an autolint or dashboard binds to; asserting it in the probe pins the id against silent drift. The override flag lets a project scaffold without the queue applied yet, provided the note lands so a later validation pass can flag the gap. The queue provider is named explicitly so an operator hitting the refusal has the shipped answer in hand without a shelf-wide grep.",
+  "tags": [
+    "blueprint:jobs-background",
+    "category:00-composition"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/requirements/jobs-background-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "jobs-background-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Job-definition contract: name, handler, input schema (opaque per project), retry policy, timeout",
+  "description": "A job definition is a module in the applying project's jobs directory (default ./jobs/, elicited at apply time) exporting a shape { name, handler, inputSchema, retryPolicy, timeoutMs }. Name is a stable string; handler is an async function receiving the message body and returning a value or throwing; inputSchema is opaque per project (the applying project's own validation library); retryPolicy is { maxAttempts, backoff }; timeoutMs is a positive integer (default 60000, floor 1000, ceiling bounded by the applied queue consumer wall-clock ceiling per ADR-3104). The jobs runtime registers every job at boot on the applied queue consumer and dispatches by name.",
+  "category": "functional",
+  "domain": "jobs",
+  "priority": "must",
+  "rationale": "A one-shape job definition keeps the discipline uniform across the applying project's job modules; the applying project owns input validation without the blueprint prescribing a validation library.",
+  "tags": [
+    "blueprint:jobs-background",
+    "category:01-definition"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/requirements/jobs-background-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "jobs-background-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Scheduler contract: POSIX cron string and one-shot delayed",
+  "description": "The scheduler surface accepts two schedule shapes: a POSIX cron string (five fields, per POSIX cron) attached to a job definition for recurring runs, and a one-shot delayed schedule with an ISO-8601 fireAt or a positive delayMs. The scheduler publishes a message to the applied queue at the elicited fire time; the jobs runtime consumes and dispatches. The scheduler mode is elicited at apply time under ADR-3102 (inProcess, workerCron, external) and a reserved workflows value ships in the v1.1.0 minor per section 5.7 of the spec.",
+  "category": "functional",
+  "domain": "jobs",
+  "priority": "must",
+  "rationale": "POSIX cron is the widely understood recurring surface; one-shot delayed covers the deferred-send / retry-later case without a second contract. The elicited mode keeps the shipped facade portable across Node long-lived processes, Cloudflare Cron Triggers, and external cron runners without a facade re-shape.",
+  "tags": [
+    "blueprint:jobs-background",
+    "category:02-scheduler"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/requirements/jobs-background-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "jobs-background-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Retry contract: handler throws retryable error re-delivers via the applied queue; max-attempts elicited within the applied queue's own ceiling",
+  "description": "A handler that throws a retryable error causes the applied queue to redeliver the message per its own retry contract; the jobs runtime records the attempt counter on each jobStarted event and inherits max-attempts from the applied queue's own ceiling (Cloudflare Queues ceiling 100 per ADR-3003 in the messaging-queue-cloudflare blueprint). The elicited retryPolicy on a job definition ({ maxAttempts, backoff: constant | exponential | linear }) is applied within that ceiling. After maxAttempts terminal jobStarted events with the same jobId and incrementing attempt counter, jobFailed lands with the terminal error code and no further re-delivery.",
+  "category": "functional",
+  "domain": "jobs",
+  "priority": "must",
+  "rationale": "Retry inheritance from the applied queue keeps the transport authority in one place (the queue's own contract) while letting the job author express the domain retry surface (backoff shape, max-attempts within the ceiling).",
+  "tags": [
+    "blueprint:jobs-background",
+    "category:03-retry"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/requirements/jobs-background-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "jobs-background-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Job-run event log: jobScheduled, jobStarted, jobCompleted, jobFailed with metadata-only fields",
+  "description": "The jobs runtime fires four lifecycle events on the injected event sink: jobScheduled at the moment the scheduler enqueues a message; jobStarted at the moment the consumer begins dispatching a message to a handler; jobCompleted at the moment a handler returns without throwing; jobFailed at the moment the applied queue's max-attempts is exhausted with a terminal error code. Each event record carries only the metadata fields { jobId, jobName, attempts, duration, timestamp } (plus a terminalErrorCode on jobFailed). No job input fields, no handler output fields, no user id, no email, no SSN. The event whitelist is enforced at the sink boundary.",
+  "category": "functional",
+  "domain": "jobs",
+  "priority": "must",
+  "rationale": "A metadata-only event log lets the applying project route the events through its logging surface without leaking domain PII by default. Domain-side observability (recording the input, the output, the error surface) is the applying project's own concern under its logging companion.",
+  "tags": [
+    "blueprint:jobs-background",
+    "category:04-run-log"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/requirements/jobs-background-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "jobs-background-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Operator-facing surface (elicited): cli, httpEndpoint, or none",
+  "description": "The operator-facing surface for triggering ad-hoc runs, inspecting the run log, and re-driving a failed job is elicited at apply time between three shipped shapes: cli (a Node CLI shim the applying project builds against the jobs runtime), httpEndpoint (a small HTTP surface the applying project mounts through its own HTTP shape), or none (no operator surface; the run log is the only observability). The blueprint does not ship the CLI or the HTTP endpoint itself; it ships the contract they build against so the applying project can hoist a thin surface without a facade re-shape.",
+  "category": "functional",
+  "domain": "jobs",
+  "priority": "must",
+  "rationale": "Operator surfaces sit above the run-log contract but their exact shape varies by applying project (CLI-first estates vs HTTP-first APIs). The elicited choice records the answer without prescribing a UI framework or an HTTP router.",
+  "tags": [
+    "blueprint:jobs-background",
+    "category:05-operator-surface"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/tacs/tac-3101-jobs-background-job-definition.json

@@ -0,0 +1,50 @@
+{
+  "tacId": "TAC-3101-jobs-background-job-definition",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Jobs-background job-definition module contract",
+  "purpose": "The shape every job-definition module in the applying project's jobs directory exports. One shape carries name, handler, inputSchema (opaque per project), retryPolicy, and timeoutMs. The jobs runtime registers every job at boot on the applied queue consumer and dispatches by name.",
+  "responsibilities": [
+    "Declare a job by exporting { name, handler, inputSchema, retryPolicy, timeoutMs } (AC-30102-1, AC-jobs-retryOnHandlerFailure).",
+    "Bound handler wall-clock via timeoutMs; jobs runtime cancels a handler that exceeds timeoutMs and treats it as a retryable error (AC-jobs-retryOnHandlerFailure).",
+    "Respect the applied queue's max-attempts ceiling; retryPolicy.maxAttempts must not exceed the ceiling (AC-jobs-retryOnHandlerFailure).",
+    "Refuse composition on a bare project via the requiresAppliedCapabilities gate (AC-jobs-requiresQueue)."
+  ],
+  "internalStructure": "Each job module in the applying project's jobs/ directory (default ./jobs/, elicited) exports a plain object. The jobs runtime scans the directory at boot, validates the shape, and registers handlers keyed by name on the applied queue consumer's dispatch table. Dispatch is by message.name; no runtime type reflection.",
+  "interfaces": [
+    {
+      "name": "jobModule.default",
+      "kind": "shape",
+      "description": "The default export shape: { name: string, handler: async (input) => any, inputSchema: opaque, retryPolicy: { maxAttempts: positive integer, backoff: 'exponential' | 'constant' | 'linear' }, timeoutMs: positive integer }."
+    },
+    {
+      "name": "registerJobs",
+      "kind": "factory",
+      "description": "The jobs runtime entry point: registerJobs({ jobsDir, queueConsumer, onEvent }) reads jobModule files, validates the shape, and registers dispatch handlers."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Scheduler",
+      "kind": "tac",
+      "tacId": "TAC-3102-jobs-background-scheduler",
+      "description": "The scheduler enqueues messages by job name; the job-definition module is the target."
+    },
+    {
+      "name": "Run log",
+      "kind": "tac",
+      "tacId": "TAC-3103-jobs-background-run-log",
+      "description": "The runtime fires the four lifecycle events on the injected event sink for every dispatch."
+    },
+    {
+      "name": "Applied queue capability",
+      "kind": "external",
+      "description": "Composed on the applied blueprint declaring capabilities: [queue] via the T-5 mechanism; refuses apply on a bare project per REQ-001."
+    }
+  ],
+  "tradeoffs": "The v1.0.0 job-definition shape does not prescribe an inputSchema validator; the applying project owns validation. A later minor could add an optional validate hook if a shipped validation library becomes the shelf default. The dispatch table is by job name; two modules exporting the same name collide at boot and refuse.",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/tacs/tac-3102-jobs-background-scheduler.json

@@ -0,0 +1,50 @@
+{
+  "tacId": "TAC-3102-jobs-background-scheduler",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Jobs-background scheduler",
+  "purpose": "The scheduler surface publishes messages to the applied queue on POSIX cron strings and one-shot delayed shapes. The scheduler mode is elicited (inProcess, workerCron, external) at ADR-3102; a reserved v1.1.0 workflows mode adds a fourth enum value per section 5.7 of the spec.",
+  "responsibilities": [
+    "Parse a POSIX cron string on a job definition and enqueue a message on each fire (AC-30103-1, AC-jobs-scheduledRunsOnCron).",
+    "Accept a one-shot delayed shape (delayMs or ISO-8601 fireAt) and enqueue the message when the elicited fire time is reached (AC-30103-1).",
+    "Expose a fake-clock seam so probes can drive the scheduler deterministically without wall-clock waits (AC-jobs-scheduledRunsOnCron).",
+    "Refuse workerCron mode when the applied queue has no cron surface (documented in the guide's Known limitations section)."
+  ],
+  "internalStructure": "One scheduler module carrying a start({ clock, publisher, onEvent }) entry point where clock is the injected clock (real system clock in production, the fake-clock seam under the probe). A long-lived setInterval per cron string in inProcess mode; a set of setTimeouts per one-shot delay. The fake-clock seam is a { now, advance(ms) } object the module reads instead of Date.now / setTimeout when injected.",
+  "interfaces": [
+    {
+      "name": "createScheduler",
+      "kind": "factory",
+      "description": "createScheduler({ mode, clock, publisher, onEvent }) -> Scheduler; mode is one of inProcess, workerCron, external."
+    },
+    {
+      "name": "scheduler.schedule",
+      "kind": "method",
+      "description": "schedule({ jobName, cron?: string, fireAt?: string, delayMs?: number, body?: any }): enqueues per the cron or delayed shape."
+    },
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with jobScheduled records: { event, jobId, jobName, attempts: 0, timestamp }."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Job-definition module",
+      "kind": "tac",
+      "tacId": "TAC-3101-jobs-background-job-definition",
+      "description": "The scheduler enqueues by jobName targeting a registered job-definition module."
+    },
+    {
+      "name": "Run log",
+      "kind": "tac",
+      "tacId": "TAC-3103-jobs-background-run-log",
+      "description": "jobScheduled events fire on the injected event sink."
+    }
+  ],
+  "tradeoffs": "The inProcess mode is unsuited to a Cloudflare Worker deploy (Worker instances have no long-lived setInterval); the workerCron mode addresses that at ADR-3102. The v1.1.0 workflows mode adds Cloudflare Workflows step.do orchestration without changing the outward scheduler contract.",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

package/blueprints/jobs-background/contributions/tacs/tac-3103-jobs-background-run-log.json

@@ -0,0 +1,49 @@
+{
+  "tacId": "TAC-3103-jobs-background-run-log",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Jobs-background run-log event sink",
+  "purpose": "The lifecycle-event sink for jobScheduled, jobStarted, jobCompleted and jobFailed events. The event whitelist { jobId, jobName, attempts, duration, timestamp } (plus terminalErrorCode on jobFailed) is enforced at this sink boundary; no domain job input, no handler output, no user id, no email, no SSN.",
+  "responsibilities": [
+    "Emit the four lifecycle events at the four moments in the runtime (AC-jobs-scheduledRunsOnCron, AC-jobs-retryOnHandlerFailure, AC-jobs-eventSecrecy).",
+    "Enforce the metadata-only whitelist at the sink boundary regardless of what the domain job body carries (AC-jobs-eventSecrecy).",
+    "Carry the attempts counter on every jobStarted and jobFailed record so the retry chain is observable (AC-jobs-retryOnHandlerFailure)."
+  ],
+  "internalStructure": "One event-sink adapter module exporting createRunLog({ upstream }) -> RunLog whose method fire({ event, ... }) filters through the whitelist and forwards to the upstream sink (the logging companion supplies the upstream). The sink is stateless per event; the runtime holds no history.",
+  "interfaces": [
+    {
+      "name": "createRunLog",
+      "kind": "factory",
+      "description": "createRunLog({ upstream }) -> RunLog; upstream is the applied logger companion's event sink."
+    },
+    {
+      "name": "runLog.fire",
+      "kind": "method",
+      "description": "fire({ event, jobId, jobName, attempts, duration, timestamp, terminalErrorCode? }): validates the whitelist and forwards the record; unknown fields are dropped."
+    },
+    {
+      "name": "eventEnvelope",
+      "kind": "shape",
+      "description": "The record shape: { event: 'jobScheduled' | 'jobStarted' | 'jobCompleted' | 'jobFailed', jobId: string, jobName: string, attempts: non-negative integer, duration: non-negative number, timestamp: ISO-8601 string, terminalErrorCode?: string (only on jobFailed) }."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Job-definition module",
+      "kind": "tac",
+      "tacId": "TAC-3101-jobs-background-job-definition",
+      "description": "Every dispatched handler produces two events (jobStarted, jobCompleted or jobFailed)."
+    },
+    {
+      "name": "Scheduler",
+      "kind": "tac",
+      "tacId": "TAC-3102-jobs-background-scheduler",
+      "description": "The scheduler fires jobScheduled at enqueue time."
+    }
+  ],
+  "tradeoffs": "The whitelist is strict; a project that needs additional structured metadata (a correlation id, a tenant id) hoists a companion-side envelope through the applied logger rather than widening this contract. That keeps the shipped surface small and defensible against PII leaks; the price is one more integration step for projects with rich domain context.",
+  "createdAt": "2026-09-06T20:30:00.000Z",
+  "updatedAt": "2026-09-06T20:30:00.000Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30101",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Apply refuses on a bare project with exit 3 and the stable message id",
+  "asA": "operator applying jobs-background on a fresh project with no queue provider applied yet",
+  "iWant": "the apply verb to refuse with exit 3, the stable message id tag on the first stderr line, an explicit reference to the shipped queue provider messaging-queue-cloudflare, and the override flag --allow-no-queue-yet",
+  "soThat": "a bare apply cannot silently ship a jobs-background surface with no queue behind it, and a dashboard or lint that binds to the stable message id keeps working across future refusal-text edits",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-jobs-requiresQueue",
+      "description": "On a fresh init scratch project with NO queue provider applied, rcf define blueprint add ./blueprints/jobs-background returns exit code 3; stderr contains the substring [jobs-background-no-queue] on the first line; stderr contains the substring messaging-queue-cloudflare naming the shipped provider; stderr contains the substring --allow-no-queue-yet naming the override flag. Nothing is written to rcf/manifest.json under blueprints[] for jobs-background.",
+      "given": "a fresh rcf init scratch project with no applied blueprints",
+      "when": "rcf define blueprint add ./blueprints/jobs-background runs",
+      "then": "exit code is 3; stderr first-line grep matches [jobs-background-no-queue]; stderr grep matches messaging-queue-cloudflare; stderr grep matches --allow-no-queue-yet; the manifest has no jobs-background entry",
+      "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-30102.json

@@ -0,0 +1,25 @@
+{
+  "usId": "jobs-background-US-30102",
+  "prdId": "PRD-001",
+  "reqId": "jobs-background-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Job definition contract with name, handler, inputSchema, retryPolicy and timeoutMs",
+  "asA": "developer authoring a job in an applying project",
+  "iWant": "one shipped job-definition shape { name, handler, inputSchema, retryPolicy, timeoutMs } that the jobs runtime registers at boot on the applied queue consumer",
+  "soThat": "every job in the project follows one uniform contract without the blueprint prescribing an input-validation library or a handler-callback style",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-30102-1",
+      "description": "The two toy job-definition modules under packages/rcf-lite/test/fixtures/infra-s3-and-queue/jobs/ (send-welcome-email.mjs and refresh-cache.mjs) each export a plain object with name (string), handler (async function), inputSchema (opaque, non-null), retryPolicy ({ maxAttempts: positive integer, backoff: one of exponential | constant | linear }), and timeoutMs (positive integer). The jobs runtime under src/jobs-runtime.mjs registers every job by name at boot and dispatches by message.name.",
+      "given": "the shared sample-app fixture with the T-4 jobs-runtime wired on top of the T-3 in-memory queue seam",
+      "when": "the fixture jobs runtime boots and reads the jobs/ directory",
+      "then": "both toy job modules load without throwing; the runtime's registry has entries keyed by name whose values carry handler, inputSchema, retryPolicy and timeoutMs; dispatch by message.name calls the matching handler",
+      "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-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"
+}