rcf-lite 0.27.0 → 0.28.0

package/blueprints/observability-probe-endpoints/contributions/probes/partial-profile-refusal.mjs

@@ -0,0 +1,101 @@
+// Partial-profile-refusal probe for observability-probe-endpoints.
+//
+// AC-14103-2 requires the process to exit non-zero when a profile
+// missing a required field is loaded at boot. This probe catches an
+// in-process refusal via refuseIfPartial rather than spawning a
+// child process and observing its OS exit code. Rows de-claimed
+// (conformanceOnly, anchorAcId=null) with the limitation naming
+// AC-14103-2.
+//
+// AC-14103-1 requires every field's value to belong to its enumerated
+// set (not just presence). This row asserts presence only. Row
+// de-claimed with the limitation naming AC-14103-1.
+//
+// AC-14103-3 requires the loadBalancer profile to be materialised
+// and observed to expose exactly one /health handler and no /live
+// or /ready handlers. This row asserts the resolved config shape but
+// does not materialise and probe for extra handlers. Row de-claimed
+// with the limitation naming AC-14103-3.
+
+import { refuseIfPartial, resolveProfile } from '../../../../packages/rcf-lite/test/fixtures/probe-pack-observability-probe-endpoints/src/profile-registry.mjs';
+
+export const anchorAcId = 'AC-14103-2';
+export const accountBound = false;
+
+const SHIPPED_NAMES = ['kubernetes', 'loadBalancer', 'uptimeMonitor', 'systemd', 'dockerHealthcheck', 'reverseProxy'];
+
+const LIM_14103_2 = `AC-14103-2: requires the process to exit non-zero when a profile missing a required field is loaded at boot. This row catches an in-process refusal via refuseIfPartial rather than spawning a child process and observing its OS exit code.`;
+const LIM_14103_1 = `AC-14103-1: requires every field's value to belong to its enumerated set (not just presence: transport must be an enum value, paths/command/notify each carry typed contents, semanticModel is one of a small set). This row asserts presence of each field only.`;
+const LIM_14103_3 = `AC-14103-3: requires the loadBalancer profile to be materialised and observed to expose exactly one /health handler and no /live or /ready handlers. This row asserts the resolved config shape but does not materialise the profile and issue HTTP GETs against /live and /ready to prove absence of those handlers.`;
+
+export default async function runProbe() {
+  const results = [];
+
+  // AC-14103-2 refusal via refuseIfPartial: strip 'transport' from the
+  // kubernetes profile.
+  const bad = { ...resolveProfile('kubernetes') };
+  delete bad.transport;
+  let refusalMessage = null;
+  let refusalCode = null;
+  let refusalMissing = null;
+  try { refuseIfPartial(bad); } catch (e) { refusalMessage = e.message; refusalCode = e.code; refusalMissing = e.missingKey; }
+  results.push({
+    anchorAcId: null,
+    conformanceOnly: true,
+    limitation: LIM_14103_2,
+    verdict: refusalCode === 'PROBE_PROFILE_INCOMPLETE' && refusalMissing === 'transport' ? 'pass' : 'fail',
+    detail: `observed stripped-transport kubernetes profile refused via refuseIfPartial with code='${refusalCode}' missingKey='${refusalMissing}' message='${refusalMessage}'. Process-level non-zero exit not observed here.`,
+    evidence: { refusalMessage, refusalCode, missingKey: refusalMissing },
+  });
+
+  // Second refusal: kubernetes with startupEnabled=true but no paths.startup.
+  const bad2 = { ...resolveProfile('kubernetes') };
+  bad2.startupEnabled = true;
+  let refusalMessage2 = null;
+  let refusalCode2 = null;
+  let refusalMissing2 = null;
+  try { refuseIfPartial(bad2); } catch (e) { refusalMessage2 = e.message; refusalCode2 = e.code; refusalMissing2 = e.missingKey; }
+  results.push({
+    anchorAcId: null,
+    conformanceOnly: true,
+    limitation: LIM_14103_2,
+    verdict: refusalCode2 === 'PROBE_PROFILE_INCOMPLETE' && refusalMissing2 === 'paths.startup' ? 'pass' : 'fail',
+    detail: `observed kubernetes with startupEnabled but no paths.startup refused via refuseIfPartial with code='${refusalCode2}' missingKey='${refusalMissing2}' message='${refusalMessage2}'. Process-level non-zero exit not observed here.`,
+    evidence: { refusalMessage: refusalMessage2, refusalCode: refusalCode2, missingKey: refusalMissing2 },
+  });
+
+  // AC-14103-1 presence shape check for all six profiles.
+  const shape = [];
+  let allShapeOk = true;
+  for (const name of SHIPPED_NAMES) {
+    let resolved = null;
+    let err = null;
+    try { resolved = refuseIfPartial(resolveProfile(name)); } catch (e) { err = e.message; }
+    const surfaceOk = resolved && (resolved.paths || resolved.command || resolved.notify);
+    const ok = Boolean(resolved && resolved.transport && surfaceOk && resolved.responseContract && resolved.semanticModel);
+    if (!ok) allShapeOk = false;
+    shape.push({ name, transport: resolved?.transport, hasSurface: Boolean(surfaceOk), hasResponseContract: Boolean(resolved?.responseContract), hasSemanticModel: Boolean(resolved?.semanticModel), err });
+  }
+  results.push({
+    anchorAcId: null,
+    conformanceOnly: true,
+    limitation: LIM_14103_1,
+    verdict: allShapeOk ? 'pass' : 'fail',
+    detail: `observed presence-only shape check for all six shipped profiles: ${JSON.stringify(shape)}. Enum-membership per field is not observed here.`,
+    evidence: { acceptedProfile: 'all-six', resolvedTransport: 'mixed', resolvedPaths: {}, shape, shippedNames: SHIPPED_NAMES },
+  });
+
+  // AC-14103-3 loadBalancer shape observation (not materialised).
+  const lb = resolveProfile('loadBalancer');
+  const lbOk = lb.paths?.health && !lb.paths?.liveness && !lb.paths?.readiness && lb.semanticModel === 'singleHealthSignal';
+  results.push({
+    anchorAcId: null,
+    conformanceOnly: true,
+    limitation: LIM_14103_3,
+    verdict: lbOk ? 'pass' : 'fail',
+    detail: `The loadBalancer profile resolves to a single-endpoint HTTP GET  -  observed resolved paths=${JSON.stringify(lb.paths)} semanticModel='${lb.semanticModel}'; expected paths.health present with no paths.liveness/paths.readiness and semanticModel==='singleHealthSignal'. Materialised handler absence not observed here.`,
+    evidence: { acceptedProfile: lb.name, resolvedTransport: lb.transport, resolvedPaths: lb.paths, semanticModel: lb.semanticModel },
+  });
+
+  return { results, extra: { envDeclared: ['RCF_FIXTURE_OBS_PROBE_PORT', 'RCF_FIXTURE_OBS_PROBE_SEPARATE_PORT'], shippedNames: SHIPPED_NAMES } };
+}

