rcf-lite 0.22.0 → 0.24.0

package/blueprints/platform-cloudflare-durable-objects/guide/platform-cloudflare-durable-objects.md

@@ -0,0 +1,237 @@
+# platform-cloudflare-durable-objects guide
+
+## When to reach for this blueprint
+
+You reach for `platform-cloudflare-durable-objects` when your
+Worker needs strongly consistent authoritative state, coordinated
+multiplayer websocket connections, or both on the same DO namespace
+mechanic. Two shapes ship in one blueprint: the SINGLE-CELL shape
+(counter, session store, lock, coordinator) and the WEBSOCKET-HUB
+shape (rooms, presence, live cursors).
+
+If you need eventually-consistent low-latency reads on a read-hot
+path (feature flags, session cache, config cache), reach for
+`platform-cloudflare-kv` (round 6 T-1) instead. If you need
+durable multi-step workflows with retries and state across steps,
+reach for the follow-up Workflows adapter on `jobs-background`
+v1.1.0 (round-6 minor bump per spec section 5.7).
+
+## Decision tree
+
+- Strongly consistent authoritative cell (counter, session store,
+  lock, coordinator) -> SINGLE-CELL shape (this blueprint,
+  `platform-cloudflare-durable-objects` v1.0.0).
+- Coordinated multiplayer websocket connections in one authoritative
+  hub (rooms, live cursors, presence) -> WEBSOCKET-HUB shape (this
+  blueprint, same v1.0.0).
+- Cache-shaped eventually-consistent reads -> `platform-cloudflare-kv`
+  v1.0.0.
+- Durable multi-step workflow -> follow-up Workflows adapter on
+  `jobs-background` v1.1.0.
+- Not on Cloudflare Workers -> reach for a platform-native
+  strongly-consistent adapter when one ships; the shelf has no
+  non-Cloudflare strong-consistency cell blueprint today.
+
+## The apply-time answers
+
+Answer seven elicits at `rcf define blueprint add` time:
+
+- `do-cell-binding` (default `CELL`): the DO namespace binding name
+  under `[[durable_objects.bindings]]` in wrangler.toml for the
+  single-cell shape.
+- `do-hub-binding` (default `HUB`): the DO namespace binding name
+  for the hub shape.
+- `do-cell-class-name` (default `SingleCellObject`): the stable class
+  name string committed under the mint `[[migrations]]` tag. A
+  future rename lands as a subsequent migrations tag, not a silent
+  edit.
+- `do-hub-class-name` (default `HubObject`): the stable class name
+  string for the hub class.
+- `do-storage-backend` (default `sql` per ADR-3403): SQL (typed
+  columns, query) or KV (simple `put`/`get`/`delete`/`list`).
+- `do-hub-broadcast-window-ms` (default `500`): the elicited window
+  for broadcast fan-out from A to all connected sockets.
+- `do-hub-hibernate-after-idle-ms` (default `30000` per ADR-3405):
+  the hibernate-after-idle window on the hub shape. The wake
+  handler is idempotent-by-contract per the same ADR.
+
+## The two shapes: single-cell first
+
+The single-cell shape is one named object exposing typed domain
+verbs. Cloudflare's DO runtime serialises invocations against the
+same instance; the shipped SingleCellObject class realises that
+contract via a per-instance FIFO promise queue so two concurrent
+callers cannot silently overwrite each other. Each increment
+resolves with a `{counter, witness}` pair: the FIFO-first caller
+sees `witness=0`, the second sees `witness=1`, and a subsequent
+read returns the sum.
+
+Storage is elicited (`sql` or `kv` per ADR-3403). The shipped
+driver factory is backend-agnostic and threads through the elicited
+answer as `driver.backend`. SQL supports typed columns and query;
+KV is simpler and single-key. Pick SQL when your object has a
+non-trivial data shape; pick KV when a single key is all you need.
+
+Alarm is a first-class surface. `setAlarm(offsetMs)` persists a
+schedule; the `alarm()` handler runs at that time, drains the
+persisted alarm from storage, and emits `doAlarmFired` on the
+injected sink with `{objectName, scheduledTime}`. Cloudflare's
+runtime guarantees exactly-once delivery per scheduled time; a
+second call to `alarm()` on the drained storage records
+`scheduledTime: null` rather than re-firing for the same schedule.
+
+## The two shapes: websocket hub
+
+The hub shape is one named object accepting websocket clients via
+`state.acceptWebSocket`. Messages route by JSON `type` field:
+`broadcast` fans out to all connected sockets (echo included, per
+the hub shape trade-off), `set-state` and `get-state` wrap the
+underlying storage.
+
+Every broadcast persists `lastBroadcast` to storage so a re-emerging
+client can catch up on the missed message. When the object goes
+idle past the elicited `hibernate-after-idle` window, Cloudflare's
+runtime hibernates the object; on the next message the wake handler
+runs from a cold start and reads the same storage. The shipped
+HubObject class emits `doWakeUp` exactly once on the first wake
+(idempotent-by-contract per ADR-3405) and returns the persisted
+`lastBroadcast` from storage so a downstream client can rebuild
+state.
+
+The elicited `do-hub-broadcast-window-ms` (default `500`) is the
+window in which A's broadcast reaches every connected socket on
+the shipped path. A tighter window is fine on a small hub; a
+looser window trades latency for fan-out cost on a busy hub.
+
+## The migration-safe class-export contract
+
+The DO class names are stable strings committed to `wrangler.toml`.
+Both binding blocks name the class explicitly; the `[[migrations]]`
+block records the mint under `tag = "v1"` with `new_classes` naming
+both classes. A copy-paste block for a fresh Worker project:
+
+```
+[[durable_objects.bindings]]
+name = "CELL"
+class_name = "SingleCellObject"
+
+[[durable_objects.bindings]]
+name = "HUB"
+class_name = "HubObject"
+
+[[migrations]]
+tag = "v1"
+new_classes = ["SingleCellObject", "HubObject"]
+```
+
+A rename in a later release ships as a NEW `[[migrations]]` tag on
+the same list (`tag = "v2"`, `renamed_classes = [...]`), never a
+silent edit of the class name. A rename without a migration is a
+runtime error the shipped anatomy assertion catches at self-review.
+
+## The sole-reader guarantee
+
+The DO facade module (`src/do-facade.mjs`) is the ONLY module in
+the applied source tree that dereferences `env.CELL` and `env.HUB`.
+Every consumer of DO calls the facade's typed handles; a call site
+outside the facade is a leak the sole-reader-scan probe surfaces
+at self-review.
+
+The probe walks every `.mjs`, `.js` and `.ts` file under the
+applied source root, strips block and line comments (so a
+documentation mention of `env.CELL` does not flag), and matches
+literal accesses against the file path. A clean scan surfaces zero
+non-facade leaks; a leak returns `aggregateVerdict: fail` and the
+review does not ship until the leak is closed.
+
+## Metadata-only lifecycle events
+
+Every lifecycle event on the sink is a metadata-only record. The
+allowed key set is `{event, key, size, ttl, timestamp, objectName,
+scheduledTime}`; no message payloads, request bodies, headers,
+cookies or PII cross the sink boundary. A logging companion
+renders records directly without a per-blueprint scrub pass.
+
+The event-secrecy assertion rides on the websocket-hub-broadcast
+probe (the shipped path emits `doAccept`, `doHibernate`, `doWakeUp`
+and the `namespaceReady` on the paired facade). Under
+`SIMULATE_PII_LEAK=true` a wrapped sink forwards synthetic
+body-bearing records; the probe surfaces the forbidden keys and
+returns fail on the AC-33106-1 result.
+
+## Composition
+
+- Consumes `deploy-cloudflare-workers` v1.2.0 (T-0). The DO bindings
+  and migrations tag land in the same `wrangler.toml`.
+- Companions `logging` and `errorHandling` supply the sink factory
+  and the internal-error record factory.
+- Complements `platform-cloudflare-kv` (round 6 T-1): DO owns the
+  strong-consistency slot; KV owns the cache-shaped eventually-
+  consistent slot. Both compose on the same Worker.
+- A future non-Cloudflare adapter on `strongConsistencyCellContract`
+  or `websocketHubContract` mints on demand; each contributes the
+  same topic string with a different answer, forcing a DELIBERATE
+  conflict the operator resolves via a project-level ADR.
+
+## Real-account smoke
+
+The `real-account-storage-smoke` probe opens the DO facade against
+a real Cloudflare account with a real DO namespace when
+`CI_HAS_CLOUDFLARE_ACCOUNT=true` (paired with `CF_ACCOUNT_ID`,
+`CF_DO_NAMESPACE_ID` and `CF_API_TOKEN`); without the env var it
+records `accountBoundSkipped: true`, aggregates to `pass`, and
+exits 0 per spec section 3.5 (Clerk pattern).
+
+## Wrangler-seam probe
+
+The eighth probe, `wrangler-seam.mjs`, spawns `wrangler dev
+--local` on the cf-platform fixture and drives the shipped DO
+facade + SingleCellObject + HubObject code path against a real
+workerd runtime:
+
+- Two concurrent `POST /cell/<id>/increment` requests route
+  through `src/index.mjs` -> `createDoFacade({env,
+  eventSink}).cellFetch(<id>, request)` -> the shipped
+  SingleCellObject class. The probe asserts per-instance
+  serialisation (sorted counters equal `[1, 2]`, sorted
+  witnesses equal `[0, 1]`; each request observed the other's
+  write).
+- One WebSocket upgrade against `/hub/<id>/connect` routes
+  through the same facade to `env.HUB` and receives one
+  broadcast frame from the HubObject fetch handler on connect
+  (payload `hello-from-hub`).
+- An additional `AC-33108-1` result on the same run greps the
+  fixture `wrangler.toml` for both `[[durable_objects.bindings]]`
+  binding pairs and the `[[migrations]]` `tag = "v1"` with
+  `new_classes`; the grep is deterministic and does not require
+  wrangler.
+
+Warn semantics per section 3.1 pass-with-skip: if the wrangler
+devDependency is missing under the fixture's `node_modules`, or
+if the CLI does not bind within the cap, the probe returns
+`aggregateVerdict: warn` (never fail). A handler thrown at the
+workerd boundary is a genuine `fail`.
+
+The routing layer in `src/index.mjs` never dereferences
+`env.CELL` or `env.HUB` directly; every DO call routes through
+`createDoFacade({env, eventSink}).cellFetch` /
+`.hubFetch` so the sole-reader guarantee still holds. The
+sole-reader-scan probe covers the boundary.
+
+## The v1.0.0 boundary: what defers to v1.1.0
+
+Per spec section 5.3, the following items are OUT of v1.0.0 and
+land as an additive v1.1.0 minor when at least one project needs
+them:
+
+- RPC-style class methods (per the DO RPC surface).
+- Storage backups.
+- Multi-object transactions across namespaces.
+
+Do not extend the shipped code path to open any of these seams in
+v1.0.0. A minor bump post-round lands the deferred items as an
+additive contribution set without a fresh blueprint.
+
+## References
+
+- Cloudflare Durable Objects overview: https://developers.cloudflare.com/durable-objects/

