rcf-lite 0.22.0 → 0.24.0

package/blueprints/platform-cloudflare-cron-triggers/guide/platform-cloudflare-cron-triggers.md

@@ -0,0 +1,119 @@
+# platform-cloudflare-cron-triggers guide
+
+## When to reach for this blueprint
+
+You reach for `platform-cloudflare-cron-triggers` when your Worker
+needs to run scheduled work on a recurring cadence, the workload
+is stateless per fire, and you are already on Cloudflare Workers.
+The blueprint ships the scheduled() handler wiring, an
+expression-routed dispatcher, a skew-tolerance classifier and a
+soft-budget observer. Every fire emits a metadata-only lifecycle
+event a logging companion renders directly.
+
+If your scheduled work is stateful across fires (a workflow that
+retries partial progress, a long-running fan-out with state per
+step), reach for the follow-up Workflows adapter on
+`jobs-background` v1.1.0 instead (round-6 minor bump, per spec
+section 5.7). If your scheduled work is a background job produced
+by a request handler (a queue push that runs later, not on a fixed
+cadence), reach for `jobs-background` v1.0.0 directly.
+
+## Decision tree
+
+- Recurring cadence, stateless per fire, Cloudflare Workers ->
+  this blueprint (Cron Triggers).
+- Background job produced by a request, retried and observed ->
+  `jobs-background` v1.0.0 over `messaging-queue-cloudflare`.
+- Durable workflow with state across steps, retried per step ->
+  follow-up Workflows adapter on `jobs-background` v1.1.0 (round-6
+  minor bump).
+- Not on Cloudflare Workers -> reach for a platform-native
+  cron adapter when one ships; the shelf has no non-Cloudflare
+  cron blueprint today.
+
+## The apply-time answers
+
+Answer four elicits at `rcf define blueprint add` time:
+
+- `cron-expressions`: your cron cadences as a comma-separated
+  list. Standard POSIX cron strings. Example: `* * * * *,*/5 * * * *`
+  runs one handler every minute and a second handler every five
+  minutes.
+- `cron-dispatcher-mode`: `single-handler` when you elicited one
+  expression and want every fire to run one handler;
+  `expression-routed` when you elicited more than one expression
+  and want the dispatcher to route by exact expression match. The
+  recommended default follows your `cron-expressions` list: one
+  entry -> `single-handler`; more than one -> `expression-routed`.
+- `cron-skew-tolerance-seconds`: the drift window inside which a
+  fire is `onTime` and outside which the dispatcher records
+  `cronSkewed`. Default `30`, floor `5`, ceiling `300`.
+- `cron-soft-budget-seconds`: the per-handler duration past which
+  the dispatcher records `cronStalled`. Default `30`. The
+  dispatcher never terminates the handler; termination is
+  Cloudflare's platform-level concern per
+  https://developers.cloudflare.com/workers/platform/limits/.
+
+## The event shape
+
+Every scheduled-side event on the sink carries only:
+
+```
+{ event, expression, scheduledTime, outcome, duration }
+```
+
+Plus optional numeric fields:
+
+- `softBudgetMs` on `cronStalled` records
+- `deltaMs` on `cronSkewed` records
+
+The event-secrecy probe drives a spy handler that closes over a
+PII fixture (`{userId, ssn}`) and asserts neither the closure nor
+any PII substring survives the sink boundary. See
+`contributions/probes/event-secrecy.mjs` for the two-layer assertion.
+
+## Verifying at mechanism reach
+
+The blueprint ships five Node-only probes under
+`contributions/probes/`. Run them from the cf-platform fixture:
+
+```
+cd packages/rcf-lite/test/fixtures/cf-platform
+pnpm install --ignore-workspace
+node ../../../../../blueprints/platform-cloudflare-cron-triggers/contributions/probes/run-wrangler-test-scheduled.mjs
+node ../../../../../blueprints/platform-cloudflare-cron-triggers/contributions/probes/run-dispatcher-routing.mjs
+node ../../../../../blueprints/platform-cloudflare-cron-triggers/contributions/probes/run-skew-tolerance.mjs
+node ../../../../../blueprints/platform-cloudflare-cron-triggers/contributions/probes/run-event-secrecy.mjs
+```
+
+Each writes a report under
+`.rcf/reports/blueprints/platform-cloudflare-cron-triggers/<probe-name>.json`.
+The real-account smoke:
+
+```
+node ../../../../../blueprints/platform-cloudflare-cron-triggers/contributions/probes/run-real-account-scheduled-smoke.mjs
+```
+
+Without `CI_HAS_CLOUDFLARE_ACCOUNT=true` and the paired env vars,
+the probe records `accountBoundSkipped: true` and exits 0 per spec
+section 3.5.
+
+## Induced-failure switches
+
+- `SIMULATE_PII_LEAK=true`: wraps the sink on the event-secrecy
+  probe so it forwards the closure onto every record. The probe
+  surfaces the forbidden keys and the PII substrings and returns
+  `aggregateVerdict: fail`. Use this before shipping to confirm
+  the whitelist assertion is teeth-bearing.
+- `SIMULATE_SLOW_HANDLER=true`: extends the spy handler on the
+  skew-tolerance probe past `softBudgetMs` on every dispatch so
+  a reviewer can see `cronStalled` fires without editing the
+  probe. The shipped path already exercises the soft-budget
+  branch; the switch is a reviewer aid.
+
+## References
+
+- Cloudflare Cron Triggers documentation: https://developers.cloudflare.com/workers/configuration/cron-triggers/
+- Cloudflare Workers scheduled handler contract: https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/
+- Cloudflare Workers platform limits: https://developers.cloudflare.com/workers/platform/limits/
+- Wrangler `wrangler dev` documentation (carries the `--test-scheduled` flag under the `dev` command): https://developers.cloudflare.com/workers/wrangler/commands/

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

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `platform-cloudflare-durable-objects` 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-durable-objects` blueprint, category `platform`, capabilities `["strongConsistencyCell", "hibernatableWebSocket"]`. Ships two composable shapes: the SINGLE-CELL shape (a named object as an authoritative counter, session store or lock) and the WEBSOCKET-HUB shape (a named object hosting many websocket clients with per-message routing and hibernate-and-wake support). One DO facade module owns the DO namespace bindings; typed storage API wraps both SQL and KV backends; alarm surface fires exactly once per scheduled time; hibernatable-WebSocket shape realises Cloudflare's documented hibernate-and-wake contract.
+- 8 REQs (`platform-cloudflare-durable-objects-REQ-001..008`), 13 USs (`platform-cloudflare-durable-objects-US-33101..33113`; US-33113 covers the wrangler-seam runtime coverage), 5 TACs (`TAC-3401` namespace facade, `TAC-3402` single-cell shape, `TAC-3403` alarm handler, `TAC-3404` websocket hub, `TAC-3405` lifecycle event sink), 5 ADRs (`ADR-3401` scope-global on new topic `strongConsistencyCellContract` with `standardsTraceClause: Cloudflare Durable Objects documented consistency model`; `ADR-3402` scope-global on new topic `websocketHubContract` with `standardsTraceClause: Cloudflare Durable Objects hibernatable WebSockets shape`; `ADR-3403` storage backend `elicited: true` `recommendedDefault: sql`; `ADR-3404` migrations-shape with `standardsTraceClause: Cloudflare Durable Objects migration documentation`; `ADR-3405` hibernation posture `elicited: true` with idempotent-by-contract wake handler).
+- 8 Node-only probes under `contributions/probes/`: `namespace-facade-ready` (facade opens and emits namespaceReady with metadata-only payload), `single-cell-concurrent-increment` (two concurrent increments serialise FIFO; also folds AC-33109-1 witness field), `storage-round-trip` (both sql and kv backends; also folds AC-33111-1 default backend), `alarm-fires-once` (once-per-schedule contract with drained storage), `websocket-hub-broadcast` (fan-out within window; folds AC-33110-1 hibernate-and-wake and AC-33106-1 event-secrecy on the shipped path with SIMULATE_PII_LEAK=true mutation), `sole-reader-scan` (source-tree scan of the applied source root with comment-stripping; folds SIMULATE_NON_FACADE_IMPORT=true mutation), `real-account-storage-smoke` (`accountBound: true`; records `accountBoundSkipped` in CI without `CI_HAS_CLOUDFLARE_ACCOUNT` per spec section 3.5), and `wrangler-seam` (drives `wrangler dev --local` on the fixture; two concurrent POST /cell/<id>/increment requests through the DO facade reaching env.CELL observe per-instance serialisation; one WebSocket upgrade against /hub/<id>/connect through the facade reaching env.HUB receives one broadcast frame; additional AC-33108-1 result on the same run greps wrangler.toml for both binding pairs and the migrations tag/new_classes; warn semantics per section 3.1 pass-with-skip if wrangler is missing or fails to bind).
+- 7 elicited parameters on `blueprint.json`: `do-cell-binding` (default `CELL`), `do-hub-binding` (default `HUB`), `do-cell-class-name` (default `SingleCellObject`), `do-hub-class-name` (default `HubObject`), `do-storage-backend` (default `sql` per ADR-3403), `do-hub-broadcast-window-ms` (default `500`), `do-hub-hibernate-after-idle-ms` (default `30000` per ADR-3405).
+- `suggestedCompanions`: `logging` (for the lifecycle-event sink) and `errorHandling` (for the handler-failure boundary).
+- Extends the shared `cf-platform` sample-app fixture with the `[[durable_objects.bindings]]` blocks (one binding named `CELL` with `class_name` `SingleCellObject`, one binding named `HUB` with `class_name` `HubObject`), the paired `[[migrations]]` block with `tag = "v1"` and `new_classes = ["SingleCellObject", "HubObject"]`, the sole-reader DO facade (`src/do-facade.mjs`), the single-cell class (`src/do-single-cell.mjs`), the hub class (`src/do-hub.mjs`), and the in-memory DO storage driver (`src/do-storage.mjs`) realising both sql and kv backends. The T-0 `[assets]`, T-1 `[[kv_namespaces]]` and T-2 `[triggers]` crons blocks are preserved verbatim; the facade does NOT dereference `env.CACHE` (KV binding stays owned by the T-1 KV facade).
+- Anatomy test at `packages/rcf-lite/test/blueprint/platform-cloudflare-durable-objects-anatomy.test.js` covers `TS-100..109` on the T-3 chain slice plus the wrangler-seam probe module shape (TC-wrangler-seam-shape) that binds AC-33113-1 to the shipped probe file (blueprint shape, contributions cross-check, probe module contracts, fixture files, ADR bodies and clauses, guide sections and URLs, two-mint-topic scope entries).
+
+### Known limitations
+
+- The `real-account-storage-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 `CI_HAS_CLOUDFLARE_ACCOUNT=true` plus paired `CF_ACCOUNT_ID`, `CF_DO_NAMESPACE_ID` and `CF_API_TOKEN` env vars, and a deployed Worker exposing the DO facade round-trip.
+- The v1.0.0 boundary defers RPC-style class methods, storage backups and multi-object transactions across namespaces to v1.1.0 per spec section 5.3. The shipped code path does not open any of these seams; the v1.1.0 minor lands them as an additive minor.
+- The in-memory DO storage driver realises both `sql` and `kv` backends deterministically for the shipped probes; a real Cloudflare DO backend (SQL storage vs KV storage) may exhibit different edge-case semantics on the wrangler dev boot path. The real-account smoke covers the real-backend edge; the local probes cover the shipped code path.
+- The hub-shape hibernate-and-wake round-trip in the shipped in-process probe uses a fake state object with `acceptWebSocket`, `getWebSockets` and a fake websocket pair. A real `wrangler dev` process hosting DO bindings would exhibit different hibernation timing behaviour; the guide notes the trade at self-review.
+- The `_serialise` promise queue on the shipped SingleCellObject class is defence-in-depth against non-workerd runtimes. Under workerd's fetch path, per-instance input gates plus storage output gates serialise concurrent invocations against the same object, so removing the `_serialise` guard is not observable through the wrangler-seam probe unless an additional race window (for example an artificial delay between the storage read and write) is also introduced. The in-process `single-cell-concurrent-increment` probe DOES observe the `_serialise` removal on its own (Node without workerd's storage gate); mutation-check tails on both probes ride the PR body.

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