package/blueprints/observability-probe-endpoints/contributions/probes/probe-utils.mjs

@@ -0,0 +1,49 @@
+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));
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/probe-pack-observability-probe-endpoints');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/observability-probe-endpoints');
+export const DECLARED_ENV = new Set(['RCF_FIXTURE_OBS_PROBE_PORT', 'RCF_FIXTURE_OBS_PROBE_SEPARATE_PORT']);
+
+export function aggregate(results) {
+  if (!Array.isArray(results) || results.length === 0) return 'fail';
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+export function isSkipped(results) { return Array.isArray(results) && results.length > 0 && results.every((r) => r.accountBoundSkipped === true); }
+export async function writeReport({ probeName, engine, results, extra }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const normalised = (Array.isArray(results) && results.length > 0)
+    ? results
+    : [{ anchorAcId: null, harnessError: true, verdict: 'fail', detail: 'no checks ran', evidence: { reason: 'no checks ran', probeName, runAt: new Date().toISOString(), engine } }];
+  const raw = aggregate(normalised);
+  const aggregateVerdict = isSkipped(normalised) ? 'pass' : raw;
+  const report = { slug: 'observability-probe-endpoints', probeName, runAt: new Date().toISOString(), engine, results: normalised, aggregateVerdict, ...(extra ?? {}) };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2) + '\n', 'utf8');
+  return { report, path };
+}
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const outcome = (await mainFn()) ?? { results: [] };
+    const { results, extra } = outcome;
+    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`);
+    if (report.aggregateVerdict === 'fail') process.exitCode = 1;
+  } catch (err) {
+    const results = [{ anchorAcId: null, harnessError: true, verdict: 'fail', detail: `probe threw: ${err?.message ?? err}`, evidence: { thrown: true, message: err?.message ?? String(err), name: err?.name ?? 'Error', probeName, runAt: new Date().toISOString(), engine } }];
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${err?.stack ?? err}\n`);
+    process.stderr.write(`report written to ${path}\n`);
+    process.exitCode = 1;
+  }
+}
+function portFrom(v) { if (v === undefined || v === '') return 0; const n = Number(v); return Number.isInteger(n) && n >= 0 && n <= 65535 ? n : 0; }
+export const primaryPort = () => portFrom(process.env.RCF_FIXTURE_OBS_PROBE_PORT);
+export const separatePort = () => portFrom(process.env.RCF_FIXTURE_OBS_PROBE_SEPARATE_PORT);

package/blueprints/observability-probe-endpoints/contributions/probes/profile-boot-materialisation.mjs