package/blueprints/platform-cloudflare-kv/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `platform-cloudflare-kv` are recorded here. The shape follows Keep a Changelog and Semantic Versioning per the blueprint authoring standard.
+
+## 1.0.0 (2026-09-07)
+
+### Added
+
+- v1.0.0 mint of the `platform-cloudflare-kv` blueprint, category `platform`, capabilities `["keyValueStore"]`. Ships a facade over Cloudflare Workers KV with typed put/get/delete/list verbs, a cache-aside helper, four metadata-only lifecycle events (`facadeReady`, `kvHit`, `kvMiss`, `kvWrite`), and an eventual-consistency note in the guide that sets the elicited cache-aside TTL as the staleness ceiling readers observe.
+- 5 REQs (`platform-cloudflare-kv-REQ-001..005`), 8 USs (`platform-cloudflare-kv-US-31101..31108`), 3 TACs (`TAC-3201` facade, `TAC-3202` cache-aside, `TAC-3203` event sink), 3 ADRs (`ADR-3201` scope-global on new topic `keyValueStoreContract` with `standardsTraceClause: Cloudflare Workers KV documented consistency model`; `ADR-3202` default cache-aside TTL 60 seconds floor 1 second `elicited: true`; `ADR-3203` key naming convention `recommendedDefault: prefixed` `elicited: true`).
+- 5 Node-only probes under `contributions/probes/`: `facade-round-trip`, `cache-aside-hit-then-miss`, `event-secrecy`, `list-with-prefix` (four local probes driving the in-memory KV driver on the `cf-platform` fixture) and `real-account-eventual-consistency-smoke` (`accountBound: true`; skipped in CI without `CI_HAS_CLOUDFLARE_ACCOUNT`).
+- Elicited parameters on `blueprint.json`: `kv-binding-name` (default `CACHE`), `kv-default-cache-ttl-seconds` (default `60`, floor `1`), `kv-metadata-field-pattern` (default `{v:1}`), `kv-key-naming-convention` (default `prefixed`).
+- `suggestedCompanions`: `logging` (for the event-sink boundary) and `errorHandling` (for the error record shape).
+- Extends the shared `cf-platform` sample-app fixture with the `[[kv_namespaces]]` binding block (name `CACHE`), the sole-reader KV facade module (`src/kv-facade.mjs`), the cache-aside helper (`src/cache-aside.mjs`), and the in-memory KV driver (`src/kv-driver.mjs`) that realises the Workers KV binding shape so the local probes drive without a live-KV dependency.
+- Anatomy test at `packages/rcf-lite/test/blueprint/platform-cloudflare-kv-anatomy.test.js` covers `TS-080..087` on the T-1 chain slice (blueprint shape, contributions cross-check, probe module contracts, fixture files, ADR bodies and clauses, guide sections and URLs, three-state probed verdicts).
+
+### Known limitations
+
+- The `real-account-eventual-consistency-smoke` probe records `accountBoundSkipped: true` and aggregates to `pass` when `CI_HAS_CLOUDFLARE_ACCOUNT` is unset (spec section 3.5 pass-with-skip). Full mechanism reach requires a CI environment with the paired `CF_ACCOUNT_ID`, `CF_KV_NAMESPACE_ID` and `CF_API_TOKEN` env vars.
+- The four local probes drive an in-memory KV driver whose shape matches the Workers KV binding at the facade boundary. Vendor surface changes beyond that boundary (a new list cursor format, a header-only limit) are not caught by the local probes; the real-account smoke is the mechanism-reach closure for that gap.
+- The loader's supported `when` block on `elicits[]` only accepts `requiresCapability` arrays, so the elicited `kv-metadata-field-pattern` cannot yet gate on an `elicitedNonEmpty` predicate for `kv-binding-name`. A future loader minor extending `validateElicits` would close that gap; the elicit fires unconditionally today and the guide teaches the pattern.

