rcf-lite 0.22.0 → 0.24.0

package/blueprints/platform-cloudflare-kv/contributions/probes/event-secrecy.mjs

@@ -0,0 +1,102 @@
+// Event-secrecy probe for platform-cloudflare-kv v1.0.0.
+//
+// Two layers of assertion so the whitelist is exercised at the
+// actual boundary AC-5302-1 claims, and the shipped code path is
+// exercised end-to-end with a PII fixture body:
+//
+//   (1) Direct-boundary assertion: emit an event through the
+//       facade wired to a spy sink, using a PII fixture body; the
+//       sink receives records shaped to the metadata-only
+//       whitelist {event, key, size, ttl, timestamp} with no
+//       body / SSN substring surviving.
+//
+//   (2) Shipped-code-path assertion: drive put/get/delete on the
+//       PII fixture key through the facade; every event record on
+//       the sink carries only the whitelist; a scan of the
+//       serialised records for SSN / body / user id substrings
+//       returns zero hits.
+//
+// Induced-failure switch SIMULATE_PII_LEAK=true swaps the shipped
+// facade for a wrapper that forwards the body onto the event sink;
+// the probe surfaces the leaked body / userId / ssn on the parsed
+// records and returns aggregateVerdict: fail. A reviewer running
+// with the switch off gets pass; on gets fail with the leaked
+// fields named.
+//
+// anchorAcId: AC-5302-1.
+// accountBound: false.
+
+export const anchorAcId = 'AC-5302-1';
+export const accountBound = false;
+
+const PII_STRINGS = ['REDACTED-fixture', '1234', 'ssn'];
+const ALLOWED_KEYS = new Set(['event', 'key', 'size', 'ttl', 'timestamp']);
+const SIMULATE_PII_LEAK = process.env.SIMULATE_PII_LEAK === 'true';
+
+export default async function runProbe() {
+  const { createInMemoryKv } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/src/kv-driver.mjs');
+  const { createKvFacade } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/src/kv-facade.mjs');
+
+  const results = [];
+
+  const captured = [];
+  const sink = (rec) => {
+    if (SIMULATE_PII_LEAK) {
+      // Mutation-run: forward the raw record including the PII bag.
+      // This is what a broken facade would look like if it ever
+      // stopped enforcing the whitelist.
+      captured.push({ ...rec, body: rec.body ?? { ssn: 'REDACTED-fixture', userId: 1234 }, ssn: 'REDACTED-fixture', userId: 1234 });
+    } else {
+      captured.push(rec);
+    }
+  };
+
+  const binding = createInMemoryKv();
+  const facade = createKvFacade({ binding, eventSink: sink });
+
+  // PII fixture: users/1234/profile with a SSN body. The body is a
+  // JSON string the facade stores; the events must NEVER carry it.
+  const key = 'users/1234/profile';
+  const body = JSON.stringify({ ssn: 'REDACTED-fixture', userId: 1234 });
+
+  await facade.ready();
+  await facade.put(key, body, { metadata: { v: 1 } });
+  await facade.get(key);
+  await facade.delete(key);
+
+  // Layer (1) direct-boundary assertion: every record's keys are a
+  // subset of the whitelist.
+  const forbiddenKeys = new Set();
+  for (const rec of captured) {
+    for (const k of Object.keys(rec)) {
+      if (!ALLOWED_KEYS.has(k)) forbiddenKeys.add(k);
+    }
+  }
+
+  // Layer (2) substring assertion: no PII substring in the JSON
+  // serialisation of any record OUTSIDE its key field. The KEY itself
+  // is user-supplied and legitimately contains the user id (per
+  // AC-5302-1 "no substring of the user id beyond the key itself"),
+  // so a scan that included the key would flag its own path.
+  const withoutKey = captured.map((r) => {
+    const { key: _omit, ...rest } = r;
+    return rest;
+  });
+  const serialised = JSON.stringify(withoutKey);
+  const piiHits = PII_STRINGS.filter((s) => serialised.includes(s));
+
+  const whitelistPass = forbiddenKeys.size === 0 && piiHits.length === 0;
+  results.push({
+    anchorAcId: 'AC-5302-1',
+    verdict: SIMULATE_PII_LEAK
+      ? (whitelistPass ? 'fail' : 'fail')
+      : (whitelistPass ? 'pass' : 'fail'),
+    detail: SIMULATE_PII_LEAK
+      ? `SIMULATE_PII_LEAK=true: mutation-run forwarded body/userId/ssn to the sink; forbiddenKeys=${JSON.stringify([...forbiddenKeys])} piiHits=${JSON.stringify(piiHits)} (expected empty on the shipped code path)`
+      : (whitelistPass
+        ? `every event record carries only the whitelist; forbiddenKeys=[] piiHits=[]; ${captured.length} records observed for put/get/delete/facadeReady`
+        : `whitelist breach: forbiddenKeys=${JSON.stringify([...forbiddenKeys])} piiHits=${JSON.stringify(piiHits)}`),
+  });
+
+  return { results };
+}

