rcf-lite 0.12.0 → 0.14.0

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"
+}

package/blueprints/persistence-data-d1/contributions/tacs/tac-1401-persistence-data-d1-facade.json

@@ -0,0 +1,51 @@
+{
+  "tacId": "TAC-1401-persistence-data-d1-facade",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "D1 store facade",
+  "purpose": "The single Worker-side module that reads the D1 binding from `env`, exposes narrow named domain verbs to consumer code, issues every query as a parameterised prepared statement, batches multi-statement writes that require atomicity, and emits structured lifecycle events to the injected sink. Consumers never destructure the D1 binding outside this module; the facade is the one place the vendor surface lives.",
+  "responsibilities": [
+    "Read the D1 binding from the Worker `env` under the configured binding name; hold no other reference to the vendor surface; export no symbol that leaks the raw binding (AC-13101-1, AC-13101-2).",
+    "Expose the domain CRUD verbs as named exports with typed parameters; refuse a general-purpose raw-SQL passthrough on the public surface (AC-13101-2, AC-13104-2).",
+    "Issue every read and write through `db.prepare(<static SQL literal>).bind(<parameters>).first() | .all() | .run() | .raw()`; never call `db.exec(...)` with a non-literal string; never build SQL by string concatenation with consumer arguments (AC-13104-1, AC-13104-3).",
+    "Issue multi-statement writes requiring atomicity through a single `db.batch([...])` call; surface no partial-batch result on a mid-batch failure (AC-13105-1, AC-13105-2, AC-13105-3).",
+    "Emit structured lifecycle events on the injected onEvent sink: facadeReady on first invocation per Worker isolate, queryFailed on any prepared-statement or batch failure the facade catches. Carry only store-metadata fields; never carry values read from domain rows (AC-13107-1, AC-13107-2)."
+  ],
+  "internalStructure": "One module that exports a `createStore({ env, bindingName, onEvent })` factory returning a facade object whose methods are the named CRUD verbs plus an event-sink hook. The D1 binding read is scoped to this module; the factory captures the binding reference and the sink and hands back a set of closures. Consumers destructure the verbs they need at their top level and hold the facade reference for the Worker request's lifetime (or, when the isolate reuses the facade across requests, for the isolate's lifetime).",
+  "interfaces": [
+    {
+      "name": "createStore",
+      "kind": "factory",
+      "description": "createStore({ env, bindingName, onEvent }) -> Store; the sole entry point every consumer calls. Reads env[bindingName] as the D1 binding; hands back a Store whose methods are the named CRUD verbs."
+    },
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with { event, ts, ... } for facadeReady and queryFailed events. Never invoked with domain-row values."
+    },
+    {
+      "name": "store.verbs",
+      "kind": "read-write-api",
+      "description": "The named domain CRUD verbs the facade exposes. Each verb has typed parameters; no verb accepts a raw SQL string or a general query object from consumer code."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Migration catalog",
+      "kind": "tac",
+      "tacId": "TAC-1402-persistence-data-d1-migration-catalog",
+      "description": "The catalog directory the wrangler CLI applies against the target database; the facade does not import it at runtime, but its schema is what the facade's static SQL literals target."
+    },
+    {
+      "name": "Recovery runner",
+      "kind": "tac",
+      "tacId": "TAC-1404-persistence-data-d1-recovery-runner",
+      "description": "Shares the facade's event sink for backupExported and timeTravelRestored events; invoked from the ops or CI surface, not from Worker code."
+    }
+  ],
+  "tradeoffs": "The facade holds no long-lived engine handle: D1 is request-scoped, and each Worker invocation reads env for the binding. That cost buys the same one-boundary invariant every other AC on this blueprint depends on. Projects that need per-verb tracing or connection-scoped context (session tokens for read-replica routing via `withSession`) wire it inside this module and preserve the facade's outward interface unchanged.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/tacs/tac-1402-persistence-data-d1-migration-catalog.json