package/blueprints/platform-cloudflare-kv/README.md

@@ -0,0 +1,159 @@
+# platform-cloudflare-kv
+
+A rcf-lite blueprint that ships a small, opinionated facade over
+Cloudflare Workers KV plus a cache-aside helper. One module holds the
+KV binding; every other module reads through typed domain verbs; every
+KV operation emits a metadata-only lifecycle event a logging companion
+can render without ever writing a body byte.
+
+- Version: `1.0.0`
+- Category: `platform`
+- Capabilities: `["keyValueStore"]`
+- Suggested companions: `logging`, `errorHandling`
+
+## What it gives you
+
+- One place that reads `env.<binding>` (the KV binding) and exports
+  typed verbs (`get`, `getWithMetadata`, `put`, `delete`, `list`).
+- A cache-aside helper (`getOr(key, originFn, {ttl?})`) that reads
+  local first, invokes origin on miss, writes back with the elicited
+  TTL, and returns the fresh value.
+- Four metadata-only lifecycle events (`facadeReady`, `kvHit`,
+  `kvMiss`, `kvWrite`) with payload `{event, key, size, ttl,
+  timestamp}` and nothing else. Two-layer secrecy assertion in the
+  event-secrecy probe.
+- A decision-tree cross-reference in the guide to
+  `platform-cloudflare-durable-objects` (round-6 T-3) for cases that
+  need strong-consistency semantics.
+
+## The five REQs
+
+| REQ | What |
+| --- | --- |
+| `platform-cloudflare-kv-REQ-001` | The facade module is the sole reader of the KV binding and opens on boot with `facadeReady`. |
+| `platform-cloudflare-kv-REQ-002` | Typed `put get delete list` verbs with the metadata field pattern realise the Workers KV binding shape behind the facade. |
+| `platform-cloudflare-kv-REQ-003` | The cache-aside helper reads local first, falls back to origin, writes back with elicited TTL (floor 1 second). |
+| `platform-cloudflare-kv-REQ-004` | Lifecycle events carry only `{event, key, size, ttl, timestamp}`; the event-secrecy probe drives this at mechanism reach. |
+| `platform-cloudflare-kv-REQ-005` | Eventual-consistency note in the guide: a write may not appear on a global read within the same request; the elicited TTL sets the staleness ceiling. |
+
+## The two-path facade shape
+
+The facade is the ONE place the KV binding lives. Every other module
+imports the facade and calls its typed verbs. The public surface is:
+
+```
+createKvFacade({ binding, eventSink, keyPrefix?, defaultCacheTtl? })
+  -> { ready, get, getWithMetadata, put, delete, list }
+```
+
+The cache-aside helper wraps the facade:
+
+```
+createCacheAside({ facade, defaultTtl })
+  -> { getOr(key, originFn, {ttl?}) }
+```
+
+## Elicited parameters
+
+- `kv-binding-name` (default `CACHE`): the KV namespace binding name
+  written into `wrangler.toml` under `[[kv_namespaces]]`.
+- `kv-default-cache-ttl-seconds` (default `60`, floor `1`): the
+  cache-aside default TTL. The cache-aside helper enforces the floor
+  at its own seam per `ADR-3202`.
+- `kv-metadata-field-pattern` (default `{"v":1}`): the recommended
+  per-key metadata shape for a schema version marker.
+- `kv-key-naming-convention` (default `prefixed`): whether the applied
+  project uses a domain prefix on keys (`users/`, `flags/`) or a flat
+  keyspace. See `ADR-3203`.
+
+## The five probes
+
+The five probes live under `contributions/probes/`. Each has a
+matching `run-<probe-name>.mjs` shim that writes a per-blueprint
+report to
+`.rcf/reports/blueprints/platform-cloudflare-kv/<probe-name>.json`
+under the fixture root.
+
+| Probe | Anchor AC | Account-bound | What it drives |
+| --- | --- | --- | --- |
+| `facade-round-trip.mjs` | `AC-31103-1` | no | Opens the facade against the in-memory KV driver, puts a fixture key, reads it back, deletes it, asserts the paired lifecycle events. Also covers `AC-31103-2` and `AC-31104-1`. |
+| `cache-aside-hit-then-miss.mjs` | `AC-31105-1` | no | Wraps a spy origin function with the cache-aside helper, drives one call within TTL (hit, no origin call), advances the fake clock past TTL, drives another call (miss, second origin call). |
+| `event-secrecy.mjs` | `AC-31108-1` | no | Two-layer assertion: whitelist check on every event record and PII-substring scan on the JSON serialisation. A mutation-run under `SIMULATE_PII_LEAK` flips the probe to fail. |
+| `list-with-prefix.mjs` | `AC-31104-1` | no | Puts 10 keys under `flags/` plus one decoy outside the prefix, calls `list({prefix: flags/})`, asserts all 10 return with correct metadata shape and the decoy is absent. |
+| `real-account-eventual-consistency-smoke.mjs` | `AC-31108-1` | yes | Opens the facade against a real Cloudflare KV namespace via the Workers KV REST API, writes a fixture key, polls up to 60 seconds bounded, asserts the write eventually appears; without `CI_HAS_CLOUDFLARE_ACCOUNT` records `accountBoundSkipped: true` and aggregates `pass` per spec section 3.5. |
+
+## How to run the probes
+
+Two-line boot from the `cf-platform` sample-app fixture:
+
+```
+cd packages/rcf-lite/test/fixtures/cf-platform
+node ../../../../../blueprints/platform-cloudflare-kv/contributions/probes/run-facade-round-trip.mjs
+```
+
+The other three local probes follow the same pattern. Reports land
+in `.rcf/reports/blueprints/platform-cloudflare-kv/`.
+
+Induced-failure switches:
+
+- `SIMULATE_PII_LEAK=true` on the `event-secrecy` shim: forwards a
+  body-bearing event record; the probe surfaces `forbiddenKeys` and
+  `piiHits` and returns `aggregateVerdict: fail`.
+- `SIMULATE_CACHE_MISS=true` on the `cache-aside-hit-then-miss`
+  shim: disables the writeback path; the probe surfaces two origin
+  calls where one was expected and returns `aggregateVerdict: fail`.
+
+The real-account smoke needs `CI_HAS_CLOUDFLARE_ACCOUNT=true` plus
+the paired `CF_ACCOUNT_ID`, `CF_KV_NAMESPACE_ID`, `CF_API_TOKEN`
+env vars.
+
+## Known mechanism-reach gaps
+
+- The four local probes drive an in-memory KV driver whose binding
+  shape matches Workers KV at the facade boundary. Vendor surface
+  changes beyond that boundary (a new list cursor format, a
+  header-only per-request limit) are not caught by the local probes.
+  The `real-account-eventual-consistency-smoke` probe is the
+  mechanism-reach closure for that gap; in CI without the account,
+  the aggregate flips to `pass` with `accountBoundSkipped: true` per
+  spec section 3.5. Full mechanism reach requires a CI environment
+  with the paired env vars set.
+- The elicited `kv-metadata-field-pattern` cannot yet gate on an
+  `elicitedNonEmpty` predicate for `kv-binding-name`; the loader's
+  `validateElicits` accepts only `requiresCapability` on the `when`
+  block. The elicit fires unconditionally and the guide teaches the
+  pattern.
+
+## Companion suggestions
+
+- `logging` supplies the event-sink factory the facade uses to emit
+  `facadeReady`, `kvHit`, `kvMiss`, `kvWrite`. Without a logging
+  companion, the sink is a no-op and the lifecycle events do not
+  render anywhere.
+- `errorHandling` supplies the internal error record factory for a
+  KV read or write failure boundary; a project without an
+  error-handling companion sees a raw `Error` propagate to the
+  Worker fetch handler.
+
+## Standards trace
+
+- ADR-3201 (scope-global on `keyValueStoreContract`) carries
+  `standardsTraceClause: Cloudflare Workers KV documented
+  consistency model` and cites
+  <https://developers.cloudflare.com/kv/concepts/how-kv-works/>.
+- ADR-3202 (default cache-aside TTL) carries
+  `standardsTraceClause: generic enterprise practice` and cites the
+  Cloudflare-documented 60-second cache TTL at
+  <https://developers.cloudflare.com/kv/concepts/how-kv-works/>.
+- ADR-3203 (key naming convention) carries
+  `standardsTraceClause: generic enterprise practice`.
+
+## Chain-slice pointers
+
+The anatomy test at
+`packages/rcf-lite/test/blueprint/platform-cloudflare-kv-anatomy.test.js`
+binds every AC on `US-5001..5401` (`AC-5001-1..AC-5401-1`) to a test
+case in that file with a resolvable `testPointer`. Repo-chain slice
+under `packages/rcf-lite/rcf/`: `REQ-050..054` (5), `US-5001..5401`
+(8), `TS-080..087` (8), `FBS-070` (1), `CN-230..234` (5) per the
+HQ round-6 T-1 reserved-block ruling 2026-09-07T10:12Z.

