rcf-lite 0.11.0 → 0.13.0

package/blueprints/persistence-data-d1/assets/migration-shape/migration-file-shape.md

@@ -0,0 +1,119 @@
+# Migration file shape
+
+Every migration in the wrangler-configured `migrations_dir` (default `migrations/`) is one `.sql` file (TAC-1402). The wrangler CLI is the applier and the D1 bookkeeping table (`migrations_table`, default `d1_migrations`) is the applied-state ledger. This asset shows the exact shape.
+
+## Filename shape
+
+The default wrangler pattern is `<zero-padded-integer>_<description>.sql`, generated by `wrangler d1 migrations create <database> <description>`:
+
+```
+migrations/
+  0001_initial_schema.sql
+  0002_soft_delete_column.sql
+  0003_boot_markers.sql
+  0004_notifier_schema.sql
+```
+
+The leading integer is monotonic across the directory; it anchors the applied-state ordering and the AC-13102-1 sequence check. The description is human-readable and appears in the file name and (by convention) the file header comment; it does not affect ordering.
+
+Projects that pin an ORM override `migrations_pattern` on the D1 binding to match the ORM's filename shape (Drizzle's `0000_name.sql`, Prisma's `<timestamp>_name/migration.sql`). The leading-integer monotonicity property still holds; the pattern controls what the CLI matches, not the ordering discipline.
+
+## File body shape
+
+Each file body is engine-native SQL: one or more statements separated by `;`, terminating in `;`. Comments (`--` line comments) are allowed. The wrangler CLI executes the statements against the D1 database and records the applied file in the bookkeeping table.
+
+Worked four-migration example (SQLite dialect, D1's native syntax):
+
+`migrations/0001_initial_schema.sql`:
+
+```sql
+-- Initial schema for the domain.
+-- Four tables: entityA, entityB, session, auditEntry.
+
+CREATE TABLE entityA (
+  id        TEXT PRIMARY KEY,
+  name      TEXT NOT NULL UNIQUE,
+  createdAt TEXT NOT NULL,
+  updatedAt TEXT NOT NULL
+);
+
+CREATE TABLE entityB (
+  id        TEXT PRIMARY KEY,
+  entityAId TEXT NOT NULL REFERENCES entityA(id),
+  payload   TEXT NOT NULL,
+  createdAt TEXT NOT NULL
+);
+
+CREATE TABLE session (
+  handle    TEXT PRIMARY KEY,
+  principal TEXT NOT NULL,
+  issuedAt  TEXT NOT NULL,
+  expiresAt TEXT NOT NULL
+);
+
+CREATE TABLE auditEntry (
+  id        TEXT PRIMARY KEY,
+  actor     TEXT NOT NULL,
+  action    TEXT NOT NULL,
+  targetId  TEXT NOT NULL,
+  at        TEXT NOT NULL
+);
+```
+
+`migrations/0002_soft_delete_column.sql`:
+
+```sql
+-- Soft-delete column on entityA for file-lane removal without eager history loss.
+ALTER TABLE entityA ADD COLUMN removedAt TEXT;
+```
+
+`migrations/0003_boot_markers.sql`:
+
+```sql
+-- Boot markers: audit trail of Worker isolate cold-starts.
+CREATE TABLE bootMarker (
+  bootAt TEXT PRIMARY KEY
+);
+```
+
+`migrations/0004_notifier_schema.sql`:
+
+```sql
+-- Notifier: per-entity channel routes and pending-delivery queue.
+CREATE TABLE entityChannelRoute (
+  entityId  TEXT NOT NULL,
+  channelId TEXT NOT NULL,
+  PRIMARY KEY (entityId, channelId)
+);
+
+CREATE TABLE channel (
+  id        TEXT PRIMARY KEY,
+  isDefault INTEGER NOT NULL DEFAULT 0
+);
+```
+
+## Applying migrations
+
+The wrangler CLI applies files in ascending leading-integer order:
+
+```
+# Local dev
+wrangler d1 migrations list  <database> --local
+wrangler d1 migrations apply <database> --local
+
+# Preview environment
+wrangler d1 migrations apply <database> --env preview
+
+# Live environment (typically run by the CI job before the Worker deploy)
+wrangler d1 migrations apply <database> --env live
+```
+
+The applied files land in the bookkeeping table (`d1_migrations` by default). A subsequent `list` reports zero unapplied migrations; a `SELECT * FROM d1_migrations` returns one row per applied file.
+
+## Rules a project must not break
+
+- **Leading integers are monotonic and unique across the directory.** A missing integer between shipped files, or a duplicate, breaks the ordering guarantee the wrangler CLI relies on. Two contributors landing overlapping integers is a merge conflict, not a runtime bug.
+- **A shipped migration is never edited.** Adding a statement to an already-applied file is a silent schema divergence between deployed databases at different apply cycles. Fixes ship as new numbered files, appended.
+- **The bookkeeping table is not the migration's concern.** A migration whose statements include an `INSERT INTO d1_migrations` corrupts the wrangler CLI's ordering; the CLI already handles that insert inside the same transaction as the migration's statements.
+- **Statements are D1-flavoured SQLite dialect.** D1 shares SQLite's SQL semantics; statements that assume Postgres-specific features (SERIAL, native JSONB, LATERAL) fail at apply. When switching engines under a superseding ADR-1401, plan for a dialect translation pass.
+- **Import from an existing SQLite dump requires stripping `BEGIN TRANSACTION` and `COMMIT`.** The vendor's guidance is explicit: D1's `wrangler d1 execute --file` refuses these statements. A migration file authored from a sqlite3 dump has them removed at authoring time.

package/blueprints/persistence-data-d1/assets/wrangler-config/d1-binding-shape.md

@@ -0,0 +1,93 @@
+# D1 binding shape in the wrangler config
+
+The Worker reads the D1 database through a binding declared on `d1_databases[]` in the project's wrangler config file (`wrangler.jsonc` or `wrangler.toml`). This asset shows the exact shape with placeholders only; substitute the project's actual identifiers at the time of writing.
+
+## Minimal shape (wrangler.jsonc)
+
+```jsonc
+{
+  "name": "<worker-name>",
+  "main": "src/worker.js",
+  "compatibility_date": "<yyyy-mm-dd>",
+  "d1_databases": [
+    {
+      "binding": "<BINDING_NAME>",
+      "database_name": "<database-name>",
+      "database_id": "<database-uuid>"
+    }
+  ]
+}
+```
+
+Field notes:
+
+- `binding` is the property name the Worker reads off `env`. Convention: uppercase snake or Pascal, one binding per named database per environment. The store facade module (TAC-1401) is the only place this name is read; every other module imports the facade.
+- `database_name` is the human-readable name from `wrangler d1 create` or `wrangler d1 list`. Used by wrangler CLI arguments (`wrangler d1 execute <database_name> ...`); not read by the Worker.
+- `database_id` is the vendor-assigned UUID from `wrangler d1 create` or `wrangler d1 info`. This is the durable identifier the vendor uses; substitute the value the project owns.
+
+## Full shape with migration overrides (wrangler.jsonc)
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "<BINDING_NAME>",
+      "database_name": "<database-name>",
+      "database_id": "<database-uuid>",
+      "migrations_dir": "migrations",
+      "migrations_table": "d1_migrations",
+      "migrations_pattern": "*.sql"
+    }
+  ]
+}
+```
+
+Field notes:
+
+- `migrations_dir` names the directory the migration files live in. Default: `migrations/` at the wrangler config's parent directory. TAC-1402 anchors the migration catalog to this value.
+- `migrations_table` names the D1-side bookkeeping table. Default: `d1_migrations`. TAC-1402 anchors the applied-state ledger to this value; AC-13102-3 reads this table for verification.
+- `migrations_pattern` is a glob selecting migration files under `migrations_dir`. Default: the wrangler-generated numbered form. Override for ORM compatibility (Drizzle's `0000_name.sql`, Prisma's `<timestamp>_name/migration.sql`).
+
+## Per-environment shape
+
+Environments (dev, preview, live) each get their own D1 database. The `env` block on the wrangler config binds them per environment:
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "<BINDING_NAME>",
+      "database_name": "<database-name>-dev",
+      "database_id": "<dev-database-uuid>"
+    }
+  ],
+  "env": {
+    "preview": {
+      "d1_databases": [
+        {
+          "binding": "<BINDING_NAME>",
+          "database_name": "<database-name>-preview",
+          "database_id": "<preview-database-uuid>"
+        }
+      ]
+    },
+    "live": {
+      "d1_databases": [
+        {
+          "binding": "<BINDING_NAME>",
+          "database_name": "<database-name>-live",
+          "database_id": "<live-database-uuid>"
+        }
+      ]
+    }
+  }
+}
+```
+
+TAC-1403's deploy-gate orders `wrangler d1 migrations apply <database-name> --env <target>` strictly before `wrangler deploy --env <target>` for each named environment. The binding name stays constant across environments so the facade module reads the same `env[BINDING_NAME]` regardless of target.
+
+## What this asset is not
+
+Not a wrangler config template the project copies verbatim. The shape above is the SHAPE of the binding block; the project fills in its own identifiers, compatibility date, and any other fields (routes, custom domains, Static Assets) its Worker needs. A future `deploy-cloudflare-workers` blueprint (round-2 sibling) is the natural owner of the wider wrangler config surface; this blueprint owns the D1 binding shape only.
+
+Not a credentials-storage guide. `CLOUDFLARE_API_TOKEN` and any deploy-specific secret the CI job uses are the concern of the `security-secrets-management` blueprint; store them there, not in this file.

