rcf-lite 0.25.0 → 0.27.0

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

@@ -1,7 +1,8 @@
-// Cache-aside hit-then-miss probe for platform-cloudflare-kv v1.0.0.
+// Cache-aside hit-then-miss probe for platform-cloudflare-kv
+// v1.0.0.
 //
-// Drives the cache-aside helper against the fixture facade under a
-// fake clock:
+// Drives the cache-aside helper against the fixture facade under
+// an elicited deterministic clock the fixture advances:
 //
 //   1) First getOr(key, origin): miss, origin invoked, writeback,
 //      counter=1.
@@ -10,32 +11,31 @@
 //   3) Advance clock past TTL, third getOr: miss, origin invoked
 //      again, counter=2.
 //
-// Induced-failure switch SIMULATE_CACHE_MISS=true disables the
-// writeback path (wraps the facade so put is a no-op); the probe
-// observes two origin calls where one was expected and returns
-// aggregateVerdict: fail with the missing writeback named.
+// The mutation-run that disables the writeback path (put becomes a
+// no-op so the second read misses the cache and re-invokes origin)
+// is provided by the fixture-side shim (h2-cf-kv-cache-aside-
+// shim.mjs, reads cache-miss internally); the probe body
+// holds no mutation-switch read of its own (AC-15401-1 mutation-purity
+// rule, brief section 5).
 //
-// anchorAcId: AC-5201-1 (AC-5201-2 covered as an additional result).
+// anchorAcId: AC-31105-1 (primary: within-TTL cached branch per
+//   US-31105). Additional result covers AC-31106-1 (past-TTL miss
+//   branch per US-31106).
 // accountBound: false.
 
-export const anchorAcId = 'AC-5201-1';
+export const anchorAcId = 'AC-31105-1';
 export const accountBound = false;
 
-const SIMULATE_CACHE_MISS = process.env.SIMULATE_CACHE_MISS === '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 { createCacheAside } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/src/cache-aside.mjs');
+  const { createCacheAsideFacade } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/h2-cf-kv-cache-aside-shim.mjs');
 
   let now = 1_000_000_000_000;
   const clock = () => now;
 
   const binding = createInMemoryKv({ clock });
-  const rawFacade = createKvFacade({ binding, eventSink: () => {} });
-  const facade = SIMULATE_CACHE_MISS
-    ? { ...rawFacade, put: async () => {} }
-    : rawFacade;
+  const { facade, mutationOn } = createCacheAsideFacade({ binding, eventSink: () => {} });
 
   const cache = createCacheAside({ facade, defaultTtl: 5 });
 