@@ -0,0 +1,69 @@
+// Profile-boot-materialisation probe for observability-probe-endpoints.
+//
+// Resolves the shipped 'kubernetes' profile and materialises it on
+// 127.0.0.1 via the fixture registry; issues real HTTP GETs to the
+// resolved liveness and readiness paths with a probe-varied
+// x-request-id header per request. Records the response header echo
+// and body excerpt and asserts the resolved profile name equals
+// 'kubernetes' and the bound listener answers on the profile's
+// declared paths.
+//
+// AC-14101-1 additionally requires observation of fused/separate port
+// topology AND absence of handlers outside the resolved path set.
+// This row observes only bound-path behaviour; it does not check
+// port topology or verify no additional handlers were bound. Row
+// de-claimed (conformanceOnly, anchorAcId=null) with the limitation
+// naming AC-14101-1.
+
+import { randomUUID } from 'node:crypto';
+import { materialise, resolveProfile } from '../../../../packages/rcf-lite/test/fixtures/probe-pack-observability-probe-endpoints/src/profile-registry.mjs';
+import { primaryPort } from './probe-utils.mjs';
+
+export const anchorAcId = 'AC-14101-1';
+export const accountBound = false;
+const LIM_14101_1 = `AC-14101-1: requires a process configured with probeInterface.profile: kubernetes to bind probe handlers whose paths match the resolved profile AND to observe fused/separate port topology AND absence of handlers outside the resolved path set. This row observes bound-path behaviour (liveness and readiness respond 200 with body.status='pass') but does not verify port-topology or handler-absence clauses.`;
+
+async function get(url, rid) {
+  const res = await fetch(url, { headers: { 'x-request-id': rid } });
+  const text = await res.text();
+  let parsed = null; try { parsed = JSON.parse(text); } catch {}
+  return { status: res.status, requestId: res.headers.get('x-request-id'), contentType: res.headers.get('content-type'), body: text, parsed };
+}
+
+export default async function runProbe() {
+  const results = [];
+  const resolved = resolveProfile('kubernetes');
+  const inst = await materialise({ profile: resolved, listenerPort: primaryPort() });
+  const suppliedLive = randomUUID();
+  const suppliedReady = randomUUID();
+  let live, ready;
+  try {
+    live = await get(`http://127.0.0.1:${inst.requestPort}${inst.profile.paths.liveness}`, suppliedLive);
+    ready = await get(`http://127.0.0.1:${inst.requestPort}${inst.profile.paths.readiness}`, suppliedReady);
+    const liveOk = live.status === 200 && live.requestId === suppliedLive && live.parsed?.status === 'pass' && live.parsed?.profile === 'kubernetes' && live.parsed?.kind === 'liveness';
+    const readyOk = ready.status === 200 && ready.requestId === suppliedReady && ready.parsed?.status === 'pass' && ready.parsed?.profile === 'kubernetes' && ready.parsed?.kind === 'readiness';
+    const nameOk = inst.profile.name === 'kubernetes';
+    const pathsOk = inst.profile.paths.liveness === '/live' && inst.profile.paths.readiness === '/ready';
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIM_14101_1,
+      verdict: liveOk && readyOk && nameOk && pathsOk ? 'pass' : 'fail',
+      detail: `observed resolved profile.name='${inst.profile.name}' paths=${JSON.stringify(inst.profile.paths)} on port ${inst.requestPort}; live status=${live.status} echoed rid=${live.requestId === suppliedLive} body.status='${live.parsed?.status}' body.profile='${live.parsed?.profile}'; ready status=${ready.status} echoed rid=${ready.requestId === suppliedReady} body.status='${ready.parsed?.status}' body.profile='${ready.parsed?.profile}'.`,
+      evidence: {
+        acceptedProfile: inst.profile.name,
+        resolvedTransport: inst.profile.transport,
+        resolvedPaths: inst.profile.paths,
+        port: inst.requestPort,
+        variedInputs: { liveness: suppliedLive, readiness: suppliedReady },
+        derivedLive: { status: live.status, requestId: live.requestId, contentType: live.contentType, bodyExcerpt: live.body.slice(0, 300) },
+        derivedReady: { status: ready.status, requestId: ready.requestId, contentType: ready.contentType, bodyExcerpt: ready.body.slice(0, 300) },
+      },
+    });
+  } finally { await inst.close(); }
+  return { results, extra: { envDeclared: ['RCF_FIXTURE_OBS_PROBE_PORT', 'RCF_FIXTURE_OBS_PROBE_SEPARATE_PORT'], boundPort: inst.requestPort,
+    variedInputs: { liveness: suppliedLive, readiness: suppliedReady },
+    derivedLive: live && { status: live.status, requestId: live.requestId, contentType: live.contentType, bodyExcerpt: live.body.slice(0, 300) },
+    derivedReady: ready && { status: ready.status, requestId: ready.requestId, contentType: ready.contentType, bodyExcerpt: ready.body.slice(0, 300) },
+  } };
+}

package/blueprints/observability-probe-endpoints/contributions/probes/run-kubernetes-startup-enabled.mjs

@@ -0,0 +1,3 @@
+import runProbe from './kubernetes-startup-enabled.mjs';
+import { runShim } from './probe-utils.mjs';
+runShim('kubernetes-startup-enabled', { kind: 'http', driver: 'node:http fixture profile registry on 127.0.0.1', healthy: true }, runProbe);

package/blueprints/observability-probe-endpoints/contributions/probes/run-partial-profile-refusal.mjs

@@ -0,0 +1,3 @@
+import runProbe from './partial-profile-refusal.mjs';
+import { runShim } from './probe-utils.mjs';
+runShim('partial-profile-refusal', { kind: 'in-process', driver: 'profile registry refusal shim', healthy: true }, runProbe);

package/blueprints/observability-probe-endpoints/contributions/probes/run-profile-boot-materialisation.mjs

@@ -0,0 +1,3 @@
+import runProbe from './profile-boot-materialisation.mjs';
+import { runShim } from './probe-utils.mjs';
+runShim('profile-boot-materialisation', { kind: 'http', driver: 'node:http fixture profile registry on 127.0.0.1', healthy: true }, runProbe);

package/blueprints/observability-probe-endpoints/docs/topics.md