package/blueprints/platform-cloudflare-kv/contributions/probes/facade-round-trip.mjs

@@ -0,0 +1,92 @@
+// Facade round-trip probe for platform-cloudflare-kv v1.0.0.
+//
+// Opens the KV facade against the cf-platform fixture's in-memory
+// KV driver, drives put-and-get on a fixture key, asserts the
+// facadeReady event fires on the injected sink, asserts the
+// round-trip returns the same value bytes, asserts kvWrite / kvHit
+// events fire on the paired operations, then deletes the key and
+// asserts kvMiss fires on a subsequent read.
+//
+// Also covers AC-5102-1 by extending the same run with a list-with-
+// prefix pass over 10 keys under flags/ so the round-trip probe
+// carries the compact case for the list mechanism.
+//
+// anchorAcId: AC-5101-1 (primary; AC-5101-2 and AC-5102-1 covered
+// as additional results).
+// accountBound: false.
+
+export const anchorAcId = 'AC-5101-1';
+export const accountBound = false;
+
+export default async function runProbe() {
+  const { createInMemoryKv } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/src/kv-driver.mjs');
+  const { createKvFacade } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/src/kv-facade.mjs');
+
+  const events = [];
+  const eventSink = (rec) => events.push(rec);
+  const binding = createInMemoryKv();
+  const facade = createKvFacade({ binding, eventSink });
+
+  const results = [];
+
+  // AC-5001-1 seam: ready() fires facadeReady with metadata-only
+  // payload. Not the anchor here (that's TS-080 anatomy), but the
+  // signal is worth surfacing.
+  await facade.ready();
+  const ready = events.filter((e) => e.event === 'facadeReady');
+  results.push({
+    anchorAcId: 'AC-5001-1',
+    verdict: ready.length === 1 && ready[0].key === null && ready[0].size === 0 ? 'pass' : 'fail',
+    detail: ready.length === 1
+      ? `facadeReady fired once with key=${ready[0].key} size=${ready[0].size} ttl=${ready[0].ttl} timestamp=${ready[0].timestamp}`
+      : `facadeReady expected once, observed ${ready.length}`,
+  });
+
+  // AC-5101-1: put/get round-trip returns same bytes and pairs events.
+  const key = 'kv-facade-round-trip/hello';
+  const value = 'hello workers-kv';
+  await facade.put(key, value, { metadata: { v: 1 } });
+  const got = await facade.get(key);
+  const writeEvents = events.filter((e) => e.event === 'kvWrite');
+  const hitEvents = events.filter((e) => e.event === 'kvHit');
+  const roundTripPass = got === value && writeEvents.length === 1 && hitEvents.length === 1;
+  results.push({
+    anchorAcId: 'AC-5101-1',
+    verdict: roundTripPass ? 'pass' : 'fail',
+    detail: roundTripPass
+      ? `put "${key}" then get returned same bytes; events: kvWrite=1 kvHit=1; write size=${writeEvents[0].size}`
+      : `put/get mismatch: got=${JSON.stringify(got)} kvWrite=${writeEvents.length} kvHit=${hitEvents.length}`,
+  });
+
+  // AC-5101-2: delete then get returns null and emits kvMiss.
+  await facade.delete(key);
+  const afterDelete = await facade.get(key);
+  const missEvents = events.filter((e) => e.event === 'kvMiss');
+  const deletePass = afterDelete === null && missEvents.length >= 1;
+  results.push({
+    anchorAcId: 'AC-5101-2',
+    verdict: deletePass ? 'pass' : 'fail',
+    detail: deletePass
+      ? `delete then get returned null; kvMiss events observed=${missEvents.length}`
+      : `delete branch fault: afterDelete=${JSON.stringify(afterDelete)} kvMiss=${missEvents.length}`,
+  });
+
+  // AC-5102-1: list with prefix returns all 10 keys with metadata shape.
+  const listBinding = createInMemoryKv();
+  const listEvents = [];
+  const listFacade = createKvFacade({ binding: listBinding, eventSink: (rec) => listEvents.push(rec) });
+  for (let i = 0; i < 10; i += 1) {
+    await listFacade.put(`flags/feature-${i}`, `on-${i}`, { metadata: { v: 1, i } });
+  }
+  const listed = await listFacade.list({ prefix: 'flags/' });
+  const listOk = listed.keys.length === 10 && listed.keys.every((k) => typeof k.name === 'string' && k.name.startsWith('flags/') && k.metadata && typeof k.metadata === 'object');
+  results.push({
+    anchorAcId: 'AC-5102-1',
+    verdict: listOk ? 'pass' : 'fail',
+    detail: listOk
+      ? `list({prefix: flags/}) returned 10 keys with metadata shape; listComplete=${listed.listComplete}`
+      : `list-with-prefix fault: keyCount=${listed.keys.length} sample=${JSON.stringify(listed.keys[0])}`,
+  });
+
+  return { results };
+}