package/blueprints/persistence-data-d1/blueprint.json

@@ -0,0 +1,42 @@
+{
+  "slug": "persistence-data-d1",
+  "version": "1.0.0",
+  "category": "persistence",
+  "contributions": [
+    { "id": "persistence-data-d1-REQ-001", "kind": "req", "path": "requirements/persistence-data-d1-req-001.json" },
+    { "id": "persistence-data-d1-REQ-002", "kind": "req", "path": "requirements/persistence-data-d1-req-002.json" },
+    { "id": "persistence-data-d1-REQ-003", "kind": "req", "path": "requirements/persistence-data-d1-req-003.json" },
+    { "id": "persistence-data-d1-REQ-004", "kind": "req", "path": "requirements/persistence-data-d1-req-004.json" },
+    { "id": "persistence-data-d1-REQ-005", "kind": "req", "path": "requirements/persistence-data-d1-req-005.json" },
+    { "id": "persistence-data-d1-REQ-006", "kind": "req", "path": "requirements/persistence-data-d1-req-006.json" },
+    { "id": "persistence-data-d1-REQ-007", "kind": "req", "path": "requirements/persistence-data-d1-req-007.json" },
+    { "id": "persistence-data-d1-US-13101", "kind": "us", "path": "user-stories/persistence-data-d1-us-13101.json" },
+    { "id": "persistence-data-d1-US-13102", "kind": "us", "path": "user-stories/persistence-data-d1-us-13102.json" },
+    { "id": "persistence-data-d1-US-13103", "kind": "us", "path": "user-stories/persistence-data-d1-us-13103.json" },
+    { "id": "persistence-data-d1-US-13104", "kind": "us", "path": "user-stories/persistence-data-d1-us-13104.json" },
+    { "id": "persistence-data-d1-US-13105", "kind": "us", "path": "user-stories/persistence-data-d1-us-13105.json" },
+    { "id": "persistence-data-d1-US-13106", "kind": "us", "path": "user-stories/persistence-data-d1-us-13106.json" },
+    { "id": "persistence-data-d1-US-13107", "kind": "us", "path": "user-stories/persistence-data-d1-us-13107.json" },
+    { "id": "TAC-1401-persistence-data-d1-facade", "kind": "tac", "path": "tacs/tac-1401-persistence-data-d1-facade.json" },
+    { "id": "TAC-1402-persistence-data-d1-migration-catalog", "kind": "tac", "path": "tacs/tac-1402-persistence-data-d1-migration-catalog.json" },
+    { "id": "TAC-1403-persistence-data-d1-deploy-gate", "kind": "tac", "path": "tacs/tac-1403-persistence-data-d1-deploy-gate.json" },
+    { "id": "TAC-1404-persistence-data-d1-recovery-runner", "kind": "tac", "path": "tacs/tac-1404-persistence-data-d1-recovery-runner.json" },
+    {
+      "id": "ADR-1401-persistence-data-d1-store-model",
+      "kind": "adr",
+      "path": "adrs/adr-1401-persistence-data-d1-store-model.json",
+      "scope": "global",
+      "topic": "persistenceStore"
+    },
+    {
+      "id": "ADR-1402-persistence-data-d1-migration-discipline",
+      "kind": "adr",
+      "path": "adrs/adr-1402-persistence-data-d1-migration-discipline.json",
+      "scope": "global",
+      "topic": "migrationDiscipline"
+    },
+    { "id": "ADR-1403-persistence-data-d1-event-secrecy", "kind": "adr", "path": "adrs/adr-1403-persistence-data-d1-event-secrecy.json" },
+    { "id": "ADR-1404-persistence-data-d1-store-boundary", "kind": "adr", "path": "adrs/adr-1404-persistence-data-d1-store-boundary.json" },
+    { "id": "ADR-1405-persistence-data-d1-recovery-model", "kind": "adr", "path": "adrs/adr-1405-persistence-data-d1-recovery-model.json" }
+  ]
+}