@@ -19,7 +19,7 @@ Rules for new topics (inherited from the application-spa, application-api-rest,
 
 ## Id number bands (registry bootstrap)
 
-AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.5.0 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.5.0 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is policy; this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
 
 This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
 
@@ -64,7 +64,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | platform-docker-compose-host | 38101-38899 | 39xx | shipped v1.0.0 | `containerHostContract` |
 | edge-cloudflare-tunnel | 39101-39899 | 40xx | shipped v1.0.0 | `edgeIngressBridge` |
 
-US 14101-14108 sit at the LOW end of the 14101-14899 band on purpose. A project-side story that mechanically derives from an observability-probe-endpoints REQ id into the number `14108` would collide against observability-probe-endpoints-US-14108 in this package; the band leaves headroom at the HIGH end (US 14181-14899) so a project's own stories anchored to observability-probe-endpoints REQs can allocate without conflict. The watchpost run4 lesson applies here too. Band spacing between the previous shelf-lane row (persistence-data-d1, 13101-13899, 14xx) and this one (14101-14899, 15xx) reflects the four-digit widening pattern opened by security-auth-clerk at 10xx and continued through the round-2 shelf lane.
+US 14101-14108 sit at the LOW end of the 14101-14899 band on purpose. A project-side story that mechanically derives from an observability-probe-endpoints REQ id into the number `14108` would collide against observability-probe-endpoints-US-14108 in this package; the band leaves headroom at the HIGH end (US 14181-14899) so a project's own stories anchored to observability-probe-endpoints REQs can allocate without conflict. Band spacing between the previous shelf-lane row (persistence-data-d1, 13101-13899, 14xx) and this one (14101-14899, 15xx) reflects the four-digit widening pattern opened by security-auth-clerk at 10xx and continued through the second shelf-lane block.
 
 ## Shared expectations for future composing blueprints
 

package/blueprints/persistence-data-d1/CHANGELOG.md

@@ -1,19 +1,32 @@
 # Changelog
 
+## 1.1.6 - 2026-09-11
+
+facade-round-trip AC-13101-4 (missing-binding refusal) row is de-claimed to conformanceOnly (anchorAcId=null on the row; the module anchor is unchanged). The refusal is thrown by the local fixture's openFacade before any call reaches the D1 engine, so no engine-returned request id or resource identifier is available; the credential-leak-absent predicate is retained on the row. The earlier CHANGELOG description of a locally minted callTrackingId as a resource identifier is corrected: the field is dropped from the probe's evidence and the language does not appear here.
+
+## 1.1.5 - 2026-09-11
+
+AC-13101-4 anchor now positively asserts no-credential-leak: a sentinel account id and API token are stashed on the env passed to openFacade alongside the missing DB binding, and the row verdict requires neither sentinel appears in the refusal error message, kind, bindingName, stack or JSON serialisation (credentialLeakAbsent=true); the row records a locally minted row correlation string on the row (no engine identifier is available on the refusal path). CHANGELOG history restored (the 1.1.0/1.1.1/1.1.2 entries were unintentionally overwritten in the previous pass) and this 1.1.5 entry is added.
+
+## 1.1.4 - 2026-09-11
+
+Adds a contributions/probes/ pack (facade-round-trip, migrations-forward-only, real-account-d1-round-trip) with a fixture-side sqlite-backed D1 binding and a facade module under packages/rcf-lite/test/fixtures/probe-pack-persistence-data-d1/. Probes run against the fixture on Node 24 and against real Cloudflare D1 on the account-bound branch (CI_HAS_CLOUDFLARE_ACCOUNT gate + CF_ACCOUNT_ID + CF_API_TOKEN, one variable per skip row).
+
+Anchoring: facade-round-trip anchors AC-13101-4 (missing-binding refusal) as its module anchor; the facadeReady, insert, find and delete rows de-claim (conformanceOnly, anchorAcId=null) with limitations naming AC-13101-1 or AC-13101-2 (source-tree sole-reader and facade-surface scan are not observable at runtime). migrations-forward-only anchors AC-13102-2 as its module anchor; each row de-claims with a limitation naming AC-13102-2 or AC-13102-3 (wrangler CLI not spawned; internal table name is not the configured d1_migrations). real-account-d1-round-trip anchors AC-13101-1 as its module anchor; every live row de-claims with the limitation naming AC-13101-1 (raw REST is not the source-tree sole-reader property). Live create rows record only what the create call proves; presentAfterDelete is set only on the teardown row after delete + inventory. An auth failure with credentials PRESENT is a FAIL, not an accountBoundSkipped row. Live scratch resources are named qa-e-d1-<short> and deleted with a post-run inventory check.
 
 ## 1.1.2 - 2026-09-10
 
-Second closure fix on the dimension-d ownership sweep for REQ-004: removed the `prepare().bind()` and `db.exec(<consumer string>)` literals from `ADR-1404.context` (the argument now names the prepared-statement discipline owned on `TAC-1401-persistence-data-d1-facade.responsibilities[2]`); added the one-line owner pointer to the facade-shape asset and the batch-usage asset naming the TAC responsibility indices they demonstrate. ADR-1404 bumped to 1.0.1. Chain-consistency lint zero on pass 1 and pass 2.
+Removed the `prepare().bind()` and `db.exec(<consumer string>)` literals from `ADR-1404.context` (the argument now names the prepared-statement discipline owned on `TAC-1401-persistence-data-d1-facade.responsibilities[2]`); added the one-line owner pointer to the facade-shape asset and the batch-usage asset naming the TAC responsibility indices they demonstrate. ADR-1404 bumped to 1.0.1.
 
 ## 1.1.1 - 2026-09-10
 
 Dimension-d single-definition-ownership cleanup on REQ-004: REQ description now references the prepared-statement discipline owned on TAC-1401 (facade responsibilities) rather than restating the vendor prepare/bind/exec literals. `deliveredBy` re-pointed at `TAC-1401-persistence-data-d1-facade.responsibilities.prepare` so the pass-2 delivery-carried check resolves against surface text present on the TAC. Chain-consistency lint zero on pass 1 and pass 2.
 
 ## 1.1.0 - 2026-09-09
-Adds deliveredBy on REQ-001. Adds ownerRef and disposition to every AC. Closes chain-contradiction specimen F-3 by settling the allowed query surface on ADR-1404 (db.exec refused on the facade's public verbs and on consumer code; permitted only inside the migration runner, out of consumer reach). No new contributions.
+Adds deliveredBy on REQ-001. Adds ownerRef and disposition to every AC. ADR-1404 settles the allowed query surface: `db.exec` is refused on the facade's public verbs and on consumer code, and permitted only inside the migration runner, out of consumer reach. No new contributions.
 
 
 
-Review-fix (2026-09-09): Version bumped from 1.0.1 to 1.1.0 to reflect the net-added AC contributions on existing stories (migration-D1-binding failure paths added under US-13101; deploy-gate quota-exhausted added under US-13102). Prior 1.0.1 entry reclassified as prose-only; this bump covers the AC additions per section 8.
+Version bumped from 1.0.1 to 1.1.0 to reflect the net-added AC contributions on existing stories (migration-D1-binding failure paths added under US-13101; deploy-gate quota-exhausted added under US-13102).
 
 Adds deliveredBy on REQ-002 through REQ-007 (six of seven mandatory REQs). Sweeps vendorCitation onto fixed ACs resting on vendor facts (AC-13103-1, AC-13104-3, AC-13105-2).

package/blueprints/persistence-data-d1/README.md

@@ -27,9 +27,9 @@ The doc set is contributions (copied into the project tree by `rcf define bluepr
 
 ## What it contributes, and what it deliberately does not
 
-Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (shipped policy 5) and no code.
 
-No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the store facade contract, the wrangler-owned migration discipline, the deploy-pipeline gate contract, the prepared-statement and batch atomicity boundaries, the two-path recovery model, the metadata-only event log discipline); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+No FBS contributions, as a matter of principle (policy): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the store facade contract, the wrangler-owned migration discipline, the deploy-pipeline gate contract, the prepared-statement and batch atomicity boundaries, the two-path recovery model, the metadata-only event log discipline); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
 
 Deliberately not contributed: the domain schema (the tables the project's own entities live in are project-authored, on top of the migration directory the project maintains; the blueprint governs the facade contract and the migration discipline, not the domain shape); an ORM or query builder above the D1 prepared-statement surface (the facade is a project-authored surface; how it internally implements its verbs above the vendor binding is not blueprint-owned, but the boundary discipline refuses raw-SQL passthrough on the public surface); a Worker deploy blueprint (a companion `deploy-cloudflare-workers` blueprint is the natural pair for the Worker deploy step the deploy-gate TAC assumes; until it ships, projects wire their own deploy step); a secrets management surface for the CI credential that runs `wrangler d1 migrations apply` and `wrangler deploy` (the credential storage and rotation posture are the concern of the `security-secrets-management` blueprint, not this one); a CI pipeline template (CI shape is the concern of the `delivery-ci-workflows` blueprint, not this one; this blueprint contributes the requirement that the migrations-apply step orders strictly before the deploy step, not the file that implements it); a replication or failover surface (D1's read-replica surface is a read-scaling primitive, not a failover primitive; a project needing failover supersedes ADR-1401 with an alternate engine); a logical schema-agnostic dump beyond the vendor's `wrangler d1 export` (out of scope; see ADR-1405's alternatives).
 

package/blueprints/persistence-data-d1/blueprint.json

@@ -1,6 +1,6 @@
 {
   "slug": "persistence-data-d1",
-  "version": "1.1.2",
+  "version": "1.1.6",
   "category": "persistence",
   "contributions": [
     {
@@ -122,5 +122,6 @@
       "kind": "adr",
       "path": "adrs/adr-1405-persistence-data-d1-recovery-model.json"
     }
-  ]
+  ],
+  "updatedAt": "2026-09-11"
 }

package/blueprints/persistence-data-d1/contributions/adrs/adr-1404-persistence-data-d1-store-boundary.json

@@ -6,7 +6,7 @@
   "status": "accepted",
   "title": "The D1 store facade is the only module that reads the D1 binding; consumers use named domain verbs, and every statement is a parameterised prepared statement",
   "context": "A persistence boundary that leaks (the domain code reads the D1 binding from `env` directly, or the facade exposes a general-purpose raw-SQL passthrough) is a boundary the swap-out story does not work through, the test-double story does not work through, the reasoning-about-persistence-code-paths story does not work through, and (worse for D1 than for a local-file engine) the SQL-injection story does not work through: any consumer-supplied SQL fragment that reaches the vendor surface bypasses the prepared-statement discipline owned on TAC-1401-persistence-data-d1-facade.responsibilities[2], and the discipline is only load-bearing when it holds at every call site the facade exposes.",
-  "decision": "One module (the D1 store facade, TAC-1401-persistence-data-d1-facade) reads the D1 binding from the Worker `env`. Every other module in the source tree that touches persistence imports the facade and calls its named verbs. The facade's public surface exposes named domain verbs with typed parameters; it does not export the D1 binding, and it does not expose a general-purpose query method whose parameter is a SQL string or a prepared-statement object supplied by a consumer. Every statement the facade issues follows the prepared-statement chain owned on TAC-1401-persistence-data-d1-facade.responsibilities[2]; the raw `exec` surface is never invoked with a non-literal string, and SQL is never constructed by string concatenation with consumer arguments. Multi-statement writes that require atomicity go through the batch call owned on TAC-1401-persistence-data-d1-facade.responsibilities[3]; the facade never fakes atomicity by chaining sequential independent calls under an application-side try-catch. Allowed query surface (ratified): only the prepared-statement chain above; no `exec` on consumer-supplied strings; the raw `exec` surface is permitted ONLY inside the migration runner (out of consumer-code reach) for the vendor-required schema-DDL pass, never on the facade's public verbs. Consumer code that calls the raw `exec` surface on the facade's exposed handle is refused by the source-scan probe.",
+  "decision": "One module (the D1 store facade, TAC-1401-persistence-data-d1-facade) reads the D1 binding from the Worker `env`. Every other module in the source tree that touches persistence imports the facade and calls its named verbs. The facade's public surface exposes named domain verbs with typed parameters; it does not export the D1 binding, and it does not expose a general-purpose query method whose parameter is a SQL string or a prepared-statement object supplied by a consumer. Every statement the facade issues follows the prepared-statement chain owned on TAC-1401-persistence-data-d1-facade.responsibilities[2]; the raw `exec` surface is never invoked with a non-literal string, and SQL is never constructed by string concatenation with consumer arguments. Multi-statement writes that require atomicity go through the batch call owned on TAC-1401-persistence-data-d1-facade.responsibilities[3]; the facade never fakes atomicity by chaining sequential independent calls under an application-side try-catch. Allowed query surface: only the prepared-statement chain above; no `exec` on consumer-supplied strings; the raw `exec` surface is permitted ONLY inside the migration runner (out of consumer-code reach) for the vendor-required schema-DDL pass, never on the facade's public verbs. Consumer code that calls the raw `exec` surface on the facade's exposed handle is refused by the source-scan probe.",
   "consequences": "The engine choice is swappable because there is exactly one place that reads the binding. Domain tests run against an in-memory double that implements the same verb surface, without any reference to D1 at any point in the test's call path. Every persistence code path is discoverable by grepping for the facade's exports. Consumer arguments never traverse the SQL parser; the vendor's parameter-binding layer is the only place values reach the engine, and SQL injection is closed by construction rather than by discipline-at-call-site. Consumers pay a small cost when they need a new query shape (a facade edit and a consumer edit, in one commit); the size of that cost is the mechanism enforcing the boundary. Composing blueprints that contribute persistence-adjacent components (a cache, an outbox, a projection) contribute their own facade modules on the same discipline; every one of them imports the D1 store facade for its persistence needs, not the D1 binding.",
   "alternativesConsidered": [
     {

package/blueprints/persistence-data-d1/contributions/probes/facade-round-trip.mjs

@@ -0,0 +1,140 @@
+// Facade round-trip probe for persistence-data-d1.
+//
+// The 'facadeReady' event count-per-open is a fixture-added observation
+// not stated on any shipped AC; the nearest shipped AC on facade shape
+// is AC-13101-1 (single source-tree reader of the binding). Row
+// de-claimed (conformanceOnly, anchorAcId=null) with the limitation
+// naming AC-13101-1.
+//
+// AC-13101-2 (named domain verbs; no general-purpose query method
+// accepting raw SQL) requires an exhaustive scan of the facade's
+// public surface to prove absence of a general-purpose query method
+// on top of the runtime CRUD observation. This probe observes the
+// runtime CRUD half only; rows de-claimed with the limitation naming
+// AC-13101-2.
+//
+// the strict-evidence contract tightening: AC-13101-4 (missing-binding refusal with
+// d1BindingMissing) is observed via the local fixture openFacade
+// throwing on a missing DB binding. The refusal never reaches the D1
+// engine, so no engine-returned request id or resource identifier is
+// available; the row is de-claimed to conformanceOnly naming AC-13101-4.
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createD1Binding } from '../../../../packages/rcf-lite/test/fixtures/probe-pack-persistence-data-d1/src/d1-binding-mock.mjs';
+import { openFacade } from '../../../../packages/rcf-lite/test/fixtures/probe-pack-persistence-data-d1/src/facade.mjs';
+
+// The module anchor names the AC this probe observes as a property;
+// individual rows may still de-claim (conformanceOnly) when the
+// evidence shape does not carry an engine-returned identifier.
+export const anchorAcId = 'AC-13101-4';
+export const accountBound = false;
+const AC4 = 'Dependency not ready: D1 binding absent from the';
+const LIM_13101_1 = `AC-13101-1: requires exactly one source-tree module to read the D1 binding from the Worker env. A fixture-added 'facadeReady' event count per open is not evidence of the import-graph sole-reader property AC-13101-1 states.`;
+const LIM_13101_2 = `AC-13101-2: requires the facade to expose named domain verbs for every persistence operation AND not to export the raw D1 binding or a general-purpose query method accepting a raw SQL string. Runtime CRUD round-trips through the facade demonstrate the named verbs work; a probe would still need an exhaustive scan of the facade's public surface to prove absence of a general-purpose query method.`;
+const LIM_13101_4 = `AC-13101-4: the missing-binding refusal is thrown by the local fixture's openFacade before any call reaches the D1 engine. No engine-returned request id or resource identifier is available on the refusal path; the credential-leak-absent predicate is observed, but the identifier half of the strict-evidence contract requires an id the engine or its response headers produced.`;
+
+export default async function runProbe() {
+  const dir = await mkdtemp(join(tmpdir(), 'rcf-d1-'));
+  const path = process.env.RCF_FIXTURE_D1_SQLITE_PATH || join(dir, 'd1.sqlite');
+  const events = [];
+  const results = [];
+  const binding = createD1Binding({ path });
+  const env = { DB: binding };
+  let rowId = null;
+  try {
+    const facade = await openFacade({ env, eventSink: (e) => events.push(e) });
+    const ready = events.filter((e) => e.event === 'facadeReady');
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIM_13101_1,
+      verdict: ready.length === 1 && facade.bindingName === 'DB' ? 'pass' : 'fail',
+      detail: `observed facadeReady x${ready.length} on bindingName='${facade.bindingName}'; migrations=${JSON.stringify(facade.migrationsApplied)}. Fixture-added event; the import-graph sole-reader property on AC-13101-1 is not observed at runtime.`,
+      evidence: { event: ready[0], bindingName: facade.bindingName, migrationsApplied: facade.migrationsApplied, bodyExcerpt: `facadeReady=${ready.length} binding=${facade.bindingName}` },
+    });
+    const ins = await facade.insertItem({ name: 'probe-item-1', note: 'from probe' });
+    rowId = ins.rowId;
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIM_13101_2,
+      verdict: Number.isInteger(ins.rowId) && ins.rowId > 0 && ins.changes === 1 ? 'pass' : 'fail',
+      detail: `observed insertItem returned real rowId=${ins.rowId} changes=${ins.changes} through the facade's named insert verb (no raw SQL leaves the facade at runtime).`,
+      evidence: { rowId: ins.rowId, changes: ins.changes, bodyExcerpt: `insertItem rowId=${ins.rowId} changes=${ins.changes}` },
+    });
+    const found = await facade.findItemByName('probe-item-1');
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIM_13101_2,
+      verdict: found && found.name === 'probe-item-1' && found.id === ins.rowId ? 'pass' : 'fail',
+      detail: `observed findItemByName returned id=${found?.id} name=${found?.name} through the facade's named find verb.`,
+      evidence: { found, rowIdOnRead: found?.id, bodyExcerpt: `findItemByName id=${found?.id} name=${found?.name}` },
+    });
+    const del = await facade.deleteItem({ name: 'probe-item-1' });
+    const after = await facade.findItemByName('probe-item-1');
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIM_13101_2,
+      verdict: del.changes === 1 && after === null ? 'pass' : 'fail',
+      detail: `observed deleteItem changes=${del.changes}; find-after-delete=${after ? 'present' : 'absent'} through the facade's named delete and find verbs.`,
+      evidence: { rowIdCreatedThenDeleted: rowId, deleteChanges: del.changes, presentAfterDelete: Boolean(after), bodyExcerpt: `deleteItem changes=${del.changes} presentAfterDelete=${Boolean(after)}` },
+    });
+    binding.__closeForFixture();
+    // Sentinels stashed on the env passed alongside the missing DB
+    // binding. AC-13101-4 requires the refusal to leak neither the
+    // account id nor the API token; the probe drives a positive predicate by
+    // proving neither sentinel appears anywhere in the refusal error's
+    // message, kind, bindingName, stack or JSON serialisation. Row
+    // de-claimed to conformanceOnly (the strict-evidence contract): the refusal never
+    // reaches the D1 engine so no engine-returned identifier exists.
+    const accountIdSentinel = 'acct-sentinel-' + Math.random().toString(36).slice(2, 12);
+    const apiTokenSentinel = 'token-sentinel-' + Math.random().toString(36).slice(2, 12);
+    let refusal = null;
+    let refusalErr = null;
+    try {
+      await openFacade({
+        env: { CLOUDFLARE_ACCOUNT_ID: accountIdSentinel, CLOUDFLARE_API_TOKEN: apiTokenSentinel },
+        eventSink: (e) => events.push(e),
+      });
+    } catch (e) {
+      refusalErr = e;
+      refusal = { message: e.message, kind: e.kind, bindingName: e.bindingName };
+    }
+    const refusalString = [
+      refusalErr?.message ?? '',
+      refusalErr?.kind ?? '',
+      refusalErr?.bindingName ?? '',
+      refusalErr?.stack ?? '',
+      (() => { try { return JSON.stringify(refusalErr, Object.getOwnPropertyNames(refusalErr || {})); } catch { return ''; } })(),
+    ].join(' || ');
+    const accountIdInRefusal = accountIdSentinel.length > 0 && refusalString.includes(accountIdSentinel);
+    const apiTokenInRefusal = apiTokenSentinel.length > 0 && refusalString.includes(apiTokenSentinel);
+    const credentialLeakAbsent = accountIdInRefusal === false && apiTokenInRefusal === false;
+    const readyAfterRefusal = events.filter((e) => e.event === 'facadeReady').length;
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: LIM_13101_4,
+      verdict: refusal?.kind === 'd1BindingMissing' && refusal?.bindingName === 'DB' && readyAfterRefusal === 1 && credentialLeakAbsent ? 'pass' : 'fail',
+      detail: `observed refusal kind='${refusal?.kind}' bindingName='${refusal?.bindingName}' after openFacade with env carrying sentinel account-id and api-token but no DB binding; accountIdInRefusal=${accountIdInRefusal}; apiTokenInRefusal=${apiTokenInRefusal}; credentialLeakAbsent=${credentialLeakAbsent}; facadeReady after refusal=${readyAfterRefusal} (unchanged; no extra event fired). Refusal never reaches the D1 engine; no engine-returned identifier is available.`,
+      evidence: {
+        ...refusal,
+        refusalMessage: refusal?.message,
+        kind: refusal?.kind,
+        bindingName: refusal?.bindingName,
+        missingKey: refusal?.bindingName,
+        accountIdInRefusal,
+        apiTokenInRefusal,
+        credentialLeakAbsent,
+        readyAfterRefusal,
+        bodyExcerpt: `refusal kind=${refusal?.kind} bindingName=${refusal?.bindingName} credentialLeakAbsent=${credentialLeakAbsent}`,
+      },
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+  return { results, extra: { envDeclared: ['RCF_FIXTURE_D1_SQLITE_PATH'], rowIdCreatedThenDeleted: rowId } };
+}