package/blueprints/platform-cloudflare-kv/blueprint.json

@@ -0,0 +1,87 @@
+{
+  "slug": "platform-cloudflare-kv",
+  "version": "1.0.0",
+  "category": "platform",
+  "capabilities": ["keyValueStore"],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every KV facade operation emits a metadata-only lifecycle event through the applied logger; a logging companion supplies the sink factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A KV read or write failure constructs an internal error record; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "elicits": [
+    {
+      "id": "kv-binding-name",
+      "prompt": "What is the KV namespace binding name to use in wrangler.toml? (default: CACHE)",
+      "kind": "string",
+      "default": "CACHE"
+    },
+    {
+      "id": "kv-default-cache-ttl-seconds",
+      "prompt": "Default cache-aside TTL in seconds (floor 1, per ADR-3202; the shipped default aligns with the Cloudflare KV documented 60-second cache TTL)",
+      "kind": "string",
+      "default": "60"
+    },
+    {
+      "id": "kv-metadata-field-pattern",
+      "prompt": "Default metadata field pattern on put and getWithMetadata (JSON serialisable object; recommended default {v: number} for a per-key schema version)",
+      "kind": "string",
+      "default": "{\"v\":1}"
+    },
+    {
+      "id": "kv-key-naming-convention",
+      "prompt": "Key naming convention: prefixed (domain prefix like users/, flags/) or flat (per ADR-3203; recommended default prefixed)",
+      "kind": "enum",
+      "options": ["prefixed", "flat"],
+      "default": "prefixed"
+    }
+  ],
+  "contributions": [
+    { "id": "platform-cloudflare-kv-REQ-001", "kind": "req", "path": "requirements/platform-cloudflare-kv-req-001.json" },
+    { "id": "platform-cloudflare-kv-REQ-002", "kind": "req", "path": "requirements/platform-cloudflare-kv-req-002.json" },
+    { "id": "platform-cloudflare-kv-REQ-003", "kind": "req", "path": "requirements/platform-cloudflare-kv-req-003.json" },
+    { "id": "platform-cloudflare-kv-REQ-004", "kind": "req", "path": "requirements/platform-cloudflare-kv-req-004.json" },
+    { "id": "platform-cloudflare-kv-REQ-005", "kind": "req", "path": "requirements/platform-cloudflare-kv-req-005.json" },
+    { "id": "platform-cloudflare-kv-US-31101", "kind": "us", "path": "user-stories/platform-cloudflare-kv-us-31101.json" },
+    { "id": "platform-cloudflare-kv-US-31102", "kind": "us", "path": "user-stories/platform-cloudflare-kv-us-31102.json" },
+    { "id": "platform-cloudflare-kv-US-31103", "kind": "us", "path": "user-stories/platform-cloudflare-kv-us-31103.json" },
+    { "id": "platform-cloudflare-kv-US-31104", "kind": "us", "path": "user-stories/platform-cloudflare-kv-us-31104.json" },
+    { "id": "platform-cloudflare-kv-US-31105", "kind": "us", "path": "user-stories/platform-cloudflare-kv-us-31105.json" },
+    { "id": "platform-cloudflare-kv-US-31106", "kind": "us", "path": "user-stories/platform-cloudflare-kv-us-31106.json" },
+    { "id": "platform-cloudflare-kv-US-31107", "kind": "us", "path": "user-stories/platform-cloudflare-kv-us-31107.json" },
+    { "id": "platform-cloudflare-kv-US-31108", "kind": "us", "path": "user-stories/platform-cloudflare-kv-us-31108.json" },
+    { "id": "TAC-3201-platform-cloudflare-kv-facade", "kind": "tac", "path": "tacs/tac-3201-platform-cloudflare-kv-facade.json" },
+    { "id": "TAC-3202-platform-cloudflare-kv-cache-aside", "kind": "tac", "path": "tacs/tac-3202-platform-cloudflare-kv-cache-aside.json" },
+    { "id": "TAC-3203-platform-cloudflare-kv-event-sink", "kind": "tac", "path": "tacs/tac-3203-platform-cloudflare-kv-event-sink.json" },
+    {
+      "id": "ADR-3201-platform-cloudflare-kv-key-value-store-contract",
+      "kind": "adr",
+      "path": "adrs/adr-3201-platform-cloudflare-kv-key-value-store-contract.json",
+      "scope": "global",
+      "topic": "keyValueStoreContract",
+      "recommendedDefault": true,
+      "elicited": false,
+      "standardsTraceClause": "Cloudflare Workers KV documented consistency model"
+    },
+    {
+      "id": "ADR-3202-platform-cloudflare-kv-default-cache-ttl",
+      "kind": "adr",
+      "path": "adrs/adr-3202-platform-cloudflare-kv-default-cache-ttl.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-3203-platform-cloudflare-kv-key-naming-convention",
+      "kind": "adr",
+      "path": "adrs/adr-3203-platform-cloudflare-kv-key-naming-convention.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    }
+  ]
+}

package/blueprints/platform-cloudflare-kv/contributions/adrs/adr-3201-platform-cloudflare-kv-key-value-store-contract.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3201-platform-cloudflare-kv-key-value-store-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Key-value store contract: Cloudflare Workers KV as the shipped shape (scope global, new topic keyValueStoreContract)",
+  "context": "An applying Workers project has one native key-value store answer today: Cloudflare Workers KV. The binding is declared through wrangler configuration ([[kv_namespaces]] with binding, id and preview_id) and the shipped runtime binds env.<binding> to an object with get, getWithMetadata, put, delete and list per https://developers.cloudflare.com/kv/api/. KV is eventually consistent: a write may not appear on a global read within the same request, and changes may take up to 60 seconds or more to be visible in other network locations as their cached versions time out (https://developers.cloudflare.com/kv/concepts/how-kv-works/). The v1.0.0 facade must hold the adapter reference opaque at the facade boundary so a future non-Cloudflare adapter or an in-memory adapter for tests slots in without a facade re-shape, and so the round-6 Durable Objects sibling (T-3) is the shipped answer for strong-consistency needs.",
+  "decision": "The shipped v1.0.0 default is Cloudflare Workers KV, wired through wrangler config ([[kv_namespaces]] with binding, id and preview_id) per https://developers.cloudflare.com/kv/. The facade module (TAC-3201) is the sole holder of the KV binding reference per REQ-001. The keyValueStoreContract topic scope is global on this blueprint; the topic string is keyValueStoreContract (lower camelCase, one concept per topic, no version suffix, per the round-2 rules-for-new-topics clause on the shelf registry). A future non-KV adapter (a Redis-shape store, a strong-consistency DO cell for a single-owner use case) would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR per the round-2 conflict pattern.",
+  "consequences": "The applying project inherits Workers KV wire-format, the platform-assigned per-namespace limits (https://developers.cloudflare.com/kv/platform/limits/) and the documented eventual-consistency semantics. Standards trace clause: Cloudflare Workers KV documented consistency model (per https://developers.cloudflare.com/kv/concepts/how-kv-works/). Consumer code needing strong-consistency semantics reaches for the round-6 T-3 platform-cloudflare-durable-objects sibling instead; the guide carries the decision-tree cross-reference.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-07T10:28:32.000Z",
+  "updatedAt": "2026-09-07T10:28:32.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/adrs/adr-3202-platform-cloudflare-kv-default-cache-ttl.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3202-platform-cloudflare-kv-default-cache-ttl",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Default cache-aside TTL: 60 seconds shipped, floor 1 second, no ceiling",
+  "context": "The cache-aside helper writes back to KV with an expirationTtl on every miss; the applied project elicits the default TTL. Cloudflare documents a default cache TTL of 60 seconds on the read path (https://developers.cloudflare.com/kv/concepts/how-kv-works/); aligning the cache-aside default with the vendor default keeps two staleness ceilings synchronised.",
+  "decision": "Ship 60 seconds as the elicited default TTL for cache-aside. The helper enforces a 1-second floor on every per-call TTL (a misconfigured project cannot ship a sub-second TTL through the cache-aside seam). No upper ceiling is imposed by the helper; the Cloudflare KV documented per-namespace limits at https://developers.cloudflare.com/kv/platform/limits/ are the vendor ceiling. The elicited answer is written into the applied project as the defaultCacheTtl argument on the facade factory; per-call overrides use cache.getOr(key, originFn, {ttl}).",
+  "consequences": "The applied project observes a bounded staleness ceiling that matches the elicited TTL. A project needing shorter staleness re-elicits with a smaller value at apply time; a project needing longer staleness re-elicits with a larger value. The 1-second floor prevents an accidental cache-thrash pattern where the writeback expires before the next read arrives.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-07T10:28:32.000Z",
+  "updatedAt": "2026-09-07T10:28:32.000Z"
+}