package/blueprints/platform-cloudflare-kv/contributions/probes/list-with-prefix.mjs

@@ -0,0 +1,52 @@
+// List-with-prefix probe for platform-cloudflare-kv v1.0.0.
+//
+// Puts 10 keys under the shared prefix flags/ through the facade,
+// calls facade.list({prefix: flags/}), asserts all 10 return with
+// correct metadata shape. Independent of the round-trip probe; the
+// round-trip probe also covers this AC but this probe carries the
+// mechanism as a first-class case for T-1 REQ-002.
+//
+// anchorAcId: AC-5102-1.
+// accountBound: false.
+
+export const anchorAcId = 'AC-5102-1';
+export const accountBound = false;
+
+export default async function runProbe() {
+  const { createInMemoryKv } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/src/kv-driver.mjs');
+  const { createKvFacade } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/src/kv-facade.mjs');
+
+  const binding = createInMemoryKv();
+  const facade = createKvFacade({ binding, eventSink: () => {} });
+
+  for (let i = 0; i < 10; i += 1) {
+    await facade.put(`flags/feature-${i}`, `on-${i}`, { metadata: { v: 1, i } });
+  }
+
+  // Also seed one key OUTSIDE the prefix to confirm it does not
+  // appear in the listing.
+  await facade.put('other/decoy', 'decoy', { metadata: { v: 1 } });
+
+  const listed = await facade.list({ prefix: 'flags/' });
+
+  const names = listed.keys.map((k) => k.name).sort();
+  const expected = Array.from({ length: 10 }, (_, i) => `flags/feature-${i}`).sort();
+
+  const namesMatch = names.length === 10 && names.every((n, i) => n === expected[i]);
+  const metadataOk = listed.keys.every(
+    (k) => k.metadata && typeof k.metadata === 'object' && k.metadata.v === 1 && typeof k.metadata.i === 'number',
+  );
+  const decoyAbsent = !names.includes('other/decoy');
+
+  const pass = namesMatch && metadataOk && decoyAbsent;
+
+  return {
+    results: [{
+      anchorAcId: 'AC-5102-1',
+      verdict: pass ? 'pass' : 'fail',
+      detail: pass
+        ? `list({prefix: flags/}) returned 10 keys under the prefix; every entry carries {name, metadata} with metadata.v=1; decoy key outside prefix was NOT included`
+        : `list-with-prefix fault: namesMatch=${namesMatch} metadataOk=${metadataOk} decoyAbsent=${decoyAbsent} names=${JSON.stringify(names)}`,
+    }],
+  };
+}