package/blueprints/persistence-data-d1/contributions/probes/migrations-forward-only.mjs

@@ -0,0 +1,66 @@
+// Migrations-forward-only probe for persistence-data-d1.
+//
+// AC-13102-2 requires the wrangler `list -> apply -> list` sequence
+// against a fresh local D1. This probe uses the fixture's openFacade
+// (which drives a sqlite-backed D1 binding), not a wrangler CLI. Row
+// de-claimed (conformanceOnly, anchorAcId=null) with the limitation
+// naming AC-13102-2.
+//
+// AC-13102-3 requires reading the configured bookkeeping table
+// (`migrations_table`; default `d1_migrations`). This probe queries
+// `schema_migrations`, the fixture's internal table name, not the
+// configured `d1_migrations`. Row de-claimed with the limitation
+// naming AC-13102-3.
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createD1Binding } from '../../../../packages/rcf-lite/test/fixtures/probe-pack-persistence-data-d1/src/d1-binding-mock.mjs';
+import { openFacade } from '../../../../packages/rcf-lite/test/fixtures/probe-pack-persistence-data-d1/src/facade.mjs';
+
+export const anchorAcId = 'AC-13102-2';
+export const accountBound = false;
+const AC2_LIM = `AC-13102-2: requires the wrangler 'list -> apply -> list' sequence against a fresh local D1 (wrangler CLI observed). openFacade is the fixture-embedded migration runner; a wrangler CLI is not spawned.`;
+const AC3_LIM = `AC-13102-3: requires reading the configured bookkeeping table (migrations_table; default d1_migrations). The fixture's internal table is schema_migrations, not the configured d1_migrations.`;
+
+export default async function runProbe() {
+  const dir = await mkdtemp(join(tmpdir(), 'rcf-d1-mig-'));
+  const path = process.env.RCF_FIXTURE_D1_SQLITE_PATH || join(dir, 'd1.sqlite');
+  const results = [];
+  const binding = createD1Binding({ path });
+  try {
+    const firstOpen = await openFacade({ env: { DB: binding } });
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: AC2_LIM,
+      verdict: firstOpen.migrationsApplied.length === 2
+        && firstOpen.migrationsApplied[0] === '0001_init.sql'
+        && firstOpen.migrationsApplied[1] === '0002_add_notes.sql' ? 'pass' : 'fail',
+      detail: `observed first open applied migrations in order: ${JSON.stringify(firstOpen.migrationsApplied)} through the sqlite-backed D1 binding (fixture-embedded migration runner; not wrangler CLI).`,
+      evidence: { migrationsApplied: firstOpen.migrationsApplied, bodyExcerpt: `applied=${JSON.stringify(firstOpen.migrationsApplied)}` },
+    });
+    const secondOpen = await openFacade({ env: { DB: binding } });
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: AC2_LIM,
+      verdict: secondOpen.migrationsApplied.length === 0 ? 'pass' : 'fail',
+      detail: `observed second open applied migrations: ${JSON.stringify(secondOpen.migrationsApplied)} (subsequent-list-reports-zero-unapplied shape; via fixture-embedded runner, not wrangler CLI).`,
+      evidence: { migrationsAppliedOnReopen: secondOpen.migrationsApplied.length > 0 ? secondOpen.migrationsApplied : ['<none-applied-on-reopen>'], bodyExcerpt: `reopenApplied=${JSON.stringify(secondOpen.migrationsApplied)}` },
+    });
+    const rows = (await binding.prepare('SELECT id FROM schema_migrations ORDER BY id').all()).results;
+    const ids = rows.map((r) => r.id);
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: AC3_LIM,
+      verdict: ids.length === 2 && ids[0] === '0001_init.sql' && ids[1] === '0002_add_notes.sql' ? 'pass' : 'fail',
+      detail: `observed fixture schema_migrations rows=${JSON.stringify(ids)} through a bounded SELECT (fixture internal table name schema_migrations, not the configured d1_migrations).`,
+      evidence: { migrationRows: ids, bodyExcerpt: `schema_migrations=${JSON.stringify(ids)}` },
+    });
+    binding.__closeForFixture();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+  return { results, extra: { envDeclared: ['RCF_FIXTURE_D1_SQLITE_PATH'] } };
+}