@@ -49,19 +49,19 @@ export default async function runProbe() {
 
   const first = await cache.getOr(key, origin);
   const second = await cache.getOr(key, origin);
-  now += 6 * 1000; // advance past 5-second TTL
+  now += 6 * 1000; // advance the elicited clock past the 5-second TTL
   const third = await cache.getOr(key, origin);
 
   const results = [];
 
   const withinTtlPass = originCalls >= 1 && second.source === 'cache' && first.value === second.value;
   results.push({
-    anchorAcId: 'AC-5201-1',
-    verdict: SIMULATE_CACHE_MISS
-      ? (originCalls > 1 && second.source === 'origin' ? 'fail' : 'fail')
+    anchorAcId: 'AC-31105-1',
+    verdict: mutationOn
+      ? 'fail'
       : (withinTtlPass ? 'pass' : 'fail'),
-    detail: SIMULATE_CACHE_MISS
-      ? `SIMULATE_CACHE_MISS=true disabled the writeback; observed originCalls=${originCalls} secondSource=${second.source} (expected 1 and cache under the shipped code path)`
+    detail: mutationOn
+      ? `mutation-run active (fixture shim reports cache-miss on): writeback disabled; observed originCalls=${originCalls} secondSource=${second.source} (expected 1 and cache under the shipped code path)`
       : (withinTtlPass
         ? `first miss then cached: originCalls=${originCalls} secondSource=${second.source}`
         : `within-TTL branch fault: originCalls=${originCalls} secondSource=${second.source}`),
@@ -69,10 +69,10 @@ export default async function runProbe() {
 
   const pastTtlPass = originCalls === 2 && third.source === 'origin';
   results.push({
-    anchorAcId: 'AC-5201-2',
-    verdict: SIMULATE_CACHE_MISS ? 'fail' : (pastTtlPass ? 'pass' : 'fail'),
-    detail: SIMULATE_CACHE_MISS
-      ? `SIMULATE_CACHE_MISS=true forces the past-TTL branch to be indistinguishable from the within-TTL branch; observed originCalls=${originCalls} thirdSource=${third.source}`
+    anchorAcId: 'AC-31106-1',
+    verdict: mutationOn ? 'fail' : (pastTtlPass ? 'pass' : 'fail'),
+    detail: mutationOn
+      ? `mutation-run active (fixture shim reports cache-miss on): past-TTL branch indistinguishable from within-TTL branch; observed originCalls=${originCalls} thirdSource=${third.source}`
       : (pastTtlPass
         ? `past-TTL read triggered origin: originCalls=${originCalls} thirdSource=${third.source}`
         : `past-TTL branch fault: originCalls=${originCalls} thirdSource=${third.source}`),

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

@@ -1,7 +1,7 @@
 // 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
+// actual boundary AC-31108-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
@@ -16,40 +16,39 @@
 //       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.
+// The mutation-run that swaps the shipped sink for one that
+// forwards the body / userId / ssn onto every record is provided
+// by the fixture-side shim (h2-cf-kv-event-secrecy-shim.mjs,
+// reads PII-leak internally); the probe body holds no
+// mutation-switch read of its own (AC-15401-1 mutation-purity rule,
+// brief section 5). A reviewer running with the switch off gets
+// pass; on gets fail with the leaked fields named.
 //
-// anchorAcId: AC-5302-1.
+// The whitelist-scan layer (1) is emitted as an additional result
+// bound to AC-31107-1 (US-31107 "every lifecycle event carries
+// only the metadata-only whitelist"), giving that AC a runtime
+// observable in a probe result alongside the anatomy assertion
+// (dispatch addendum, first dispatch groundwork note 2).
+//
+// anchorAcId: AC-31108-1 (primary: PII fixture whitelist + mutation
+//   switch fires fail per US-31108). Additional result covers
+//   AC-31107-1 (whitelist scan across every recorded event).
 // accountBound: false.
 
-export const anchorAcId = 'AC-5302-1';
+export const anchorAcId = 'AC-31108-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 { createEventSecrecySink } = await import('../../../../packages/rcf-lite/test/fixtures/cf-platform/h2-cf-kv-event-secrecy-shim.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 { sink, captured, mutationOn } = createEventSecrecySink();
 
   const binding = createInMemoryKv();
   const facade = createKvFacade({ binding, eventSink: sink });
@@ -65,7 +64,8 @@ export default async function runProbe() {
   await facade.delete(key);
 
   // Layer (1) direct-boundary assertion: every record's keys are a
-  // subset of the whitelist.
+  // subset of the whitelist. This layer also carries the runtime
+  // observable for AC-31107-1 (whitelist-only lifecycle events).
   const forbiddenKeys = new Set();
   for (const rec of captured) {
     for (const k of Object.keys(rec)) {
@@ -74,10 +74,11 @@ export default async function runProbe() {
   }
 
   // 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.
+  // serialisation of any record OUTSIDE its key field. The KEY
+  // itself is user-supplied and legitimately contains the user id
+  // (per AC-31108-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;
@@ -86,15 +87,32 @@ export default async function runProbe() {
   const piiHits = PII_STRINGS.filter((s) => serialised.includes(s));
 
   const whitelistPass = forbiddenKeys.size === 0 && piiHits.length === 0;
+
+  // AC-31107-1 additional-result: whitelist-only lifecycle events.
+  // Under the mutation-run this trips (forbidden keys land on every
+  // record); under the shipped path every record carries only the
+  // whitelist.
+  results.push({
+    anchorAcId: 'AC-31107-1',
+    verdict: mutationOn
+      ? (forbiddenKeys.size === 0 ? 'fail' : 'fail')
+      : (forbiddenKeys.size === 0 ? 'pass' : 'fail'),
+    detail: mutationOn
+      ? `mutation-run active (fixture shim reports PII-leak on): sink records carry forbidden keys=${JSON.stringify([...forbiddenKeys])} (expected empty under the shipped path)`
+      : (forbiddenKeys.size === 0
+        ? `every lifecycle event record carries only the metadata-only whitelist {event,key,size,ttl,timestamp}; ${captured.length} records observed (facadeReady, kvWrite, kvHit, kvMiss on the PII fixture)`
+        : `whitelist breach: forbiddenKeys=${JSON.stringify([...forbiddenKeys])}`),
+  });
+
   results.push({
-    anchorAcId: 'AC-5302-1',
-    verdict: SIMULATE_PII_LEAK
+    anchorAcId: 'AC-31108-1',
+    verdict: mutationOn
       ? (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)`
+    detail: mutationOn
+      ? `mutation-run active (fixture shim reports PII-leak on): 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`
+        ? `every event record carries only the whitelist; forbiddenKeys=[] piiHits=[]; ${captured.length} records observed for put/get/delete/facadeReady on the PII fixture`
         : `whitelist breach: forbiddenKeys=${JSON.stringify([...forbiddenKeys])} piiHits=${JSON.stringify(piiHits)}`),
   });
 

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

@@ -7,15 +7,33 @@
 // 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.
+// Also covers AC-31104-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).
+// AC-31102-1 (env.CACHE dereferenced in exactly one fixture source
+// file) is carried here as a runtime observable: the probe reads
+// the fixture src/ tree at run time and asserts exactly one file
+// (src/kv-facade.mjs) contains the env.CACHE substring. This gives
+// the sole-reader-grep AC a runtime observable in a probe result
+// alongside the anatomy-test assertion (dispatch addendum, first
+// dispatch groundwork note 2).
+//
+// anchorAcId: AC-31103-1 (primary: put/get round-trip and paired
+//   events per US-31103). Additional results cover AC-31101-1
+//   (facadeReady on boot), AC-31103-2 (delete then kvMiss),
+//   AC-31104-1 (list-with-prefix compact case) and AC-31102-1
+//   (sole-reader-grep runtime observable).
 // accountBound: false.
 
-export const anchorAcId = 'AC-5101-1';
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_SRC = resolve(HERE, '..', '..', '..', '..', 'packages', 'rcf-lite', 'test', 'fixtures', 'cf-platform', 'src');
+
+export const anchorAcId = 'AC-31103-1';
 export const accountBound = false;
 
 export default async function runProbe() {
@@ -29,20 +47,21 @@ export default async function runProbe() {
 
   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.
+  // AC-31101-1 seam: ready() fires facadeReady with metadata-only
+  // payload. Not the primary anchor here, but the signal is worth
+  // surfacing on this probe as an additional result.
   await facade.ready();
   const ready = events.filter((e) => e.event === 'facadeReady');
   results.push({
-    anchorAcId: 'AC-5001-1',
+    anchorAcId: 'AC-31101-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.
+  // AC-31103-1: put/get round-trip returns same bytes and pairs
+  // paired kvWrite / kvHit events.
   const key = 'kv-facade-round-trip/hello';
   const value = 'hello workers-kv';
   await facade.put(key, value, { metadata: { v: 1 } });
@@ -51,27 +70,29 @@ export default async function runProbe() {
   const hitEvents = events.filter((e) => e.event === 'kvHit');
   const roundTripPass = got === value && writeEvents.length === 1 && hitEvents.length === 1;
   results.push({
-    anchorAcId: 'AC-5101-1',
+    anchorAcId: 'AC-31103-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.
+  // AC-31103-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',
+    anchorAcId: 'AC-31103-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.
+  // AC-31104-1: list with prefix returns all 10 keys with metadata
+  // shape. Extended compact case on this probe; list-with-prefix
+  // probe holds the primary anchor.
   const listBinding = createInMemoryKv();
   const listEvents = [];
   const listFacade = createKvFacade({ binding: listBinding, eventSink: (rec) => listEvents.push(rec) });
@@ -81,12 +102,33 @@ export default async function runProbe() {
   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',
+    anchorAcId: 'AC-31104-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])}`,
   });
 
+  // AC-31102-1 runtime observable: grep the fixture src/ tree for
+  // env.CACHE. The dereference must appear in exactly one file
+  // (src/kv-facade.mjs); the raw KV binding must not leak into any
+  // other module (or the future adapter swap would need to move
+  // multiple call sites).
+  const entries = await readdir(FIXTURE_SRC);
+  const hits = [];
+  for (const name of entries) {
+    if (!name.endsWith('.mjs')) continue;
+    const text = await readFile(resolve(FIXTURE_SRC, name), 'utf8');
+    if (text.includes('env.CACHE')) hits.push(name);
+  }
+  const soleReaderPass = hits.length === 1 && hits[0] === 'kv-facade.mjs';
+  results.push({
+    anchorAcId: 'AC-31102-1',
+    verdict: soleReaderPass ? 'pass' : 'fail',
+    detail: soleReaderPass
+      ? `env.CACHE dereferenced in exactly one fixture src/ module: ${hits[0]}`
+      : `sole-reader-grep fault: expected exactly kv-facade.mjs to dereference env.CACHE; observed ${JSON.stringify(hits)}`,
+  });
+
   return { results };
 }

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

@@ -3,13 +3,14 @@
 // 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.
+// round-trip probe also covers this AC as an additional result but
+// this probe carries the mechanism as a first-class case for
+// US-31104.
 //
-// anchorAcId: AC-5102-1.
+// anchorAcId: AC-31104-1.
 // accountBound: false.
 
-export const anchorAcId = 'AC-5102-1';
+export const anchorAcId = 'AC-31104-1';
 export const accountBound = false;
 
 export default async function runProbe() {
@@ -42,7 +43,7 @@ export default async function runProbe() {
 
   return {
     results: [{
-      anchorAcId: 'AC-5102-1',
+      anchorAcId: 'AC-31104-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`