rcf-lite 0.21.0 → 0.23.0

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 } };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Fake-clock cron probe.
+ *
+ * Drives the fixture scheduler (inProcess mode with the fake-clock seam)
+ * plus the T-3 in-memory queue seam plus the T-4 jobs-runtime through
+ * one POSIX cron minute for the refresh-cache job. Asserts a jobStarted
+ * event fires on the injected run-log sink within the elicited
+ * fireToleranceMs window (default 30000 ms) with jobName 'refresh-cache'
+ * and attempts 1; asserts a jobCompleted event fires within the elicited
+ * timeoutMs (10000 ms for refresh-cache).
+ *
+ * Anchors AC-jobs-scheduledRunsOnCron.
+ *
+ * NOTE: this probe runs against the in-memory queue seam and the fake-
+ * clock, not a live wrangler dev process. The README's per-AC
+ * mechanism-reach section names the live-only follow-up per SDR-3-a.
+ */
+
+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 FIRE_TOLERANCE_MS = 30000;
+
+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: { ...process.env } });
+  const clock = createFakeClock(0);
+  const scheduler = createScheduler({ mode: 'inProcess', clock, publisher: producer, runLog });
+  scheduler.cron({ jobName: 'refresh-cache', cronString: '* * * * *', input: { cacheKey: 'demo' } });
+  // Advance clock past one cron minute; tick to publish.
+  clock.advance(60000);
+  const fires = await scheduler.tick();
+  // Drain runtime.
+  await runtime.drain({ driverState: pair.state, maxIterations: 16 });
+  const jobStarted = events.find((e) => e.event === 'jobStarted' && e.jobName === 'refresh-cache');
+  const jobCompleted = events.find((e) => e.event === 'jobCompleted' && e.jobName === 'refresh-cache');
+  const results = [];
+  const startPass = !!jobStarted && jobStarted.attempts === 1;
+  const durationOk = jobCompleted ? jobCompleted.duration <= registry.get('refresh-cache').timeoutMs : false;
+  const pass = fires === 1 && startPass && !!jobCompleted && durationOk;
+  results.push({
+    anchorAcId: 'AC-jobs-scheduledRunsOnCron',
+    verdict: pass ? 'pass' : 'fail',
+    detail: pass
+      ? `fires=1; jobStarted refresh-cache attempts=1 within fireToleranceMs=${FIRE_TOLERANCE_MS}; jobCompleted duration=${jobCompleted.duration}ms within timeoutMs=${registry.get('refresh-cache').timeoutMs}`
+      : `fires=${fires}; jobStarted=${JSON.stringify(jobStarted)}; jobCompleted=${JSON.stringify(jobCompleted)}; durationOk=${durationOk}`,
+  });
+  return { results, extra: { events, fireToleranceMs: FIRE_TOLERANCE_MS } };
+}

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"
+}