rcf-lite 0.22.0 → 0.24.0

package/blueprints/platform-cloudflare-durable-objects/contributions/tacs/tac-3405-platform-cloudflare-durable-objects-event-sink.json

@@ -0,0 +1,24 @@
+{
+  "tacId": "TAC-3405-platform-cloudflare-durable-objects-event-sink",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Platform-cloudflare-durable-objects lifecycle event sink",
+  "purpose": "The one boundary for lifecycle event records across the facade and both DO classes. The sink is a plain function callback with a metadata-only record contract: {event, key, size, ttl, timestamp, ?objectName, ?scheduledTime}. Message bodies, request headers, cookies and PII never cross the sink; the event-secrecy probe asserts the record shape on every emitted event.",
+  "responsibilities": [
+    "Constrain every emitted record to the allowed key set (AC-33106-1).",
+    "Route through the applied logging companion without a per-blueprint scrub pass."
+  ],
+  "internalStructure": "A one-arg callback contract enforced by every emitter (facade, single-cell, hub). The record is a plain object built inline at every emit site; no derivation, no framework object graph.",
+  "interfaces": [
+    {
+      "name": "eventSink",
+      "kind": "contract",
+      "summary": "One-arg record-write callback shared by facade and DO classes."
+    }
+  ],
+  "dependencies": [],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33101.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33101",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "DO facade opens on boot against env.CELL and env.HUB and emits namespaceReady",
+  "asA": "shelf consumer applying the platform-cloudflare-durable-objects v1.0.0 blueprint on a Workers project using the cf-platform fixture",
+  "iWant": "one DO facade module (src/do-facade.mjs) that opens against env.CELL and env.HUB on boot, wires the injected event sink and emits a namespaceReady lifecycle event with a metadata-only payload",
+  "soThat": "boot ordering is observable, the DO namespace seam is a single call site, and the applied project can compose its own bootstrapping around one predictable event",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33101-1",
+      "description": "On process boot, the DO facade opens against the elicited DO namespace bindings (env.CELL and env.HUB on the cf-platform fixture), wires the injected event sink and emits a namespaceReady event with a payload of exactly {event, key, size, ttl, timestamp} where key is null, size is 0 and ttl is null. The facade module is the ONLY module in the fixture source tree that dereferences env.CELL or env.HUB.",
+      "given": "a Node or Worker process with the do-facade module imported and its factory invoked with the elicited configuration",
+      "when": "the process boots and the facade ready() call resolves",
+      "then": "a namespaceReady event fires on the injected event sink with the metadata-only payload; no other module dereferences env.CELL or env.HUB",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3401-platform-cloudflare-durable-objects-namespace-facade"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33102.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33102",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Single-cell concurrent increments serialise per instance and return witness of prior write",
+  "asA": "developer whose Worker needs an authoritative counter, session store or lock behind a swappable boundary",
+  "iWant": "one SingleCellObject class instance to observe concurrent increments in per-instance FIFO order and return the sum plus a written witness",
+  "soThat": "two concurrent callers cannot silently overwrite each other and a domain assertion can prove the write happened before the read",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33102-1",
+      "description": "Two concurrent increment(delta=1) invocations against a named SingleCellObject with an initial counter of 0 resolve to {counter, witness} pairs whose counter values are 1 and 2 (in some order) and whose witness values are 0 and 1. The final read() returns counter 2. No non-serialised interleaving is possible: the counter is always equal to the sum of the deltas at read-time.",
+      "given": "a SingleCellObject wired with an in-memory DO storage driver at counter 0",
+      "when": "two increment(1) invocations fire concurrently and a read follows",
+      "then": "the two increments resolve with counters {1, 2} in FIFO order, witnesses {0, 1}, and the final read returns 2",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3402-platform-cloudflare-durable-objects-single-cell-shape"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33103.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33103",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Storage round-trip covers put/get/delete/list on both SQL and KV backends",
+  "asA": "developer configuring the storage backend on a new SingleCellObject",
+  "iWant": "the shipped storage driver to round-trip put, get, delete and list on both the SQL and KV backends via a fixture switch",
+  "soThat": "the applied project can elicit the backend at apply time (ADR-3403) and the shipped code path exercises both branches without code changes",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33103-1",
+      "description": "A storage driver factory created with {backend: \"sql\"} and a storage driver factory created with {backend: \"kv\"} both round-trip put(\"k\",\"v\")->get(\"k\")===\"v\", delete(\"k\") followed by get(\"k\")===undefined, and list({prefix:\"p/\"}) returns a Map keyed by the prefix. The driver.backend property reports the chosen backend on each factory.",
+      "given": "two storage drivers, one on each backend",
+      "when": "put/get/delete/list operations are driven on each driver in turn",
+      "then": "both round-trip identically and driver.backend reports \"sql\" and \"kv\" respectively",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3402-platform-cloudflare-durable-objects-single-cell-shape"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33104.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33104",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Alarm fires exactly once and doAlarmFired records objectName and scheduledTime",
+  "asA": "developer whose SingleCellObject schedules future work via storage.setAlarm",
+  "iWant": "the alarm() handler to fire exactly once per scheduled time and doAlarmFired to carry object name and scheduled time",
+  "soThat": "the applied project can observe alarm delivery through the metadata-only sink and trust the once-per-schedule contract",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33104-1",
+      "description": "A SingleCellObject with setAlarm(offsetMs=100) fires alarm() when driven at the scheduled time. The alarm() handler runs exactly once, deletes the persisted alarm from storage (getAlarm() returns null after the fire) and emits a doAlarmFired event on the injected sink with {event, key, size, ttl, timestamp, objectName, scheduledTime} where objectName is the object's name and scheduledTime matches the setAlarm scheduled millis. A second call to alarm() on the drained storage does NOT emit a second doAlarmFired for the same schedule (the storage.getAlarm() returns null so the second fire records scheduledTime null).",
+      "given": "a SingleCellObject with setAlarm(100)",
+      "when": "alarm() is driven once and then again after the fire",
+      "then": "the first fire emits doAlarmFired with the scheduledTime; the second fire records scheduledTime null; storage.getAlarm() returns null after the first fire",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3403-platform-cloudflare-durable-objects-alarm-handler"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33105.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33105",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Hub broadcast fans out a payload from client A to all connected clients within the elicited window",
+  "asA": "developer coordinating multiplayer websocket clients through one authoritative hub",
+  "iWant": "the HubObject to fan out a broadcast payload from one connected client to all connected clients within the elicited window",
+  "soThat": "the shipped hub shape delivers the coordinated-multiplayer contract without a hand-rolled broadcast layer",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33105-1",
+      "description": "A HubObject with two accepted fake websockets A and B, when driven with webSocketMessage(A, JSON.stringify({type:\"broadcast\", payload:\"ping\"})), delivers a JSON message to both A and B whose type is \"broadcast\" and payload is \"ping\" within 500ms elapsed on the fixture clock. The persisted lastBroadcast key in storage carries the serialised outbound payload.",
+      "given": "a HubObject with two accepted fake websocket sockets",
+      "when": "a broadcast message is sent from A",
+      "then": "both A and B receive the same broadcast within 500ms and storage.get(\"lastBroadcast\") returns the serialised payload",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3404-platform-cloudflare-durable-objects-websocket-hub"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33106.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33106",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Lifecycle events carry only allowed metadata fields and drop forbidden keys",
+  "asA": "reviewer verifying the platform-cloudflare-durable-objects v1.0.0 blueprint at mechanism reach",
+  "iWant": "the event-secrecy probe to drive namespaceReady, doAccept, doAlarmFired, doWakeUp and doHibernate through the shipped code path and assert no record carries any forbidden key (body, ssn, userId, headers, cookies)",
+  "soThat": "a logging companion can render the sink directly without a per-blueprint scrub pass",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33106-1",
+      "description": "Every record emitted on the sink by createDoFacade, SingleCellObject.alarm() and HubObject.accept/hibernate/wake is a plain object whose top-level keys are drawn from the allowed set {event, key, size, ttl, timestamp, objectName, scheduledTime}. No record carries body, ssn, userId, headers, cookies, request or payload; the probe returns aggregateVerdict: pass with a zero-hit count on the forbidden-key scan. Under SIMULATE_PII_LEAK=true a wrapped sink forwards a synthetic body-bearing record and the probe surfaces the forbidden keys, returning aggregateVerdict: fail.",
+      "given": "a driven facade + single-cell + hub with an accumulating spy sink",
+      "when": "the event-secrecy probe runs on the shipped code path",
+      "then": "every record contains only allowed keys; the forbidden-key scan finds zero hits; SIMULATE_PII_LEAK=true surfaces the injected fields",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3405-platform-cloudflare-durable-objects-event-sink"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33107.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33107",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sole-reader-scan probe surfaces every non-facade module that dereferences env.CELL or env.HUB",
+  "asA": "reviewer enforcing the sole-reader guarantee on env.CELL and env.HUB",
+  "iWant": "the sole-reader-scan probe to walk every .mjs/.js/.ts file under the fixture's applied source root and assert only src/do-facade.mjs dereferences env.CELL or env.HUB",
+  "soThat": "a legacy call site or an accidental new one surfaces at self-review, not at runtime",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33107-1",
+      "description": "The sole-reader-scan probe reads every regular file under packages/rcf-lite/test/fixtures/cf-platform/src ending in .mjs, .js or .ts, matches literal occurrences of \"env.CELL\" and \"env.HUB\" against the file path, and reports every non-facade file that contains a match as a \"leak\". A clean fixture has exactly one leak-free file (do-facade.mjs) that contains the matches; every other file records zero matches. Under SIMULATE_NON_FACADE_IMPORT=true the probe additionally scans a synthetic scratch file whose body dereferences env.CELL outside the facade and surfaces the leak, returning aggregateVerdict: fail.",
+      "given": "the cf-platform fixture applied source root and, optionally, the SIMULATE_NON_FACADE_IMPORT scratch scenario",
+      "when": "the sole-reader-scan probe runs",
+      "then": "the clean-fixture pass reports zero non-facade leaks; the simulate pass surfaces the injected leak and returns fail",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3401-platform-cloudflare-durable-objects-namespace-facade"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33108.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33108",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Wrangler.toml commits stable DO class names on both binding blocks and a migrations tag records the mint classes",
+  "asA": "operator applying platform-cloudflare-durable-objects on a fresh Workers project",
+  "iWant": "the generated wrangler.toml to carry [[durable_objects.bindings]] blocks and a paired [[migrations]] block committing the class names under a stable tag",
+  "soThat": "a future rename lands as a wrangler migration rather than a silent rewire and the DO class identity survives the mint",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33108-1",
+      "description": "The fixture wrangler.toml carries at least two [[durable_objects.bindings]] blocks (one binding named CELL with class_name SingleCellObject; one binding named HUB with class_name HubObject) and at least one [[migrations]] block with tag \"v1\" and new_classes = [\"SingleCellObject\", \"HubObject\"]. An anatomy assertion greps the toml for each of the four literal strings (name = \"CELL\", class_name = \"SingleCellObject\", name = \"HUB\", class_name = \"HubObject\") and the tag/new_classes pair. A rename in a real project ships as a new migrations tag entry, never a silent edit of the class name.",
+      "given": "the cf-platform fixture wrangler.toml",
+      "when": "the anatomy assertion greps for the four literal strings and the migrations pair",
+      "then": "every string is present and the migrations tag \"v1\" carries the two class names",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3401-platform-cloudflare-durable-objects-namespace-facade"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33109.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33109",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Single-cell increment returns the observed prior counter as a witness field",
+  "asA": "developer relying on per-instance FIFO serialisation for a mint or lock-shape operation",
+  "iWant": "each concurrent increment to return the observed prior-counter as a witness field",
+  "soThat": "a downstream assertion can prove the second write observed the first without racing against clock",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33109-1",
+      "description": "increment() resolves with a {counter, witness} pair where witness equals the counter value at the start of that call's serialised turn. Two concurrent increments starting from 0 report witnesses 0 and 1 (in FIFO order); a subsequent read reports counter 2. The witness field is present on every resolved increment, never on read or reset.",
+      "given": "a SingleCellObject at counter 0",
+      "when": "two concurrent increments fire",
+      "then": "the FIFO-first increment returns witness 0, the second returns witness 1, and read returns 2",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3402-platform-cloudflare-durable-objects-single-cell-shape"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33110.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33110",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Hibernate-and-wake round-trip preserves storage and re-emits doWakeUp exactly once",
+  "asA": "developer whose HubObject hibernates when idle and wakes on the next message",
+  "iWant": "the wake handler to run from cold and read the same lastBroadcast key from storage the pre-hibernate state persisted",
+  "soThat": "a re-emerging client can catch up on the missed broadcast without a full re-sync",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33110-1",
+      "description": "A HubObject that has processed a broadcast, hibernated (doHibernate emitted), and then woken (doWakeUp emitted once) resolves wake() with {lastBroadcast} equal to the serialised outbound payload the pre-hibernate broadcast persisted. A second wake() call resolves with {alreadyAwake: true, lastBroadcast: <same>} and does NOT emit a second doWakeUp. The wake handler is idempotent-by-contract per ADR-3405.",
+      "given": "a HubObject with one persisted lastBroadcast that has hibernated",
+      "when": "wake() is called once, then again",
+      "then": "the first wake emits doWakeUp once and returns lastBroadcast; the second wake reports alreadyAwake without a second event",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3404-platform-cloudflare-durable-objects-websocket-hub"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33111.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33111",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Storage driver factory threads the elicited backend answer through as driver.backend",
+  "asA": "operator eliciting the storage backend at apply time",
+  "iWant": "the shipped storage driver factory to accept the elicited answer and report it as driver.backend",
+  "soThat": "a downstream operations panel and a review probe can read the shipped-backend value from the driver instance and cross-check against the elicited answer",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33111-1",
+      "description": "createInMemoryDoStorage({backend: \"sql\"}) returns a driver whose .backend property equals \"sql\"; createInMemoryDoStorage({backend: \"kv\"}) returns a driver whose .backend property equals \"kv\"; createInMemoryDoStorage({}) defaults to \"sql\" per ADR-3403 recommendedDefault. The driver.backend field is present on every returned driver.",
+      "given": "three factory calls with backend=\"sql\", backend=\"kv\" and no backend arg",
+      "when": "the returned drivers are inspected",
+      "then": "each driver.backend reports the elicited answer or the default \"sql\"",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3402-platform-cloudflare-durable-objects-single-cell-shape"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33112.json

@@ -0,0 +1,27 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33112",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Real-account storage smoke drives a facade round-trip against a real DO namespace",
+  "asA": "operator validating platform-cloudflare-durable-objects v1.0.0 against a real Cloudflare account",
+  "iWant": "the real-account-storage-smoke probe to open the facade against a real DO namespace, drive a storage round-trip with the elicited backend and assert the round-trip returns",
+  "soThat": "the shipped DO facade surface is proven against the vendor's runtime, not only against the in-process driver",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33112-1",
+      "description": "The real-account-storage-smoke probe, when CI_HAS_CLOUDFLARE_ACCOUNT=true and the paired CF_ACCOUNT_ID / CF_DO_NAMESPACE_ID / CF_API_TOKEN env vars are set, opens the facade against the real Cloudflare account with a real DO namespace, drives a storage.put(\"k\",\"v\")->get(\"k\")===\"v\" round-trip and returns aggregateVerdict: pass. Without CI_HAS_CLOUDFLARE_ACCOUNT the probe records accountBoundSkipped: true and aggregates to pass per spec section 3.5.",
+      "given": "a real Cloudflare account with the paired env vars, or no such account and CI_HAS_CLOUDFLARE_ACCOUNT unset",
+      "when": "the probe runs",
+      "then": "with the account: the round-trip returns and the probe passes. Without the account: accountBoundSkipped:true and exit 0.",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-3401-platform-cloudflare-durable-objects-namespace-facade"
+  ],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/user-stories/platform-cloudflare-durable-objects-us-33113.json