package/blueprints/platform-cloudflare-kv/contributions/adrs/adr-3203-platform-cloudflare-kv-key-naming-convention.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3203-platform-cloudflare-kv-key-naming-convention",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Key naming convention: prefix-per-domain shipped, flat allowed",
+  "context": "KV keys are string-typed and globally addressed within a namespace. Two shipped shapes exist for a small-to-medium application: flat (keys are their own domain identifier, no prefix) and prefixed (keys carry a domain prefix such as users/, flags/, sessions/). The shipped shape must be one; the elicited answer supports the other for projects that already carry a naming discipline.",
+  "decision": "Ship prefixed as the default (recommendedDefault: prefixed). The facade accepts an elicited keyPrefix; when set, every operation transparently rewrites the key with the prefix on the storage boundary and the domain code sees prefix-free keys. When the elicited answer is flat, the facade passes the key through verbatim. The prefix disambiguation is what makes list({prefix}) predictable across multiple domain concepts sharing one namespace.",
+  "consequences": "The applying project chooses the shape at apply time. The default prefixed shape is the shape the round-6 spec section 5.1 example ACs assume (users/1234/profile, flags/feature-0). A project already keyed flat re-elicits and the facade passes keys through.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-07T10:28:32.000Z",
+  "updatedAt": "2026-09-07T10:28:32.000Z"
+}

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