@@ -0,0 +1,200 @@
+# platform-cloudflare-durable-objects
+
+A rcf-lite blueprint that ships a small, opinionated wiring over
+Cloudflare Durable Objects. Two shapes ride in one blueprint: the
+SINGLE-CELL shape (a named object as an authoritative counter,
+session store or lock) and the WEBSOCKET-HUB shape (a named object
+hosting many websocket clients with per-message routing and
+hibernate-and-wake support). A facade module owns the DO namespace
+bindings; typed domain verbs wrap the storage API; the alarm
+surface and the hibernatable-WebSocket contract land under two
+scope-global ADRs on new topics.
+
+- Version: `1.0.0`
+- Category: `platform`
+- Capabilities: `["strongConsistencyCell", "hibernatableWebSocket"]`
+- Suggested companions: `logging`, `errorHandling`
+
+## When to reach for it
+
+- Authoritative state on Cloudflare Workers (counter, session
+  store, lock, coordinator) that needs strong-consistency writes:
+  the single-cell shape.
+- Coordinated multiplayer websocket connections in one authoritative
+  hub (rooms, live cursors, presence): the hub shape.
+
+The sibling `platform-cloudflare-kv` (round 6 T-1) is the shipped
+answer for eventually-consistent low-latency reads. The guide's
+decision tree pairs them.
+
+## The two shapes: decision tree at the top
+
+- Do you need a strongly consistent authoritative cell? Reach for
+  the SINGLE-CELL shape.
+- Do you need coordinated multiplayer websocket connections?
+  Reach for the WEBSOCKET-HUB shape.
+- Do you need cache-shaped read-hot reads with no strong-consistency
+  contract? Reach for `platform-cloudflare-kv` instead.
+- Do you need durable multi-step workflows with retries and state
+  across steps? Reach for the round-6 Workflows adapter on
+  `jobs-background` v1.1.0 instead.
+
+## The eight REQs
+
+| REQ | What |
+| --- | --- |
+| `platform-cloudflare-durable-objects-REQ-001` | The DO facade is the sole reader of `env.CELL` and `env.HUB` and opens on boot with `namespaceReady`. |
+| `platform-cloudflare-durable-objects-REQ-002` | The single-cell shape exposes typed domain verbs (`increment`, `read`, `reset`) and serialises concurrent invocations per instance. |
+| `platform-cloudflare-durable-objects-REQ-003` | The storage API provides typed `put`, `get`, `delete` and `list` on the object with an elicited backend (SQL or KV). |
+| `platform-cloudflare-durable-objects-REQ-004` | The alarm surface fires `alarm()` exactly once per scheduled time and `doAlarmFired` carries `objectName` and `scheduledTime`. |
+| `platform-cloudflare-durable-objects-REQ-005` | The hibernatable WebSocket hub accepts clients via `state.acceptWebSocket` and the wake handler runs from cold reading the same storage. |
+| `platform-cloudflare-durable-objects-REQ-006` | Lifecycle events fire at namespace and object level with metadata-only payloads. |
+| `platform-cloudflare-durable-objects-REQ-007` | The sole-reader guarantee is enforced by an AST scan; no non-facade module dereferences `env.CELL` or `env.HUB`. |
+| `platform-cloudflare-durable-objects-REQ-008` | Migration-safe class exports: stable class names committed to wrangler config with a paired `[[migrations]]` block. |
+
+## The wired shape
+
+The DO facade is the ONE place `env.CELL` and `env.HUB` are read.
+Typed handles wrap named instances of the SingleCellObject and
+HubObject classes. The public surface is:
+
+```
+createDoFacade({ env, eventSink, clock? })
+  -> { ready, cellHandle(name), hubHandle(name) }
+```
+
+For in-process probing (no wrangler dev), the in-process variant:
+
+```
+createDoFacadeInProcess({ singleCell, hub, eventSink, clock? })
+  -> { ready, cell(name), hub(name), registerCell(i), registerHub(i) }
+```
+
+The two DO classes:
+
+```
+new SingleCellObject({ storage, eventSink, name, clock? })
+  -> instance.increment(delta?) / read() / reset() / setAlarm(offsetMs) / alarm()
+
+new HubObject({ state, storage, eventSink, name, hibernateAfterIdleMs?, clock? })
+  -> instance.accept(ws) / webSocketMessage(ws, msg) / webSocketClose(ws)
+     / hibernate() / wake()
+```
+
+## Elicited parameters
+
+- `do-cell-binding` (default `CELL`): the DO namespace binding name
+  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 for the single-cell class.
+- `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.
+- `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 eight probes
+
+The eight 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-durable-objects/<probe-name>.json`
+under the fixture root.
+
+| Probe | anchorAcId | accountBound | What it covers |
+| --- | --- | --- | --- |
+| `namespace-facade-ready.mjs` | `AC-33101-1` | false | Facade opens; `namespaceReady` fires with allowed keys; `cell(name)` and `hub(name)` return the registered instances. |
+| `single-cell-concurrent-increment.mjs` | `AC-33102-1` | false | Two concurrent increments serialise FIFO; counters `[1,2]`, witnesses `[0,1]`, final read `2`. Also covers `AC-33109-1` (witness field). |
+| `storage-round-trip.mjs` | `AC-33103-1` | false | `put`, `get`, `delete`, `list` on both `sql` and `kv` backends; `driver.backend` reports the elicited answer. Also covers `AC-33111-1`. |
+| `alarm-fires-once.mjs` | `AC-33104-1` | false | `alarm()` fires once; `doAlarmFired` carries `objectName` and `scheduledTime`; drained storage does not re-fire. |
+| `websocket-hub-broadcast.mjs` | `AC-33105-1` | false | Broadcast from A reaches A and B within 500 ms; storage persists `lastBroadcast`. Also covers `AC-33110-1` (hibernate-and-wake) and `AC-33106-1` (event-secrecy on the shipped path). |
+| `sole-reader-scan.mjs` | `AC-33107-1` | false | Every `.mjs`/`.js`/`.ts` file under the fixture applied source root is scanned; only `src/do-facade.mjs` may dereference `env.CELL` or `env.HUB` in live source. |
+| `real-account-storage-smoke.mjs` | `AC-33112-1` | true | Facade round-trip against a real Cloudflare DO namespace when `CI_HAS_CLOUDFLARE_ACCOUNT=true`; otherwise records `accountBoundSkipped` and passes per spec section 3.5. |
+| `wrangler-seam.mjs` | `AC-33113-1` | false | Spawns `wrangler dev --local` on the fixture and drives two concurrent `POST /cell/<id>/increment` requests through the DO facade against `env.CELL`, asserting per-instance serialisation (counters `[1, 2]`, witnesses `[0, 1]`); opens one WebSocket upgrade against `/hub/<id>/connect` through the facade against `env.HUB`, asserting one broadcast frame arrives on connect. Also carries an additional `AC-33108-1` result that greps `wrangler.toml` for both binding pairs and the migrations tag/new_classes. Warn semantics per section 3.1 pass-with-skip if wrangler is not installed or fails to bind. |
+
+## Two-line gate-reviewer boot
+
+```
+cd packages/rcf-lite/test/fixtures/cf-platform
+pnpm install --ignore-workspace
+node ../../../../../blueprints/platform-cloudflare-durable-objects/contributions/probes/run-namespace-facade-ready.mjs
+node ../../../../../blueprints/platform-cloudflare-durable-objects/contributions/probes/run-single-cell-concurrent-increment.mjs
+node ../../../../../blueprints/platform-cloudflare-durable-objects/contributions/probes/run-storage-round-trip.mjs
+node ../../../../../blueprints/platform-cloudflare-durable-objects/contributions/probes/run-alarm-fires-once.mjs
+node ../../../../../blueprints/platform-cloudflare-durable-objects/contributions/probes/run-websocket-hub-broadcast.mjs
+node ../../../../../blueprints/platform-cloudflare-durable-objects/contributions/probes/run-sole-reader-scan.mjs
+node ../../../../../blueprints/platform-cloudflare-durable-objects/contributions/probes/run-real-account-storage-smoke.mjs
+node ../../../../../blueprints/platform-cloudflare-durable-objects/contributions/probes/run-wrangler-seam.mjs
+```
+
+Each returns exit 0 with `aggregateVerdict: pass`. The seventh
+records `accountBoundSkipped: true` without the CI env var per
+spec section 3.5.
+
+The wrangler-dev boot (documented in the fixture README
+under the T-3 sections) is required for the eighth probe
+(`wrangler-seam.mjs`), which spawns `wrangler dev --local` on
+the fixture to drive the shipped DO facade + SingleCellObject +
+HubObject code path against a real workerd runtime. The six
+local probes drive the shipped code path in-process against the
+in-memory DO storage driver and a fake WebSocket state; a
+real-account round-trip lives on the `real-account-storage-smoke`
+probe and is skipped by default per the Clerk pattern. Prepare
+the fixture once with `pnpm install --ignore-workspace`; the
+wrangler-seam probe returns warn per spec section 3.1 pass-with-skip
+if the CLI is missing or fails to bind within the cap.
+
+## The v1.0.0 boundary
+
+The v1.0.0 mint keeps a single build worker inside its context
+budget for an L blueprint. The following items DEFER to the v1.1.0
+minor bump per spec section 5.3 and land as an additive minor once
+at least one project needs them:
+
+- RPC-style class methods (per the DO RPC surface).
+- Storage backups.
+- Multi-object transactions across namespaces.
+
+The v1.0.0 shipped code path does not open any of these seams; a
+future v1.1.0 grows the mechanism inside the same blueprint.
+
+## Companion pairing
+
+- `logging`: every lifecycle event on the sink writes through the
+  applied logger; a logging companion supplies the sink factory.
+- `errorHandling`: a namespace binding miss, an alarm handler
+  throwing, a hub broadcast failure constructs an internal error
+  record; an error-handling companion supplies the record factory
+  and the boundary.
+
+## Cross-reference to `platform-cloudflare-kv`
+
+If your project needs 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. Durable
+Objects owns the strong-consistency slot on the shelf; KV owns
+the cache-shaped eventually-consistent slot. Both compose on the
+same Worker.
+
+## The two mint topics
+
+- `strongConsistencyCellContract` (ADR-3401): the shipped shape is
+  a Cloudflare Durable Object named instance. A future non-Cloudflare
+  sibling (Postgres advisory-lock singleton, Redis single-master)
+  conflicts on this topic.
+- `websocketHubContract` (ADR-3402): the shipped shape is a
+  Cloudflare Durable Object hub instance with hibernatable
+  WebSockets. A future non-Cloudflare hub sibling conflicts on
+  this topic.
+
+Both topics are `scope: global` on the ADR contribution entries in
+`blueprint.json`; the round-2 conflict pattern applies.
+
+## References
+
+- Cloudflare Durable Objects overview: https://developers.cloudflare.com/durable-objects/

package/blueprints/platform-cloudflare-durable-objects/blueprint.json

@@ -0,0 +1,243 @@
+{
+  "slug": "platform-cloudflare-durable-objects",
+  "version": "1.0.0",
+  "category": "platform",
+  "capabilities": [
+    "strongConsistencyCell",
+    "hibernatableWebSocket"
+  ],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every namespaceReady, doAccept, doAlarmFired, doWakeUp and doHibernate event writes through the applied logger; a logging companion supplies the sink factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A namespace binding miss, an alarm handler throwing, a hub broadcast failure constructs an internal error record; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "elicits": [
+    {
+      "id": "do-cell-binding",
+      "prompt": "Durable Object namespace binding name for the single-cell shape (a stable identifier in wrangler.toml under [[durable_objects.bindings]]; recommended default CELL).",
+      "kind": "string",
+      "default": "CELL"
+    },
+    {
+      "id": "do-hub-binding",
+      "prompt": "Durable Object namespace binding name for the hibernatable-WebSocket hub shape (recommended default HUB).",
+      "kind": "string",
+      "default": "HUB"
+    },
+    {
+      "id": "do-cell-class-name",
+      "prompt": "Stable class name string for the single-cell class exported from src/do-single-cell.mjs; committed under [[migrations]] on the v1 mint tag (recommended default SingleCellObject).",
+      "kind": "string",
+      "default": "SingleCellObject"
+    },
+    {
+      "id": "do-hub-class-name",
+      "prompt": "Stable class name string for the hub class exported from src/do-hub.mjs; committed under [[migrations]] on the v1 mint tag (recommended default HubObject).",
+      "kind": "string",
+      "default": "HubObject"
+    },
+    {
+      "id": "do-storage-backend",
+      "prompt": "Storage backend for the single-cell class per ADR-3403: sql (typed columns, query) or kv (simple put/get/delete/list). Recommended default sql.",
+      "kind": "enum",
+      "options": [
+        "sql",
+        "kv"
+      ],
+      "default": "sql"
+    },
+    {
+      "id": "do-hub-broadcast-window-ms",
+      "prompt": "Broadcast delivery window per HubObject fan-out, in milliseconds (recommended default 500).",
+      "kind": "string",
+      "default": "500"
+    },
+    {
+      "id": "do-hub-hibernate-after-idle-ms",
+      "prompt": "Hibernate-after-idle window per ADR-3405, in milliseconds (recommended default 30000; a coordinated-multiplayer workload with tight latency budgets picks a longer window).",
+      "kind": "string",
+      "default": "30000"
+    }
+  ],
+  "contributions": [
+    {
+      "id": "platform-cloudflare-durable-objects-REQ-001",
+      "kind": "req",
+      "path": "requirements/platform-cloudflare-durable-objects-req-001.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-REQ-002",
+      "kind": "req",
+      "path": "requirements/platform-cloudflare-durable-objects-req-002.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-REQ-003",
+      "kind": "req",
+      "path": "requirements/platform-cloudflare-durable-objects-req-003.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-REQ-004",
+      "kind": "req",
+      "path": "requirements/platform-cloudflare-durable-objects-req-004.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-REQ-005",
+      "kind": "req",
+      "path": "requirements/platform-cloudflare-durable-objects-req-005.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-REQ-006",
+      "kind": "req",
+      "path": "requirements/platform-cloudflare-durable-objects-req-006.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-REQ-007",
+      "kind": "req",
+      "path": "requirements/platform-cloudflare-durable-objects-req-007.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-REQ-008",
+      "kind": "req",
+      "path": "requirements/platform-cloudflare-durable-objects-req-008.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33101",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33101.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33102",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33102.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33103",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33103.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33104",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33104.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33105",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33105.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33106",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33106.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33107",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33107.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33108",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33108.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33109",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33109.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33110",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33110.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33111",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33111.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33112",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33112.json"
+    },
+    {
+      "id": "platform-cloudflare-durable-objects-US-33113",
+      "kind": "us",
+      "path": "user-stories/platform-cloudflare-durable-objects-us-33113.json"
+    },
+    {
+      "id": "TAC-3401-platform-cloudflare-durable-objects-namespace-facade",
+      "kind": "tac",
+      "path": "tacs/tac-3401-platform-cloudflare-durable-objects-namespace-facade.json"
+    },
+    {
+      "id": "TAC-3402-platform-cloudflare-durable-objects-single-cell-shape",
+      "kind": "tac",
+      "path": "tacs/tac-3402-platform-cloudflare-durable-objects-single-cell-shape.json"
+    },
+    {
+      "id": "TAC-3403-platform-cloudflare-durable-objects-alarm-handler",
+      "kind": "tac",
+      "path": "tacs/tac-3403-platform-cloudflare-durable-objects-alarm-handler.json"
+    },
+    {
+      "id": "TAC-3404-platform-cloudflare-durable-objects-websocket-hub",
+      "kind": "tac",
+      "path": "tacs/tac-3404-platform-cloudflare-durable-objects-websocket-hub.json"
+    },
+    {
+      "id": "TAC-3405-platform-cloudflare-durable-objects-event-sink",
+      "kind": "tac",
+      "path": "tacs/tac-3405-platform-cloudflare-durable-objects-event-sink.json"
+    },
+    {
+      "id": "ADR-3401-platform-cloudflare-durable-objects-single-cell-contract",
+      "kind": "adr",
+      "path": "adrs/adr-3401-platform-cloudflare-durable-objects-single-cell-contract.json",
+      "scope": "global",
+      "topic": "strongConsistencyCellContract",
+      "recommendedDefault": true,
+      "elicited": false,
+      "standardsTraceClause": "Cloudflare Durable Objects documented consistency model"
+    },
+    {
+      "id": "ADR-3402-platform-cloudflare-durable-objects-websocket-hub-contract",
+      "kind": "adr",
+      "path": "adrs/adr-3402-platform-cloudflare-durable-objects-websocket-hub-contract.json",
+      "scope": "global",
+      "topic": "websocketHubContract",
+      "recommendedDefault": true,
+      "elicited": false,
+      "standardsTraceClause": "Cloudflare Durable Objects hibernatable WebSockets shape"
+    },
+    {
+      "id": "ADR-3403-platform-cloudflare-durable-objects-storage-backend",
+      "kind": "adr",
+      "path": "adrs/adr-3403-platform-cloudflare-durable-objects-storage-backend.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-3404-platform-cloudflare-durable-objects-migrations-shape",
+      "kind": "adr",
+      "path": "adrs/adr-3404-platform-cloudflare-durable-objects-migrations-shape.json",
+      "recommendedDefault": true,
+      "elicited": false,
+      "standardsTraceClause": "Cloudflare Durable Objects migration documentation"
+    },
+    {
+      "id": "ADR-3405-platform-cloudflare-durable-objects-hibernation-posture",
+      "kind": "adr",
+      "path": "adrs/adr-3405-platform-cloudflare-durable-objects-hibernation-posture.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    }
+  ]
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/adrs/adr-3401-platform-cloudflare-durable-objects-single-cell-contract.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3401-platform-cloudflare-durable-objects-single-cell-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Single-cell contract: Cloudflare Durable Objects authoritative-cell shape (scope global, new topic strongConsistencyCellContract)",
+  "context": "An applying Workers project has one native strong-consistency answer today: Cloudflare Durable Objects. The DO runtime serialises invocations against a named instance per https://developers.cloudflare.com/durable-objects/, providing the authoritative-cell shape a counter, session store or lock needs. Two shapes ship in this blueprint (single-cell and websocket-hub) per spec section 5.3; both share the DO namespace mechanic. The single-cell shape is the one project-wide answer to strongConsistencyCellContract; a future non-Cloudflare adapter (a Postgres advisory-lock singleton, a Redis single-master pattern) would conflict on the same topic.",
+  "decision": "The shipped v1.0.0 default is a Cloudflare Durable Object named instance behind the DO facade (env.CELL), realising the single-cell shape per REQ-002 and TAC-3402. The strongConsistencyCellContract topic scope is global on this blueprint; the topic string is strongConsistencyCellContract (lower camelCase, one concept per topic, no version suffix, per the round-2 rules-for-new-topics clause). A future non-Cloudflare adapter would contribute the same topic string with a different answer, forcing a DELIBERATE conflict the operator resolves with a project-level ADR.",
+  "consequences": "The applying project inherits Cloudflare's documented DO consistency model, the platform-assigned per-object limits (https://developers.cloudflare.com/durable-objects/), and the migration-safe class-export contract (REQ-008). Standards trace clause: Cloudflare Durable Objects documented consistency model (per https://developers.cloudflare.com/durable-objects/). Consumers needing weaker-consistency low-latency reads reach for the sibling platform-cloudflare-kv blueprint (round 6 T-1) instead; the guide names the decision.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/adrs/adr-3402-platform-cloudflare-durable-objects-websocket-hub-contract.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3402-platform-cloudflare-durable-objects-websocket-hub-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Websocket hub contract: Cloudflare Durable Objects hibernatable WebSockets shape (scope global, new topic websocketHubContract)",
+  "context": "A named DO instance can host many websocket clients via state.acceptWebSocket per the hibernatable WebSockets shape (https://developers.cloudflare.com/durable-objects/). The runtime hibernates the object when idle and wakes it on the next message; the wake handler runs from cold and reads the same storage. This is the shipped answer for the coordinated-multiplayer shape the WSD lane consumers reach for. A future non-Cloudflare hub adapter (a Redis pub-sub broker, a bespoke websocket server) would conflict on the same topic; the guide names the trade.",
+  "decision": "The shipped v1.0.0 default is a Cloudflare Durable Object hub instance behind the DO facade (env.HUB), realising the hibernatable-WebSocket hub shape per REQ-005 and TAC-3404. The websocketHubContract topic scope is global on this blueprint; the topic string is websocketHubContract. A future non-Cloudflare adapter would contribute the same topic string, forcing a DELIBERATE conflict the operator resolves with a project-level ADR.",
+  "consequences": "The applying project inherits Cloudflare's documented hibernatable-WebSockets contract, the hibernate-after-idle window (elicited per ADR-3405) and the idempotent wake-handler shape. Standards trace clause: Cloudflare Durable Objects hibernatable WebSockets shape (per https://developers.cloudflare.com/durable-objects/). The hub shape shares the DO namespace mechanic with the single-cell shape; a future non-Cloudflare websocket-hub sibling mints on demand and the two-blueprint split conversation resurfaces then.",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}

package/blueprints/platform-cloudflare-durable-objects/contributions/adrs/adr-3403-platform-cloudflare-durable-objects-storage-backend.json

@@ -0,0 +1,14 @@
+{
+  "adrId": "ADR-3403-platform-cloudflare-durable-objects-storage-backend",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Storage backend: SQL or KV on the object (elicited)",
+  "context": "A Cloudflare Durable Object exposes state.storage per https://developers.cloudflare.com/durable-objects/. Two backends are documented: SQL storage (state.storage.sql) supports typed columns and query; KV storage (state.storage.put/get/delete/list) is simpler and single-key. Both are useful; the choice depends on the shipped object's data shape. The elicit forces the operator to pick at apply time so the shipped code path can carry the trace record.",
+  "decision": "The applied blueprint elicits do-storage-backend at apply time with two options (sql, kv). The recommendedDefault is sql for new objects (SQL supports typed columns and future migrations without a driver rewrite). The chosen answer threads through the storage driver factory as driver.backend per AC-33111-1; the shipped SingleCellObject class code is backend-agnostic and does not care which backend is live.",
+  "consequences": "A project that picks sql inherits the DO SQL storage semantics and the shipped SQL migration path; a project that picks kv inherits the simpler put/get/delete/list surface and the KV eventual-consistency-on-the-object trade the guide documents. Standards trace clause: generic enterprise practice (the sql-vs-kv trade is a general enterprise-tier storage-shape choice, not a Cloudflare-specific claim).",
+  "alternativesConsidered": [],
+  "createdAt": "2026-09-07T14:00:00.000Z",
+  "updatedAt": "2026-09-07T14:00:00.000Z"
+}