@@ -0,0 +1,25 @@
+{
+  "usId": "platform-cloudflare-durable-objects-US-33113",
+  "prdId": "PRD-001",
+  "reqId": "platform-cloudflare-durable-objects-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Wrangler-seam probe drives two concurrent increments against the DO through env.CELL and one WebSocket upgrade through env.HUB, both routed via the DO facade so the sole-reader guarantee holds",
+  "asA": "reviewer verifying the platform-cloudflare-durable-objects v1.0.0 blueprint under a real workerd runtime",
+  "iWant": "the wrangler-seam probe to spawn wrangler dev on the cf-platform fixture, issue two concurrent POST /cell/<id>/increment requests against a route in src/index.mjs that reaches env.CELL through the DO facade (createDoFacade({env}).cellFetch), and open one WebSocket upgrade against /hub/<id>/connect that reaches env.HUB through the facade (createDoFacade({env}).hubFetch), asserting per-instance serialisation on the increments and one broadcast frame on the WebSocket",
+  "soThat": "the shipped DO facade + SingleCellObject + HubObject code path is proven against workerd, not only against the in-memory storage driver and the fake websocket state that the six in-process probes drive",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-33113-1",
+      "description": "The wrangler-seam probe, when the fixture has been prepared with `pnpm install --ignore-workspace` so the wrangler devDependency is on the tree, spawns `wrangler dev --local --port 0` from the cf-platform fixture, waits bounded 45 seconds for the CLI to bind, then (a) issues two concurrent POST /cell/<id>/increment requests against a fetch route in src/index.mjs that calls createDoFacade({env, eventSink}).cellFetch(<id>, request), asserting the two responses observe per-instance serialisation (sorted counters == [1, 2], sorted witnesses == [0, 1], each request read the other's write) and (b) opens one WebSocket upgrade against /hub/<id>/connect via createDoFacade({env, eventSink}).hubFetch(<id>, request), asserting one broadcast frame arrives on connect with payload 'hello-from-hub'. The probe kills wrangler cleanly on exit. Warn semantics per section 3.1 pass-with-skip: if wrangler is not installed or fails to bind within the cap, the probe returns aggregateVerdict warn (never fail); a handler thrown at the workerd boundary is a genuine fail. The additional result on the same probe run covers AC-33108-1 by grepping the fixture wrangler.toml for the two [[durable_objects.bindings]] pairs and the [[migrations]] tag/new_classes pair; the grep result is deterministic and does not require wrangler.",
+      "given": "the cf-platform fixture with the wrangler devDependency installed and the shipped DO classes exported from src/index.mjs",
+      "when": "the wrangler-seam probe runs",
+      "then": "wrangler dev binds; two concurrent increments through env.CELL observe per-instance serialisation; one WebSocket upgrade through env.HUB receives a broadcast frame; the wrangler.toml grep confirms both binding pairs and the migrations tag/new_classes; wrangler exits cleanly",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-3401-platform-cloudflare-durable-objects-namespace-facade"],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T16:10:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/docs/topics.md

@@ -0,0 +1,73 @@
+# platform-cloudflare-durable-objects blueprint coordination vocabulary
+
+This file is the platform-cloudflare-durable-objects half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | platform-cloudflare-durable-objects contribution | Origin | Composition note |
+|---|---|---|---|
+| `strongConsistencyCellContract` | ADR-3401-platform-cloudflare-durable-objects-single-cell-contract | Minted by this blueprint. Names the wire-shape contract for a strongly consistent single-instance authoritative cell (counter, session store, lock); the shipped answer is a Cloudflare Durable Object named instance per https://developers.cloudflare.com/durable-objects/. | The one project-wide decision on the strong-consistency cell contract at the shipped-shape boundary. A future non-Cloudflare sibling (a Postgres advisory-lock singleton, a Redis single-master pattern) would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR. |
+| `websocketHubContract` | ADR-3402-platform-cloudflare-durable-objects-websocket-hub-contract | Minted by this blueprint. Names the wire-shape contract for a coordinated-multiplayer websocket hub; the shipped answer is a Cloudflare Durable Object hub instance with hibernatable WebSockets per https://developers.cloudflare.com/durable-objects/. | The one project-wide decision on the hub contract. A future non-Cloudflare hub sibling (Redis pub-sub broker, a bespoke websocket server) would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR. |
+
+The platform-cloudflare-durable-objects blueprint claims two global topics (both minted here, both under Cloudflare Durable Objects on the shipped path). Every other contribution is scope-local (ADR-3403 storage backend, ADR-3404 migrations shape, ADR-3405 hibernation posture do not contribute global topics; a composing blueprint that holds an opinion on any of them authors its own project-level ADR).
+
+Rules for new topics: lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer.
+
+## Id number bands (registry bootstrap)
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.2.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
+| application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.1.0 | `adminConsoleSignInSurface` |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+| messaging-queue-cloudflare | 29101-29899 | 30xx | shipped v1.0.0 | `deliverySemantics` |
+| jobs-background | 30101-30899 | 31xx | shipped v1.0.0 | `backgroundJobModel` |
+| platform-cloudflare-kv | 31101-31899 | 32xx | shipped v1.0.0 | `keyValueStoreContract` |
+| platform-cloudflare-cron-triggers | 32101-32899 | 33xx | shipped v1.0.0 | `scheduledTriggerContract` |
+| platform-cloudflare-durable-objects | 33101-33899 | 34xx | shipped v1.0.0 | `strongConsistencyCellContract`, `websocketHubContract` |
+| edge-cloudflare-access | 34101-34899 | 35xx | shipped v1.0.0 | `edgeAuthenticationGate` |
+| edge-cloudflare-turnstile | 35101-35899 | 36xx | shipped v1.0.0 | `humanVerificationGate` |
+| edge-cloudflare-rate-limiting | 36101-36899 | 37xx | shipped v1.0.0 | `edgeThrottleContract` |
+
+US 33101-33112 sit at the LOW end of the 33101-33899 band on purpose (watchpost run-4 lesson). A project-side story mechanically derived from a platform-cloudflare-durable-objects REQ id into the number 33113 would collide against a shipped US-33113; band headroom (33113-33899) leaves that space.
+
+ADR/TAC suffixes for this blueprint use the 3401-3499 block, continuing the shelf pattern.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `strongConsistencyCellContract` exactly as spelled here when your blueprint holds an opinion on the strong-consistency cell contract; contribute your own scope:global ADR on that string and let composition surface the pairing.
+- Reuse `websocketHubContract` exactly as spelled here when your blueprint holds an opinion on the websocket-hub contract; the same pattern applies.
+- A future non-Cloudflare adapter on either contract mints on demand; each claims the same topic string and conflicts by design.
+- Consumer blueprints reading the `strongConsistencyCell` or `hibernatableWebSocket` capability declared on `blueprint.json` per section 6a of `blueprint-authoring.md` obtain the DO facade wiring at apply time via the T-5 visual-round capability-declaration mechanism.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-3401 on `strongConsistencyCellContract` and ADR-3402 on `websocketHubContract` are the first shipped answers to two topics that will conflict, by design, with future non-Cloudflare siblings. Applying `platform-cloudflare-durable-objects` alongside such a sibling would raise `globalAdrTopic` conflicts the operator resolves via one of the four documented resolutions per topic (adopt one, keep the existing one, author a project-level supersede ADR, or `--resolve <topic>=project:<ADR-id>` on the add).