@@ -0,0 +1,82 @@
+// 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:
+//
+//   1) First getOr(key, origin): miss, origin invoked, writeback,
+//      counter=1.
+//   2) Second getOr within TTL: hit, origin NOT invoked, counter
+//      still 1.
+//   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.
+//
+// anchorAcId: AC-5201-1 (AC-5201-2 covered as an additional result).
+// accountBound: false.
+
+export const anchorAcId = 'AC-5201-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');
+
+  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 cache = createCacheAside({ facade, defaultTtl: 5 });
+
+  let originCalls = 0;
+  const origin = async () => {
+    originCalls += 1;
+    return `origin-value-${originCalls}`;
+  };
+
+  const key = 'cache-aside/hit-then-miss';
+
+  const first = await cache.getOr(key, origin);
+  const second = await cache.getOr(key, origin);
+  now += 6 * 1000; // advance past 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')
+      : (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)`
+      : (withinTtlPass
+        ? `first miss then cached: originCalls=${originCalls} secondSource=${second.source}`
+        : `within-TTL branch fault: originCalls=${originCalls} secondSource=${second.source}`),
+  });
+
+  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}`
+      : (pastTtlPass
+        ? `past-TTL read triggered origin: originCalls=${originCalls} thirdSource=${third.source}`
+        : `past-TTL branch fault: originCalls=${originCalls} thirdSource=${third.source}`),
+  });
+
+  return { results };
+}