package/blueprints/persistence-data-d1/contributions/probes/probe-utils.mjs

@@ -0,0 +1,51 @@
+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));
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/probe-pack-persistence-data-d1');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/persistence-data-d1');
+export const DECLARED_ENV = new Set([
+  'RCF_FIXTURE_D1_SQLITE_PATH',
+  'SIMULATE_D1_RATE_LIMIT',
+  'CI_HAS_CLOUDFLARE_ACCOUNT',
+  'CF_ACCOUNT_ID',
+  'CF_API_TOKEN',
+]);
+export function aggregate(results) {
+  if (!Array.isArray(results) || results.length === 0) return 'fail';
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+export function isSkipped(results) { return Array.isArray(results) && results.length > 0 && results.every((r) => r.accountBoundSkipped === true); }
+export async function writeReport({ probeName, engine, results, extra }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const normalised = (Array.isArray(results) && results.length > 0)
+    ? results
+    : [{ anchorAcId: null, harnessError: true, verdict: 'fail', detail: 'no checks ran', evidence: { reason: 'no checks ran', probeName, runAt: new Date().toISOString(), engine } }];
+  const raw = aggregate(normalised);
+  const aggregateVerdict = isSkipped(normalised) ? 'pass' : raw;
+  const report = { slug: 'persistence-data-d1', probeName, runAt: new Date().toISOString(), engine, results: normalised, aggregateVerdict, ...(extra ?? {}) };
+  const path = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(path, JSON.stringify(report, null, 2) + '\n', 'utf8');
+  return { report, path };
+}
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const outcome = (await mainFn()) ?? { results: [] };
+    const { results, extra } = outcome;
+    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`);
+    if (report.aggregateVerdict === 'fail') process.exitCode = 1;
+  } catch (err) {
+    const results = [{ anchorAcId: null, harnessError: true, verdict: 'fail', detail: `probe threw: ${err?.message ?? err}`, evidence: { thrown: true, message: err?.message ?? String(err), name: err?.name ?? 'Error', probeName, runAt: new Date().toISOString(), engine } }];
+    const { report, path } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${err?.stack ?? err}\n`);
+    process.stderr.write(`report written to ${path}\n`);
+    process.exitCode = 1;
+  }
+}