package/blueprints/platform-cloudflare-kv/contributions/probes/probe-utils.mjs

@@ -0,0 +1,73 @@
+// Shared helpers for platform-cloudflare-kv probes.
+//
+// Runtime-dependency posture: probes import the fixture's in-memory
+// KV driver, KV facade, and cache-aside helper from the cf-platform
+// fixture's src/ tree so rcf-lite itself gains no new runtime
+// dependency. The wrangler.toml alongside declares the real KV
+// [[kv_namespaces]] binding shape a project would receive when
+// composing against live Workers KV; the in-memory driver realises
+// the same binding shape (get, getWithMetadata, put, delete, list)
+// so the facade module is indistinguishable from a live-KV run at
+// the facade boundary.
+//
+// The real-account eventual-consistency smoke opens the facade
+// against a real KV namespace via the Workers KV REST API when the
+// CI_HAS_CLOUDFLARE_ACCOUNT env var is set; without the env var it
+// records accountBoundSkipped and aggregates to pass per spec
+// section 3.5.
+
+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/cf-platform');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/platform-cloudflare-kv');
+
+export function aggregate(results) {
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  if (results.some((r) => r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+
+export async function writeReport({ probeName, engine, results, extra }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const report = {
+    slug: 'platform-cloudflare-kv',
+    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) + '\n', 'utf8');
+  return { report, path };
+}
+
+// Wraps a probe's async main body and reports. Never calls
+// process.exit after the large report write: sets process.exitCode
+// and lets Node drain stdout naturally.
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const { results, extra } = 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`);
+    if (report.aggregateVerdict !== 'pass') process.exitCode = 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.exitCode = 1;
+  }
+}

package/blueprints/platform-cloudflare-kv/contributions/probes/real-account-eventual-consistency-smoke.mjs

@@ -0,0 +1,102 @@
+// Real-account eventual-consistency smoke for platform-cloudflare-kv
+// v1.0.0.
+//
+// Opens the facade against a real Cloudflare KV namespace via the
+// Workers KV REST API (per https://developers.cloudflare.com/api/
+// operations/workers-kv-namespace-write-key-value-pair). Writes a
+// fixture key, waits up to 60 seconds bounded (poll every 2s), then
+// reads and asserts the write eventually appears. The probe does
+// NOT bind a specific propagation time; only that a write eventually
+// becomes visible under the 60-second cap. Cleans up the written
+// key on exit.
+//
+// accountBound: true. Without CI_HAS_CLOUDFLARE_ACCOUNT (and the
+// paired CF_ACCOUNT_ID, CF_KV_NAMESPACE_ID, CF_API_TOKEN env vars),
+// the probe records accountBoundSkipped: true and the aggregate
+// flips to pass per spec section 3.5.
+//
+// anchorAcId: AC-5401-1.
+
+export const anchorAcId = 'AC-5401-1';
+export const accountBound = true;
+
+const CAP_MS = 60_000;
+const POLL_INTERVAL_MS = 2_000;
+const API_BASE = 'https://api.cloudflare.com/client/v4';
+
+export default async function runProbe() {
+  if (process.env.CI_HAS_CLOUDFLARE_ACCOUNT !== 'true') {
+    return {
+      results: [{
+        anchorAcId: 'AC-5401-1',
+        verdict: 'pass',
+        detail: 'accountBoundSkipped: CI_HAS_CLOUDFLARE_ACCOUNT is not set to true; spec section 3.5 pass-with-skip.',
+      }],
+      extra: { accountBoundSkipped: true },
+    };
+  }
+
+  const accountId = process.env.CF_ACCOUNT_ID;
+  const namespaceId = process.env.CF_KV_NAMESPACE_ID;
+  const token = process.env.CF_API_TOKEN;
+  if (!accountId || !namespaceId || !token) {
+    return {
+      results: [{
+        anchorAcId: 'AC-5401-1',
+        verdict: 'fail',
+        detail: `CI_HAS_CLOUDFLARE_ACCOUNT=true but one of CF_ACCOUNT_ID/CF_KV_NAMESPACE_ID/CF_API_TOKEN is missing: accountIdPresent=${!!accountId} namespaceIdPresent=${!!namespaceId} tokenPresent=${!!token}`,
+      }],
+    };
+  }
+
+  const key = `platform-cloudflare-kv/real-account-smoke/${Date.now()}`;
+  const value = `smoke-${Math.random().toString(36).slice(2)}`;
+  const putUrl = `${API_BASE}/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(key)}`;
+  const authHeaders = { authorization: `Bearer ${token}`, 'content-type': 'text/plain' };
+
+  const putResp = await fetch(putUrl, { method: 'PUT', headers: authHeaders, body: value });
+  if (!putResp.ok) {
+    return {
+      results: [{
+        anchorAcId: 'AC-5401-1',
+        verdict: 'fail',
+        detail: `real-account smoke: PUT returned status ${putResp.status}`,
+      }],
+    };
+  }
+
+  const start = Date.now();
+  let observed = null;
+  while (Date.now() - start < CAP_MS) {
+    const getResp = await fetch(putUrl, { method: 'GET', headers: { authorization: `Bearer ${token}` } });
+    if (getResp.ok) {
+      const body = await getResp.text();
+      if (body === value) {
+        observed = body;
+        break;
+      }
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+
+  const elapsed = Date.now() - start;
+
+  // Clean up the written key regardless of outcome.
+  try {
+    await fetch(putUrl, { method: 'DELETE', headers: { authorization: `Bearer ${token}` } });
+  } catch (_err) {
+    // Best effort; do not fail the probe on cleanup.
+  }
+
+  const pass = observed === value;
+  return {
+    results: [{
+      anchorAcId: 'AC-5401-1',
+      verdict: pass ? 'pass' : 'fail',
+      detail: pass
+        ? `write eventually appeared on the same-region read within elapsed=${elapsed}ms (CAP=${CAP_MS}ms)`
+        : `write did not appear within CAP=${CAP_MS}ms; elapsed=${elapsed}ms`,
+    }],
+    extra: { elapsedMs: elapsed, cap: CAP_MS },
+  };
+}

package/blueprints/platform-cloudflare-kv/contributions/probes/run-cache-aside-hit-then-miss.mjs

@@ -0,0 +1,5 @@
+import runProbe from './cache-aside-hit-then-miss.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'kv', image: 'in-memory KV driver realising Workers KV binding shape', healthy: true };
+runShim('cache-aside-hit-then-miss', engine, runProbe);

package/blueprints/platform-cloudflare-kv/contributions/probes/run-event-secrecy.mjs

@@ -0,0 +1,5 @@
+import runProbe from './event-secrecy.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'kv', image: 'in-memory KV driver realising Workers KV binding shape', healthy: true };
+runShim('event-secrecy', engine, runProbe);

package/blueprints/platform-cloudflare-kv/contributions/probes/run-facade-round-trip.mjs

@@ -0,0 +1,5 @@
+import runProbe from './facade-round-trip.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'kv', image: 'in-memory KV driver realising Workers KV binding shape', healthy: true };
+runShim('facade-round-trip', engine, runProbe);

package/blueprints/platform-cloudflare-kv/contributions/probes/run-list-with-prefix.mjs

@@ -0,0 +1,5 @@
+import runProbe from './list-with-prefix.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'kv', image: 'in-memory KV driver realising Workers KV binding shape', healthy: true };
+runShim('list-with-prefix', engine, runProbe);

package/blueprints/platform-cloudflare-kv/contributions/probes/run-real-account-eventual-consistency-smoke.mjs

@@ -0,0 +1,5 @@
+import runProbe from './real-account-eventual-consistency-smoke.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'kv', image: 'live Cloudflare Workers KV via REST API (or skipped)', healthy: true };
+runShim('real-account-eventual-consistency-smoke', engine, runProbe);

package/blueprints/platform-cloudflare-kv/contributions/requirements/platform-cloudflare-kv-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-cloudflare-kv-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The KV facade module is the sole reader of the KV binding and opens on boot with facadeReady",
+  "description": "The applying project reaches Cloudflare Workers KV through a single facade module in the project source tree that is the ONLY module holding a reference to env.<binding> (env.CACHE in the cf-platform fixture; the elicited binding name in a real project). Every other module that touches KV imports the facade and calls its typed domain verbs (get, getWithMetadata, put, delete, list); no other module dereferences the raw KV binding. On process boot, the facade opens against the bound namespace via a bounded list(limit:1) ready-check and, once ready, emits a facadeReady lifecycle event on the injected event sink. The binding name is elicited at apply time and the elicited answer is written into wrangler.toml under [[kv_namespaces]] binding = \"<name>\" per https://developers.cloudflare.com/kv/api/.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (2026-09-06 section 5.1). Ships as v1.0.0 of platform-cloudflare-kv.",
+  "tags": [
+    "blueprint:platform-cloudflare-kv",
+    "category:001-the"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T10:26:28.000Z",
+  "updatedAt": "2026-09-07T10:26:28.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/requirements/platform-cloudflare-kv-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-cloudflare-kv-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Typed put get delete list verbs with the metadata field pattern realise the Workers KV binding shape behind the facade",
+  "description": "The facade exposes typed named domain verbs put(key, value, {ttl?, metadata?}), get(key), getWithMetadata(key), delete(key) and list({prefix?, limit?, cursor?}) whose contracts map directly onto the Cloudflare Workers KV binding shape per https://developers.cloudflare.com/kv/api/. put writes with expirationTtl (per the elicited default TTL from ADR-3202) and metadata (per the elicited default metadata field pattern; ship default {v: number}); get returns null on miss; getWithMetadata returns {value, metadata}; delete is idempotent; list paginates keys with metadata shape intact. Metadata is a JSON-serialisable object; the facade never rewrites it before storage.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (2026-09-06 section 5.1). Ships as v1.0.0 of platform-cloudflare-kv.",
+  "tags": [
+    "blueprint:platform-cloudflare-kv",
+    "category:002-typed"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T10:26:28.000Z",
+  "updatedAt": "2026-09-07T10:26:28.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/requirements/platform-cloudflare-kv-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-cloudflare-kv-REQ-003",
+  "prdId": "PRD-001",
+  "title": "The cache-aside helper reads local first, falls back to origin, writes back with elicited TTL floor 1 second",
+  "description": "The blueprint ships a cache-aside helper (src/cache-aside.mjs on the applied fixture) that wraps a domain-origin call with a facade read. getOr(key, originFn, {ttl?}) reads local first via facade.get; on hit returns the cached value with source \"cache\"; on miss invokes originFn, writes back via facade.put with the effective TTL (elicited default 60 seconds per ADR-3202; floor 1 second enforced at this seam so a misconfigured project cannot ship a sub-second TTL through cache-aside), and returns the fresh value with source \"origin\". No upper ceiling is imposed by the helper; the Cloudflare KV per-namespace limits at https://developers.cloudflare.com/kv/platform/limits/ are the vendor ceiling.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (2026-09-06 section 5.1). Ships as v1.0.0 of platform-cloudflare-kv.",
+  "tags": [
+    "blueprint:platform-cloudflare-kv",
+    "category:003-the"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T10:26:28.000Z",
+  "updatedAt": "2026-09-07T10:26:28.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/requirements/platform-cloudflare-kv-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-cloudflare-kv-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Lifecycle events facadeReady kvHit kvMiss kvWrite carry metadata-only fields key size ttl timestamp",
+  "description": "The facade emits four lifecycle events on the injected sink: facadeReady once on the first ready-check resolving; kvHit on a get returning a non-null value; kvMiss on a get returning null; kvWrite on put and on delete. Every event record carries EXACTLY the whitelist {event, key, size, ttl, timestamp} and NOTHING else: no body bytes, no metadata pass-through, no user id beyond the key itself. The event-secrecy probe drives this at mechanism reach with a PII fixture body and asserts the whitelist under both the shipped code path and a mutation-run.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (2026-09-06 section 5.1). Ships as v1.0.0 of platform-cloudflare-kv.",
+  "tags": [
+    "blueprint:platform-cloudflare-kv",
+    "category:004-lifecycle"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T10:26:28.000Z",
+  "updatedAt": "2026-09-07T10:26:28.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/requirements/platform-cloudflare-kv-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "platform-cloudflare-kv-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Eventual-consistency note in the guide: a write may not appear on a global read within the same request and the elicited TTL sets the staleness ceiling",
+  "description": "Workers KV is eventually consistent per https://developers.cloudflare.com/kv/concepts/how-kv-works/. The guide surfaces the note (a write may not appear on a global read within the same request; changes may take up to 60 seconds or more to be visible in other network locations as cached versions time out) and states that the elicited cache-aside TTL (default 60 seconds per Cloudflare-documented cache TTL default) sets the staleness ceiling readers observe. The guide also carries a decision-tree cross-reference to platform-cloudflare-durable-objects (round-6 T-3) for cases needing stronger-consistency semantics; DO is the shipped answer when a key must have exactly one owner and every read must reflect the most recent write.",
+  "category": "functional",
+  "domain": "platform",
+  "priority": "must",
+  "rationale": "Ratified in the Cloudflare round 6 spec (2026-09-06 section 5.1). Ships as v1.0.0 of platform-cloudflare-kv.",
+  "tags": [
+    "blueprint:platform-cloudflare-kv",
+    "category:005-eventual-consistency"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T10:26:28.000Z",
+  "updatedAt": "2026-09-07T10:26:28.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/tacs/tac-3201-platform-cloudflare-kv-facade.json

@@ -0,0 +1,27 @@
+{
+  "tacId": "TAC-3201-platform-cloudflare-kv-facade",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Platform-cloudflare-kv facade",
+  "purpose": "The single project-side module that dereferences the Cloudflare Workers KV binding (env.<binding>), exposes narrow named domain verbs (get, getWithMetadata, put, delete, list) to consumer code, and emits structured lifecycle events to the event sink (TAC-3203). Consumers never touch the raw binding outside this module; the facade is the one place the vendor surface lives. The KV driver reference is opaque at this boundary so a future adapter (a different vendor, an in-memory driver for tests) slots in without a facade re-shape.",
+  "responsibilities": [
+    "Open the facade on boot against the elicited KV binding via a bounded list(limit:1) ready-check; hold no other reference to the KV vendor surface; export no symbol that leaks the raw binding (AC-31101-1, AC-31102-1).",
+    "Expose named domain verbs (get, getWithMetadata, put, delete, list) as returned methods on the factory result; refuse a raw-binding passthrough on the public surface (AC-31101-1).",
+    "Emit facadeReady exactly once per facade instance on the injected event sink (AC-31101-1); serialise pre-ready operations behind the ready-check.",
+    "Emit kvHit / kvMiss / kvWrite per operation, all metadata-only per TAC-3203 (AC-31107-1, AC-31108-1).",
+    "Apply the elicited keyPrefix (a per-app namespace disambiguator) transparently on every operation so the domain code sees prefix-free keys and the storage layer sees fully qualified keys (elicited answer per ADR-3203)."
+  ],
+  "internalStructure": "One module exporting a createKvFacade({ binding, eventSink, keyPrefix?, defaultCacheTtl? }) factory returning a KvFacade whose methods are the named domain verbs. The binding dereference lives at the top of this module; the factory captures the binding, wires the sink, and hands back closures. Consumers call the facade methods for the process lifetime; the raw binding never crosses the module boundary.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "factory",
+      "summary": "Platform-cloudflare-kv facade factory exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-07T10:28:32.000Z",
+  "updatedAt": "2026-09-07T10:28:32.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/tacs/tac-3202-platform-cloudflare-kv-cache-aside.json

@@ -0,0 +1,26 @@
+{
+  "tacId": "TAC-3202-platform-cloudflare-kv-cache-aside",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Platform-cloudflare-kv cache-aside helper",
+  "purpose": "The cache-aside helper wraps a domain-origin call with the facade. It is the shipped shape for a read-through cache: reads local first, invokes origin on miss, writes back with the elicited TTL, and returns the fresh value. TTL floor (1 second) is enforced at this seam so a misconfigured project cannot ship a sub-second TTL through cache-aside (ADR-3202).",
+  "responsibilities": [
+    "Read local first via facade.get(key); on hit, return the cached value with source cache (AC-31105-1).",
+    "On miss, invoke originFn once; write back via facade.put with the effective TTL (elicited default 60 seconds per ADR-3202); return the fresh value with source origin (AC-31105-1).",
+    "After the TTL elapses, re-invoke origin on the next read (AC-31106-1).",
+    "Enforce the TTL floor of 1 second on every call; no per-call TTL below 1 second reaches the facade (ADR-3202)."
+  ],
+  "internalStructure": "One module exporting a createCacheAside({ facade, defaultTtl }) factory returning an object with a getOr(key, originFn, options?) method. The helper closes over the facade and the default TTL; per-call TTL overrides are floored to 1 second.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "factory",
+      "summary": "Platform-cloudflare-kv cache-aside helper factory exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-07T10:28:32.000Z",
+  "updatedAt": "2026-09-07T10:28:32.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/tacs/tac-3203-platform-cloudflare-kv-event-sink.json

@@ -0,0 +1,25 @@
+{
+  "tacId": "TAC-3203-platform-cloudflare-kv-event-sink",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Platform-cloudflare-kv event sink boundary",
+  "purpose": "The event sink is the boundary between the KV facade and the applied logging companion (or a spy sink in the local probes). The facade emits four events (facadeReady, kvHit, kvMiss, kvWrite) whose payloads are metadata-only: {event, key, size, ttl, timestamp}. No body bytes, no metadata blob, no user id beyond the key itself ever crosses this boundary.",
+  "responsibilities": [
+    "Accept exactly the whitelist {event, key, size, ttl, timestamp} on every record emitted by the facade (AC-31107-1).",
+    "Never forward a body byte, a metadata blob, or any additional field appended by a downstream mutation (AC-31108-1).",
+    "Serialise events in emit order so a downstream logging companion can observe the causal ordering per-operation."
+  ],
+  "internalStructure": "The facade calls the sink as a function reference; the sink either accumulates records (spy in probes) or forwards them into the applied logging companion. The shape is enforced at the facade side by constructing each record explicitly from the metadata-only fields.",
+  "interfaces": [
+    {
+      "name": "default export",
+      "kind": "factory",
+      "summary": "Platform-cloudflare-kv event sink boundary factory exported from the applied fixture module."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-07T10:28:32.000Z",
+  "updatedAt": "2026-09-07T10:28:32.000Z"
+}