@@ -0,0 +1,31 @@
+{
+  "tacId": "TAC-1402-persistence-data-d1-migration-catalog",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Wrangler-managed migration catalog",
+  "purpose": "The in-tree source of schema truth. A directory of numbered `.sql` migration files, one per shipped schema change, under the path configured on the D1 binding's `migrations_dir` (default `migrations/`). Each filename carries a monotonic version integer; each file body is engine-native SQL. The wrangler CLI is the applier; the D1 side of the bookkeeping table (`migrations_table`, default `d1_migrations`) is the applied-state ledger. The catalog itself contributes no runtime code.",
+  "responsibilities": [
+    "Hold every schema change ever shipped in this project's history as one `.sql` file under the configured migrations directory. Each filename begins with a monotonic integer that is unique across the directory (AC-13102-1).",
+    "Match the wrangler configuration: `d1_databases[<index>].migrations_dir` names the directory; `migrations_table` names the bookkeeping table (default `d1_migrations`); `migrations_pattern` selects the file glob (default is the wrangler-generated numbered form). Any deviation from the defaults is explicit on the binding, not implicit in the tree layout (AC-13102-1, AC-13102-2).",
+    "Support the `wrangler d1 migrations list` / `apply` cycle against `--local` for development and `--remote` for the target environment; the applied-state ledger is the D1 database's own bookkeeping table (AC-13102-2, AC-13102-3)."
+  ],
+  "internalStructure": "One source-tree directory (the wrangler-configured migrations directory) containing one `.sql` file per shipped migration. Files are appended, never edited: a shipped migration is a fact of production, and any correction is a new migration that supersedes it. The statements are engine-native SQL. No Worker-side module imports the directory at runtime; the wrangler CLI is the sole reader, and the D1 bookkeeping table is the applied-state fact.",
+  "interfaces": [
+    {
+      "name": "migrations/",
+      "kind": "directory",
+      "description": "The source-tree directory named on `d1_databases[].migrations_dir`; holds one numbered `.sql` file per shipped migration."
+    },
+    {
+      "name": "d1_migrations",
+      "kind": "table",
+      "description": "The D1-side bookkeeping table named on `d1_databases[].migrations_table`; wrangler writes one row per applied migration. Read via `wrangler d1 execute <database> --command \"SELECT * FROM <table>\"` for verification."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "One numbered file per migration is trivial to reason about at small history and starts to lengthen the directory listing at large history (dozens of files); the tradeoff mirrors any file-per-migration migration tool. The vendor tooling picks the file naming for `wrangler d1 migrations create`; a project can override `migrations_pattern` for ORM compatibility (Drizzle, Prisma) at the cost of pinning that ORM into the pipeline. Statements-as-SQL keeps the catalog readable but couples it to D1's SQLite dialect; a project that intends to swap engines pays that translation cost at swap time, not now.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/tacs/tac-1403-persistence-data-d1-deploy-gate.json

@@ -0,0 +1,38 @@
+{
+  "tacId": "TAC-1403-persistence-data-d1-deploy-gate",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Deploy-time migration gate",
+  "purpose": "The CI or ops-side step that runs `wrangler d1 migrations apply <database> --env <target>` strictly before `wrangler deploy --env <target>` for the same environment; refuses to publish a new Worker version when the migration apply fails; emits a structured `migrationsApplied` event on the store event log on each successful apply.",
+  "responsibilities": [
+    "Run `wrangler d1 migrations apply <database> --env <target>` as a step whose completion is a hard prerequisite for the deploy step against the same environment (AC-13103-1).",
+    "Fail the deploy job when the migrations-apply step exits non-zero; do not run `wrangler deploy` against that environment; leave the previously deployed Worker in place (AC-13103-2).",
+    "Emit one `migrationsApplied` event per successful apply carrying the environment name, the database identifier, the applied migration filenames or version integers, and the ISO-8601 completion timestamp; carry no domain-row values (AC-13103-3, AC-13107-1)."
+  ],
+  "internalStructure": "A CI job (GitHub Actions step, or the project's equivalent) whose YAML or configuration is committed alongside the Worker source. The step invokes wrangler via the vendor's own action or via a direct `pnpm exec wrangler d1 migrations apply` call; environment secrets are supplied by the CI credential store, following the discipline the project's secrets management sets. On success, the step invokes the project's event-emission surface with a `migrationsApplied` payload before the deploy step runs.",
+  "interfaces": [
+    {
+      "name": "ciStep.migrationsApply",
+      "kind": "ci-step",
+      "description": "The CI job step that runs `wrangler d1 migrations apply <database> --env <target>`; declared as a prerequisite for the deploy step."
+    },
+    {
+      "name": "ciStep.deploy",
+      "kind": "ci-step",
+      "description": "The CI job step that runs `wrangler deploy --env <target>`; declares the migrations-apply step as its prerequisite (needs, depends-on, or sequential ordering per the CI tool)."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Migration catalog",
+      "kind": "tac",
+      "tacId": "TAC-1402-persistence-data-d1-migration-catalog",
+      "description": "The directory the apply step reads; the file set at HEAD determines what the apply attempts."
+    }
+  ],
+  "tradeoffs": "Ordering the apply strictly before the deploy costs a small amount of CI latency per environment (one wrangler invocation, one round trip to the D1 API) in exchange for making the schema-behind-the-code state impossible in production. Projects that need faster CI can parallelise across environments, but never inside one environment's apply-then-deploy sequence. The gate is a project-authored CI file; the blueprint does not ship a CI template, because CI shape is a `delivery-ci-workflows`-adjacent concern the project owns.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/tacs/tac-1404-persistence-data-d1-recovery-runner.json

@@ -0,0 +1,39 @@
+{
+  "tacId": "TAC-1404-persistence-data-d1-recovery-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Recovery runner (Time Travel and export)",
+  "purpose": "The project-side ops surface that exercises D1's two recovery paths without a Worker code change: `wrangler d1 time-travel restore <database> --timestamp=<unix-seconds>` for the in-vendor point-in-time restore path, and `wrangler d1 export <database> --output <artifact> --remote` for the off-vendor portable-artifact path. Emits `backupExported` and `timeTravelRestored` events on the store event log at each invocation.",
+  "responsibilities": [
+    "Invoke `wrangler d1 time-travel restore <database> --timestamp=<unix-seconds>` on operator request; the target database is rewound in place to the recorded state at the named timestamp within the vendor's supported recovery window (AC-13106-1).",
+    "Invoke `wrangler d1 export <database> --output <artifact-path> --remote` on the configured schedule; the artifact file is written to the project-configured destination (a repository asset, an R2 bucket, an object store the project already runs); the artifact is a portable `.sql` file that reloads into a fresh D1 via `wrangler d1 execute --file <artifact-path>` (after stripping BEGIN TRANSACTION / COMMIT statements per the vendor's import guidance) (AC-13106-2).",
+    "Emit `backupExported` and `timeTravelRestored` events on the store event log carrying only store-metadata fields (target database, artifact path, restore timestamp or bookmark, ISO-8601 completion timestamp); never carry values read from domain rows (AC-13106-1, AC-13106-2, AC-13107-1).",
+    "Run entirely from the project's ops or CI surface; require no Worker source change to invoke either path (AC-13106-3)."
+  ],
+  "internalStructure": "A small set of ops-side scripts or CI job steps (project-authored) that invoke the wrangler commands and post events to the project's log sink. The runner shares the facade's onEvent contract (metadata only, no domain values) but does not import the facade module; the two surfaces meet only through the shared event-record shape.",
+  "interfaces": [
+    {
+      "name": "recovery.timeTravelRestore",
+      "kind": "ops-command",
+      "description": "recovery.timeTravelRestore({ database, env, timestamp }) invokes `wrangler d1 time-travel restore` and emits the timeTravelRestored event."
+    },
+    {
+      "name": "recovery.export",
+      "kind": "ops-command",
+      "description": "recovery.export({ database, env, outputPath }) invokes `wrangler d1 export` and emits the backupExported event."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Store facade",
+      "kind": "tac",
+      "tacId": "TAC-1401-persistence-data-d1-facade",
+      "description": "Shares the event-record shape used for backupExported and timeTravelRestored; the runner does not import the facade module at runtime."
+    }
+  ],
+  "tradeoffs": "Time Travel is the vendor's built-in fast path but bounded by the plan's recovery window (7 days on Free, 30 days on Paid at the vendor's currently published limits); an operator whose compliance model needs longer retention runs the export step on a schedule and holds the artifacts off-vendor. The export path is portable at the cost of run time (an export blocks other database requests for the duration per the vendor's current guidance), so schedule it in low-traffic windows. Neither path fully covers the other; the two-path posture is the shape the vendor's tooling produces.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/user-stories/persistence-data-d1-us-13101.json

@@ -0,0 +1,45 @@
+{
+  "usId": "persistence-data-d1-US-13101",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-d1-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One facade module is the only place the D1 binding is read",
+  "asA": "developer who needs the domain code to stay swappable and testable across the persistence boundary",
+  "iWant": "one facade module to hold the D1 binding and expose named domain verbs, with no consumer reaching into env for the binding directly",
+  "soThat": "the boundary between the domain and the D1 vendor surface is the only place that has to move when the vendor changes and the only place tests have to double",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13101-1",
+      "description": "Exactly one source-tree module reads the D1 binding from the Worker `env`. Every other module that touches persistence imports the facade module and calls its named domain verbs.",
+      "given": "the running source tree after a Worker request is handled",
+      "when": "the import graph and source tree are inspected for the D1 binding reference (`env.<BINDING_NAME>` where BINDING_NAME is the value configured on `d1_databases[].binding` in the project's wrangler config)",
+      "then": "the reference appears in exactly one file (the facade module) and no other file in the source tree contains the reference, verified by an import-graph query or a targeted grep against the configured binding name",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13101-2",
+      "description": "The facade exposes named domain verbs for every persistence operation the domain requires; the facade module does not export the raw D1 binding or a general-purpose query method that accepts a raw SQL string from consumer code.",
+      "given": "the facade module's public surface",
+      "when": "the surface is inspected",
+      "then": "every exported symbol is either a named domain verb with typed parameters or an event-sink registration; no exported symbol is the D1 binding itself, and no exported function accepts a raw SQL string as a call argument from consumer code",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13101-3",
+      "description": "Replacing the facade module with an in-memory double that implements the same verb surface allows the domain code to run against it without any reference to the D1 binding.",
+      "given": "a test double implementing the same named verbs as the facade with an in-memory backing store",
+      "when": "the domain code runs against the double in place of the facade",
+      "then": "the domain code executes to completion with no reference to the D1 binding on its call path, and its behaviour is unchanged from a facade-backed run for the operations under test",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1401-persistence-data-d1-facade"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/user-stories/persistence-data-d1-us-13102.json

@@ -0,0 +1,45 @@
+{
+  "usId": "persistence-data-d1-US-13102",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-d1-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Schema evolution ships as numbered forward-only migration files under a wrangler-managed directory",
+  "asA": "operator who needs deploys reproducible from a git ref with no schema state outside version control",
+  "iWant": "every schema change to be a new numbered `.sql` file under the wrangler-configured migrations directory, applied by the wrangler CLI",
+  "soThat": "the schema shape at any deployed version can be read from the committed files and the vendor's own tooling is the single applier",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13102-1",
+      "description": "The migrations directory named on the D1 binding (`migrations_dir` in the project's wrangler config; default `migrations/`) exists in the source tree and contains one `.sql` file per shipped migration. Each filename begins with a monotonic integer that is unique across the directory; the file body is engine-native SQL.",
+      "given": "the source tree at any commit that produces a running Worker",
+      "when": "the migrations directory is listed and each filename's leading integer is extracted",
+      "then": "the sequence of leading integers is strictly increasing with no duplicates, every file has a non-empty SQL body, and no file in the directory falls outside the wrangler-configured pattern",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13102-2",
+      "description": "Running `wrangler d1 migrations list <database> --local` against a fresh local D1 lists every file in the migrations directory as unapplied; running `wrangler d1 migrations apply <database> --local` applies them in order and a subsequent `list` reports zero unapplied.",
+      "given": "a fresh local D1 (no prior applies) and the migrations directory from AC-13102-1",
+      "when": "the `list` then `apply` then `list` sequence runs against the local database",
+      "then": "the first `list` prints every migration file as unapplied, the `apply` exits zero, and the second `list` prints zero unapplied migrations",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13102-3",
+      "description": "The D1 bookkeeping table configured on the binding (`migrations_table`; default `d1_migrations`) holds one row per applied migration, keyed by the filename or its leading integer, after `wrangler d1 migrations apply` completes.",
+      "given": "the local D1 after the `apply` in AC-13102-2 completes",
+      "when": "the bookkeeping table is read via `wrangler d1 execute <database> --local --command \"SELECT * FROM d1_migrations\"` (or the configured `migrations_table` name)",
+      "then": "the returned row count equals the number of migration files in the directory, and the recorded identifiers match the migration filenames or their leading integers",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1402-persistence-data-d1-migration-catalog"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/contributions/user-stories/persistence-data-d1-us-13103.json

@@ -0,0 +1,46 @@
+{
+  "usId": "persistence-data-d1-US-13103",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-d1-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Deploy is gated on migrations applying cleanly to the target environment first",
+  "asA": "operator whose Worker deploys must never reach production ahead of the schema they were built against",
+  "iWant": "the deploy pipeline to run `wrangler d1 migrations apply` before `wrangler deploy` for the same environment, and to abort the deploy on any apply failure",
+  "soThat": "a schema-behind-the-code state is impossible in production and a bad migration fails the CI job instead of the customer request",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13103-1",
+      "description": "The deploy pipeline definition for each environment contains a `wrangler d1 migrations apply <database> --env <target>` step ordered strictly before the `wrangler deploy --env <target>` step; the Worker deploy step declares the migrations-apply step as a prerequisite (job dependency, sequential step, or equivalent).",
+      "given": "the CI pipeline configuration for the project (GitHub Actions workflow, or the pipeline the project uses)",
+      "when": "the deploy job's step list is inspected for each environment",
+      "then": "the migrations-apply step appears before the deploy step in that job, and any parallelism configuration is such that the deploy cannot start until the apply has exited zero",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13103-2",
+      "description": "A pipeline run where `wrangler d1 migrations apply` exits non-zero fails the deploy job and does not run `wrangler deploy` against that environment.",
+      "given": "a branch on which the migrations set contains a statement that fails at apply (an ALTER against a missing table, a syntactically invalid statement) and the CI pipeline is triggered",
+      "when": "the pipeline runs",
+      "then": "the migrations-apply step exits non-zero, the deploy step does not execute, the deploy job is reported as failed, and no new Worker version has been published to the target environment",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13103-3",
+      "description": "The deploy pipeline emits a `migrationsApplied` structured event on the store event log per successful apply, carrying the environment name, the target database name or identifier, the applied migration filenames or version integers, and the ISO-8601 completion timestamp. No event field carries a domain-row value.",
+      "given": "a successful CI run whose migrations-apply step applied at least one migration",
+      "when": "the store event log for that CI run is inspected",
+      "then": "the log contains exactly one migrationsApplied event whose metadata fields match the run and whose payload contains no value read from a domain table",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1403-persistence-data-d1-deploy-gate",
+    "TAC-1402-persistence-data-d1-migration-catalog"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}