package/blueprints/persistence-data-d1/contributions/adrs/adr-1401-persistence-data-d1-store-model.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1401-persistence-data-d1-store-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Cloudflare D1 as the project's primary durable store, read through a Worker-side facade; other engines behind the same facade contract on supersede",
+  "context": "A project deployed on Cloudflare Workers has a natural persistence choice: D1, the vendor's managed serverless SQLite-semantics database, bound directly into the Worker's `env` and accessed request-scoped through a vendor-owned prepared-statement surface. The alternatives (a self-managed store fronted by a Worker adapter, an external Postgres reached from the Worker over HTTPS, an in-memory Workers KV substrate) each cost the project either an operator surface the Workers tier is supposed to eliminate or the relational semantics the domain expects. The rcf-lite Workers-tier target for this blueprint has one obvious answer.",
+  "decision": "The default primary durable store is one Cloudflare D1 database bound into the Worker under a named binding declared in `d1_databases[]`, accessed through the D1 store facade (TAC-1401) which is the only module that reads the binding. One binding per environment; the binding name and database identifier are project-configured; migrations are numbered forward-only `.sql` files under the wrangler-managed directory and applied by the vendor's own tooling (TAC-1402); the deploy pipeline is the gate that binds the applied set to the deployed Worker (TAC-1403); recovery is Time Travel plus a scheduled portable export (TAC-1404). Other engines behind the same store facade contract on supersede: a project that outgrows the D1 tier, or that has a workload D1 does not fit (relational semantics but scale beyond a single D1 database, non-Workers deploy target), supersedes this ADR with a project-level ADR selecting the alternate engine and replaces the facade's binding read with an engine-appropriate handle.",
+  "consequences": "The project inherits zero-infrastructure persistence at the Workers tier: no database server, no connection pool, no network round trip outside the vendor's own edge substrate. The binding is request-scoped inside the Worker; the facade is the one module the vendor surface lives in; migrations are a CI concern, not a boot-time runner; recovery is a wrangler command, not a hand-rolled backup daemon. The scale ceiling is the vendor's per-database size limit (a currently-published upper bound of 10 GB per D1 database on the Paid plan; 500 MB on the Free plan) plus the queries-per-Worker-invocation limit (currently 1000 on Paid, 50 on Free); a project whose steady-state working set outgrows either supersedes this ADR. Composing blueprints that hold an opinion on the store engine conflict on the `persistenceStore` topic; this blueprint's ADR is one of at least two shipped answers on the rcf-lite shelf (the other names a single-file local SQLite for non-Workers tiers), and the expected resolution is one project-level ADR that fixes the engine and states the tier reasoning.",
+  "alternativesConsidered": [
+    {
+      "name": "External Postgres reached from the Worker over HTTPS",
+      "summary": "Point the Worker at a hosted Postgres (Neon, Supabase, an operator-run cluster) reached via an HTTP-fronted client; the store facade wraps the HTTP client.",
+      "reasonNotChosen": "Wrong shape for the tier. A Workers-deployed application whose persistence is a network hop outside the vendor's edge substrate pays the round-trip on every request, gives up the vendor's built-in point-in-time recovery, and reintroduces the connection-pool sizing problem the Workers tier is supposed to remove. Projects whose scale genuinely needs Postgres supersede this ADR; the Workers tier is not where that supersede is default."
+    },
+    {
+      "name": "Cloudflare Workers KV as the substrate",
+      "summary": "Drop the relational shape and use KV as the persistence layer; the store facade wraps KV get/put.",
+      "reasonNotChosen": "The relational shape is what makes the query story sane for the domain the rcf-lite Workers-tier target typically ships. KV pushes the query problem into application code and gives up the constraint-checking safety net the SQL substrate provides for free. Projects whose domain is genuinely KV-shaped supersede this ADR and pick a KV blueprint when one ships."
+    },
+    {
+      "name": "Ship D1 and a second engine as co-contributed alternate TACs in one blueprint",
+      "summary": "Contribute D1 and Postgres store TACs side by side; the project picks one at apply time.",
+      "reasonNotChosen": "The rcf-lite blueprint mechanism (Phase 1) has no variant/profile selector. Two TACs contributed together are both applied, and both leave dangling tacIds references on their user stories if the project only realises one. The composable-vendor-siblings pattern (this blueprint plus the SQLite blueprint, each shipping its own opinion on `persistenceStore`, resolved at operator supersede time) is the shape the mechanism supports today; a mechanism-side variant concept is a future investment."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/adrs/adr-1402-persistence-data-d1-migration-discipline.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1402-persistence-data-d1-migration-discipline",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Numbered forward-only migrations owned by the vendor CLI; deploy pipeline gates the target Worker on the apply succeeding first",
+  "context": "Schema evolution in a Workers-deployed application has three failure modes: silent drift (the deployed database does not match the code's assumptions), half-application (a migration ran partway and left the database in an undefined shape), and deploy-order hazard (the Worker deploys ahead of the migration and starts failing per request against a schema behind its expectations). The migration story has to close all three at the substrate level. D1's vendor tooling already owns numbered forward-only migrations and per-database bookkeeping; the discipline this ADR sets is where the vendor's tooling fits into the deploy pipeline, and where the gate that prevents the deploy-order hazard lives.",
+  "decision": "Schema evolution is a directory of numbered `.sql` migration files under the wrangler-configured `migrations_dir` (default `migrations/`), one file per shipped change, applied by `wrangler d1 migrations apply <database> --env <target>`. The vendor's bookkeeping table (`migrations_table`, default `d1_migrations`) is the applied-state ledger; no project-side runner duplicates it. Half-application is closed by the vendor's own transaction semantics: each migration file's statements are applied under the vendor's atomicity guarantee, and a mid-apply failure surfaces as a wrangler non-zero exit. Deploy-order hazard is closed by the deploy-pipeline gate (TAC-1403): the CI job orders `wrangler d1 migrations apply` strictly before `wrangler deploy` for the same environment, and refuses the deploy on any apply failure. Forward-only: there are no down migrations; a rollback to an older schema is a redeploy against the older Worker build (whose migration set is a prefix), and the newer database refuses no request in that case because the older Worker's SQL literals target the older schema shape.",
+  "consequences": "Deploys are reproducible from a git ref because the migration directory and the Worker code ship in one commit. Half-migrations are structurally impossible at the D1 side. The Worker-behind-the-schema case is closed at deploy time by the CI gate; the operator sees a failed CI job instead of a customer-visible 5xx. The cost is that a botched schema change is a code fix and a redeploy of the migration file, not a schema-side undo: projects that need to revert a migration in-place cannot, and ship a compensating forward migration under a new number. Composing blueprints that hold their own opinion on migration discipline conflict on the `migrationDiscipline` topic; this ADR's opinion (vendor-CLI-owned, deploy-pipeline-gated) is deliberately distinct from a project-side boot-time runner discipline (the shape shipped by the SQLite blueprint on the same topic), and the expected resolution is one project-level ADR that fixes the discipline for the project.",
+  "alternativesConsidered": [
+    {
+      "name": "Boot-time migration runner inside the Worker",
+      "summary": "The first Worker request per isolate checks the schema version against a code-side max and runs pending migrations before serving.",
+      "reasonNotChosen": "Wrong shape for D1. Workers are cold-started per isolate and per region; a boot-time runner introduces a request-tax spike on every cold start, competes with concurrent isolates trying to apply the same migration, and depends on transaction primitives the D1 Worker binding does not expose (no explicit BEGIN/COMMIT; only `batch()` for multi-statement atomicity). The vendor's out-of-band apply is the shape the substrate supports; the CI gate is the shape that keeps deploy-order safe."
+    },
+    {
+      "name": "External migration tool (Drizzle Kit, Prisma Migrate, hand-rolled) instead of wrangler",
+      "summary": "Use an ORM-provided migration surface that talks to D1 through the same API; skip `wrangler d1 migrations`.",
+      "reasonNotChosen": "The vendor's tooling is the one path the vendor supports and updates as D1 evolves; an external tool that owns the bookkeeping table means the project reconciles two applied-state sources on every apply. Projects that pin an ORM can align it with wrangler by pointing `migrations_pattern` at the ORM's filename shape; the applied-state ledger stays with wrangler."
+    },
+    {
+      "name": "Application-side polling to detect a schema behind the code, and fail hot on detection",
+      "summary": "The Worker reads the schema version on each request and returns 503 when it observes a schema behind the code's expectations.",
+      "reasonNotChosen": "Trades one problem for another. The customer sees the 503 instead of the CI job seeing the failure; the recovery loop is the operator noticing the alert and running the apply manually. Ordering the apply in the deploy pipeline itself closes the window entirely instead of catching it in production."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/adrs/adr-1403-persistence-data-d1-event-secrecy.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1403-persistence-data-d1-event-secrecy",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Store event fields are restricted to store metadata; no domain-row values reach the event sink",
+  "context": "The store's event log describes the store's own lifecycle (facadeReady, migrationsApplied, backupExported, timeTravelRestored, queryFailed). The store also holds the domain's most sensitive material: session handles, token secrets, credential material, private keys, whatever the project stores. Conflating the two produces a log stream a downstream observability provider cannot be trusted with, and a log-store breach turns into a domain-data breach. The store's log shape is distinct from the application-api-rest tier's wire-log shape (topic `logging`, owned by the application-api-rest blueprint): this ADR governs the store event surface only.",
+  "decision": "Every field on every store event is restricted to store metadata: the event name string, an ISO-8601 timestamp, the binding name, the environment name, the database identifier, migration version integers and filenames, artifact paths, Time Travel bookmarks or timestamps, D1 error codes, and the domain-verb name that surfaced a queryFailed event. No event field is populated with a value read from a domain row; no event field is populated with a value derived from a domain-row column marked as secret. The discipline is enforced at emit time inside the facade (TAC-1401), the deploy gate (TAC-1403), and the recovery runner (TAC-1404); the sink is treated as though it ships every field to a third-party observability provider by default. Downstream redaction is not relied on. A queryFailed event carries the domain-verb name and the D1 error code, never the failed statement's parameter values.",
+  "consequences": "The store's event log is safe to ship to any observability provider the operator picks; no per-provider redaction rule is negotiated. A log-store breach exposes lifecycle metadata (when did the facade initialise, what migration versions applied, when did the last export land) but no domain data. Operators who need per-request correlation between the store's events and the domain surface derive a correlation id from something other than a row value (the request id is the intended surface). The REST tier's own log shape governs its own field set; the two logs may share a shipper but do not share this ADR's rules.",
+  "alternativesConsidered": [
+    {
+      "name": "Emit failed-statement parameter values inside queryFailed events under a downstream redaction rule",
+      "summary": "Ship rich queryFailed events with parameter context and rely on a log-shipper redactor to strip secret fields.",
+      "reasonNotChosen": "Redactors miss cases (new field, misspelled field, escaped value in a nested structure), and the log is already on disk on the emitting host by the time the redactor runs. Not-emitting-at-source is the only reliable posture; the domain-verb name plus the D1 error code is enough to open the diagnostic."
+    },
+    {
+      "name": "Hashed parameter values in event fields",
+      "summary": "Emit a stable hash of the parameter so investigations can correlate without exposing the plaintext.",
+      "reasonNotChosen": "A hashed session handle still lets an attacker with log access confirm 'this handle is the handle for that principal', which is enough for correlation attacks. The request id already provides the correlation surface without leaking anything, and no store-lifecycle event has a use case for domain-row correlation."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/adrs/adr-1404-persistence-data-d1-store-boundary.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1404-persistence-data-d1-store-boundary",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The D1 store facade is the only module that reads the D1 binding; consumers use named domain verbs, and every statement is a parameterised prepared statement",
+  "context": "A persistence boundary that leaks (the domain code reads the D1 binding from `env` directly, or the facade exposes a general-purpose raw-SQL passthrough) is a boundary the swap-out story does not work through, the test-double story does not work through, the reasoning-about-persistence-code-paths story does not work through, and (worse for D1 than for a local-file engine) the SQL-injection story does not work through: consumer-supplied string concatenation into a prepared-statement argument is functionally equivalent to a `db.exec(<consumer string>)` call, and the vendor's `prepare().bind()` chain is only safe when it stays a static SQL literal.",
+  "decision": "One module (the D1 store facade, TAC-1401) reads the D1 binding from the Worker `env`. Every other module in the source tree that touches persistence imports the facade and calls its named verbs. The facade's public surface exposes named domain verbs with typed parameters; it does not export the D1 binding, and it does not expose a general-purpose query method whose parameter is a SQL string or a prepared-statement object supplied by a consumer. Every statement the facade issues is a `db.prepare(<static SQL literal>).bind(<parameters>).first() | .all() | .run() | .raw()` chain; `db.exec(...)` is never called with a non-literal string; SQL is never constructed by string concatenation with consumer arguments. Multi-statement writes that require atomicity go through `db.batch([...])`; the facade never fakes atomicity by chaining sequential independent calls under an application-side try-catch.",
+  "consequences": "The engine choice is swappable because there is exactly one place that reads the binding. Domain tests run against an in-memory double that implements the same verb surface, without any reference to D1 at any point in the test's call path. Every persistence code path is discoverable by grepping for the facade's exports. Consumer arguments never traverse the SQL parser; the vendor's parameter-binding layer is the only place values reach the engine, and SQL injection is closed by construction rather than by discipline-at-call-site. Consumers pay a small cost when they need a new query shape (a facade edit and a consumer edit, in one commit); the size of that cost is the mechanism enforcing the boundary. Composing blueprints that contribute persistence-adjacent components (a cache, an outbox, a projection) contribute their own facade modules on the same discipline; every one of them imports the D1 store facade for its persistence needs, not the D1 binding.",
+  "alternativesConsidered": [
+    {
+      "name": "General-purpose raw-query passthrough on the facade",
+      "summary": "The facade exposes `execute(sql, params)` that consumers use for ad-hoc queries the facade does not otherwise express.",
+      "reasonNotChosen": "Any raw-query passthrough migrates over time from 'occasional escape hatch' to 'the way consumers write queries'. Every such call site is a code path that has to be re-audited on an engine swap, a code path that cannot be tested against an in-memory double, and (uniquely damaging on D1) a code path where the consumer-supplied SQL string is one edit away from a SQL-injection surface. The escape hatch is not worth the boundary erosion."
+    },
+    {
+      "name": "Domain-code direct env reads for hot-path queries",
+      "summary": "Performance-sensitive queries read `env.<BINDING_NAME>` directly and skip the facade.",
+      "reasonNotChosen": "Performance is not a defensible reason to erode the boundary at the rcf-lite Workers-tier target: the facade adds no measurable overhead over the direct binding read, and hot-path queries that genuinely need it are a rare-enough case to justify a specialised facade verb rather than a binding-read shortcut. Projects that outgrow the tier and need a different posture do so by superseding this ADR with reasoning."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/adrs/adr-1405-persistence-data-d1-recovery-model.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1405-persistence-data-d1-recovery-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Recovery is Time Travel point-in-time restore plus a scheduled portable export; both paths carry the load, neither substitutes for the other",
+  "context": "A recovery model has three axes: what the artifact is (an in-vendor point-in-time snapshot, a portable dump, a stream), when it is available (bounded lookback, unbounded off-vendor retention), and how it recovers (rewind in place, replay against a fresh database, promote a replica). D1 has one built-in fast path (Time Travel point-in-time recovery, bounded by the plan's recovery window) and one vendor-provided portable path (`wrangler d1 export`, unbounded off-vendor retention when the operator holds the artifacts). Neither substitutes for the other; the two together cover the recovery cases a Workers-tier project actually faces.",
+  "decision": "The recovery model is two paths, both configured in the project and both exercisable from the ops or CI surface without a Worker code change (TAC-1404). Path one, Time Travel: `wrangler d1 time-travel restore <database> --timestamp=<unix-seconds>`; the target database rewinds in place to the recorded state at the named timestamp within the vendor's supported recovery window (currently 30 days on Paid, 7 days on Free). Path two, portable export: a scheduled `wrangler d1 export <database> --output <artifact-path> --remote`; the artifact is a `.sql` file the project stores off-vendor (a repository asset, an R2 bucket, an object store the project already runs); recovery is `wrangler d1 execute --file <artifact-path>` into a fresh database (with any BEGIN TRANSACTION / COMMIT statements stripped per the vendor's import guidance). Every invocation of either path emits a structured event on the store event log: `timeTravelRestored` or `backupExported`; event fields are metadata only per ADR-1403.",
+  "consequences": "The operator has a one-command answer to the accidental-drop and bad-migration cases inside the vendor recovery window (Time Travel), and a portable off-vendor artifact for the compliance-retention and vendor-outage cases (export). No Worker code change is required to exercise either path; the ops surface is where recovery lives. Time Travel is destructive in place (the vendor's contract), so an operator restoring under uncertainty pairs a pre-restore export with the restore. The export path is slow enough that the vendor's own guidance warns it blocks other database requests for the duration; schedule it in low-traffic windows. Composing blueprints that hold their own opinion on recovery (a replication-based failover blueprint, a logical-dump-only blueprint) supersede this ADR at the project level; the two-path posture is the shape D1's currently published tooling supports.",
+  "alternativesConsidered": [
+    {
+      "name": "Time Travel only, no scheduled export",
+      "summary": "Rely on Time Travel's bounded recovery window; skip the export step and the off-vendor artifact.",
+      "reasonNotChosen": "Loses the compliance-retention story and the vendor-outage story. An operator whose regulator asks 'produce the state as of six months ago' cannot answer from Time Travel alone once the plan window expires, and an operator locked out of the vendor console cannot restore without an off-vendor artifact. The export step is cheap enough to keep as the second path."
+    },
+    {
+      "name": "Scheduled export only, no Time Travel usage",
+      "summary": "Treat Time Travel as a vendor feature the project does not exercise; recover only from the exported artifact.",
+      "reasonNotChosen": "Loses the fast in-place restore path Time Travel gives for free. An accidental drop is a one-command Time Travel restore inside the window; forcing every recovery through export-and-reimport pays the export run time on every drill and gives up the vendor's in-place semantics. The two paths cost little to keep both."
+    },
+    {
+      "name": "Continuous replication to a second D1 database",
+      "summary": "Stand up a second database and stream writes; failover by pointing the binding at the replica.",
+      "reasonNotChosen": "D1's currently published replication surface (read replicas via `withSession`) targets read scaling, not failover. A project that genuinely needs failover semantics supersedes this ADR with a project-level ADR selecting an alternate engine that provides them; the Workers-tier target this blueprint targets is not where failover is default."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/requirements/persistence-data-d1-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-d1-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Every persistent entity lives in one D1 database accessed through one facade module",
+  "description": "The application persists every stateful entity (session records, work items, audit trail, whatever the project's domain model requires) in a single D1 database bound into the Worker under a named binding. One facade module in the source tree is the sole reader of that binding; every other module that touches persistence imports the facade and calls its named domain verbs. The D1 binding is never destructured or re-exported outside the facade module.",
+  "category": "functional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "D1 is only available inside the Worker request context; a single facade module is what turns that request-scoped binding into an application-side surface with domain-shaped verbs. Multiple call sites reaching into env for the binding produces a codebase where the shape of the store, the parameter binding discipline, and the event-emission discipline are all diffused across the tree. One facade means one place to test, one place to swap, and one place where the persistence code paths are discoverable.",
+  "tags": [
+    "blueprint:persistence-data-d1",
+    "category:01-store-facade"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/requirements/persistence-data-d1-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-d1-REQ-002",
+  "prdId": "PRD-001",
+  "title": "The store schema evolves through numbered forward-only migration files managed by the wrangler CLI",
+  "description": "Schema evolution is expressed as a directory of numbered `.sql` migration files under the project-side migrations folder configured in the wrangler binding (`migrations_dir`). Each file's leading version integer is monotonic and unique; the file body is engine-native SQL. Applying migrations is the wrangler CLI's responsibility (`wrangler d1 migrations apply <database> --env <target>`), which tracks applied versions in the D1-side bookkeeping table configured by `migrations_table` (default `d1_migrations`). The project's source tree does not carry a hand-rolled migration runner; the wrangler CLI is the runner.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "D1 is a managed service whose vendor tooling already owns the migration surface (create/list/apply plus a bookkeeping table). Layering a project-side runner on top duplicates the vendor's contract and forces a project to reconcile two sources of truth on 'has this migration applied'. Delegating to wrangler keeps the vendor's bookkeeping authoritative, the migration file shape portable to any project reading these docs, and the deploy pipeline the one place migration application is orchestrated.",
+  "tags": [
+    "blueprint:persistence-data-d1",
+    "category:02-migration-catalog"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/requirements/persistence-data-d1-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-d1-REQ-003",
+  "prdId": "PRD-001",
+  "title": "The Worker deploy pipeline refuses to deploy a build whose migrations set has not been applied to the target environment first",
+  "description": "The deploy pipeline runs `wrangler d1 migrations apply <database> --env <target>` as a step ordered strictly before `wrangler deploy` against the same environment. When the migrations apply step exits non-zero (a migration statement failed, the database is unreachable, the CI credential lacks apply permission), the deploy pipeline fails and no Worker deploy is attempted against that environment. When the migrations apply step exits zero, the deploy pipeline proceeds; the Worker deploying against the target reads a database at or ahead of the migration set the code was built against.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "D1 is not opened at process boot; a Worker isolate that observes a schema behind the code's expectations fails per request, not at deploy, and the operator sees the failure as customer-visible 5xxs instead of a red CI job. Ordering the apply strictly before the deploy in the pipeline makes the schema-behind-the-code case impossible in production: the migration set either applies cleanly and the deploy proceeds, or the apply fails and the older Worker keeps serving on the older schema.",
+  "tags": [
+    "blueprint:persistence-data-d1",
+    "category:03-deploy-gate"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/requirements/persistence-data-d1-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-d1-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Every statement the facade issues against D1 is a parameterised prepared statement; no consumer-supplied SQL reaches the binding",
+  "description": "The facade module issues every read or write against D1 through the prepared-statement surface: `db.prepare(<static SQL literal>).bind(<parameters>).first()`, `.all()`, or `.run()`. The static SQL literal is authored inside the facade module and does not embed values from consumer arguments through string concatenation, template interpolation, or any other join that produces a call-site-specific SQL fragment. The facade does not export a general-purpose query method whose parameter is a SQL string supplied by a consumer, and it does not use `db.exec(<consumer string>)` on any path.",
+  "category": "security",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "D1's prepared-statement surface is the only path that binds parameters through the vendor's escaping layer; SQL concatenated at a call site is a SQL-injection surface exactly the way it is on any other engine, and D1's ergonomic prepare/bind chain removes the excuse to reach for concatenation. Restating the discipline as a REQ that binds runtime-observable ACs turns the vendor's ergonomic default into a shipped floor of the blueprint.",
+  "tags": [
+    "blueprint:persistence-data-d1",
+    "category:04-prepared-statements"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/requirements/persistence-data-d1-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-d1-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Multi-statement writes that require atomicity are issued through the batch surface; the facade never surfaces a partial-batch result",
+  "description": "When the facade needs to commit two or more statements as one unit (a domain operation that writes to more than one table, an insert-then-update pair whose semantics depend on both landing), the facade issues them through `db.batch([<prepared statements>])`. On any statement in the batch failing, the facade surfaces the failure to the caller without surfacing any of the batch's other statement results as though they had committed. Single-statement writes commit as their own transaction; the facade does not synthesise atomicity across independent facade calls, and consumers do not chain facade calls under the assumption that they run in one transaction.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "D1 does not expose explicit BEGIN/COMMIT to the Worker binding; `batch()` is the only vendor-supported multi-statement atomicity primitive, and its contract is that a mid-batch failure rolls back the sequence. Naming that surface explicitly at the REQ level puts every domain operation whose correctness depends on multi-statement atomicity on the one path the vendor's contract supports. Refusing to expose partial-batch results means a consumer never has to reason about whether an error is 'some statements landed, some did not'; either the batch committed or it did not.",
+  "tags": [
+    "blueprint:persistence-data-d1",
+    "category:05-batch-atomicity"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/requirements/persistence-data-d1-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-d1-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Recovery is available through Time Travel point-in-time recovery and through a scheduled export to a portable artifact",
+  "description": "Recovery has two paths, both configured in the project. Path one: Time Travel, the vendor's built-in point-in-time recovery, invoked via `wrangler d1 time-travel restore <database> --timestamp=<unix-seconds>`; the recovery window is the vendor's supported window at the project's plan tier. Path two: a scheduled `wrangler d1 export <database> --output=<artifact> --remote` producing a portable `.sql` artifact written to a project-configured destination (a repository asset, an R2 bucket, an object store the project already runs); the schedule and destination are project-configured. Both paths preserve the schema and rows at the recovery moment; both are exercisable from the CI or ops surface without a Worker code change.",
+  "category": "nonFunctional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Time Travel is the natural first line of defence for D1: it is built in, requires no configuration, and covers the operator's likely restore window (accidental drop, bad deploy) inside a bounded lookback. It is not a substitute for a portable dump: the recovery window is finite, the restore is in-place and destructive, and an operator whose compliance model demands off-vendor retention needs the export as well. Naming both paths at the REQ level makes the two-part recovery posture a floor, not a project convention.",
+  "tags": [
+    "blueprint:persistence-data-d1",
+    "category:06-recovery"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/requirements/persistence-data-d1-req-007.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-d1-REQ-007",
+  "prdId": "PRD-001",
+  "title": "The store lifecycle event log holds no secret material",
+  "description": "No field on any store lifecycle event (facadeReady, migrationsApplied, backupExported, timeTravelRestored, queryFailed) carries user data, credential material, session handles, token secrets, private keys, or the values of any column marked as secret in the domain schema. Event fields are limited to store metadata: the binding name, environment name, ISO-8601 timestamps, migration version integers, migration filenames, artifact paths, Time Travel bookmarks or timestamps, D1 error codes, and the domain-verb name that surfaced a queryFailed event.",
+  "category": "security",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "The event log is safe to ship to a third-party observability provider only if it holds no secret material. Store events describe the store's own lifecycle, not the domain data it holds; conflating the two produces a log stream a leak turns into a session-takeover breach. Enforcing metadata-only at emit time inside the facade is the only reliable posture; downstream redaction misses cases.",
+  "tags": [
+    "blueprint:persistence-data-d1",
+    "category:07-log-secrecy"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}