rcf-lite 0.11.0 → 0.13.0

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 `ci-pipeline`-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"
+}

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

@@ -0,0 +1,45 @@
+{
+  "usId": "persistence-data-d1-US-13104",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-d1-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every facade query is a parameterised prepared statement",
+  "asA": "developer who needs the persistence boundary to leave no SQL-injection surface for consumer arguments",
+  "iWant": "every facade query to be a static SQL literal issued via `db.prepare(...).bind(...)`, with no string-concatenated SQL and no `exec(<consumer string>)` on any path",
+  "soThat": "consumer arguments never traverse the SQL parser and the vendor's parameter-binding layer is the only place values reach the engine",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13104-1",
+      "description": "Every call site in the facade module that reaches the D1 binding is a `db.prepare(<static SQL literal>).bind(...)` chain terminating in `.first()`, `.all()`, `.run()`, or `.raw()`. No call site inside the facade calls `db.exec(...)` with any string other than a static SQL literal authored inside the facade module.",
+      "given": "the facade module source",
+      "when": "every call to the D1 binding is inspected for its SQL argument shape",
+      "then": "every `prepare` argument is a static string literal (not a template with an interpolation for a value, not a `+`-concatenation with any consumer argument, not a function-returned string) and no `exec` call takes a non-literal string; a targeted grep for `\\.exec(`, `\\.prepare(` template-literal interpolations, and `\\+` inside prepared-statement arguments returns only the known-safe literal-static occurrences the facade documents",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13104-2",
+      "description": "The facade does not export a general-purpose query method whose parameter is a SQL string supplied by a consumer.",
+      "given": "the facade module's exported surface",
+      "when": "the surface is inspected",
+      "then": "no exported function's typed parameter list includes a SQL-string parameter (a parameter named `sql`, `query`, `statement`, or typed as an arbitrary string that reaches `db.prepare` or `db.exec` inside the facade body); the boundary refuses raw-query passthrough by construction",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13104-3",
+      "description": "A facade verb invoked with a value containing SQL metacharacters (a semicolon, a comment marker, an OR-1=1 fragment, a quote) treats the value as a bound parameter, not as SQL syntax: the resulting query behaves as if the value were the literal string.",
+      "given": "a facade verb that accepts a string argument (a lookup by name, an insert of a title, an update by identifier) and a probe value containing the literal characters `'; DROP TABLE domainTable; --`",
+      "when": "the verb is invoked with the probe value against a local D1 database",
+      "then": "the invocation completes without side-effect against tables other than the one the verb legitimately touches, and a follow-up `SELECT COUNT(*) FROM domainTable` returns the same count as before the invocation (no DROP), and the probe value round-trips as an ordinary string wherever the verb persisted or returned it",
+      "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-13105.json

@@ -0,0 +1,45 @@
+{
+  "usId": "persistence-data-d1-US-13105",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-d1-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Multi-statement atomicity is expressed through batch; no partial result is ever surfaced",
+  "asA": "developer whose domain operations require two or more statements to land as one unit or none",
+  "iWant": "the facade to issue such operations through `db.batch([...])` and to surface no partial-batch result on any failure path",
+  "soThat": "a consumer never has to reason about 'some statements landed, some did not' and mid-batch failures roll back cleanly",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13105-1",
+      "description": "Every facade verb whose implementation requires multi-statement atomicity issues its statements through a single `db.batch([...])` invocation; the facade does not synthesise atomicity by issuing sequential `db.prepare(...).run()` calls under an application-side try-catch.",
+      "given": "the facade module source",
+      "when": "every verb whose responsibility involves writing to two or more rows across two or more statements is inspected",
+      "then": "each such verb issues its statements as one `db.batch([...])` call whose array contains every statement the atomicity claim covers, and no such verb chains sequential independent facade calls to fake atomicity",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13105-2",
+      "description": "A facade verb whose batch fails mid-sequence (a UNIQUE constraint violation on the second statement of a two-statement batch) surfaces the failure to the caller without persisting the first statement.",
+      "given": "a facade verb that batches an insert into table A followed by a constraint-violating insert into table B, and a local D1 database primed to violate the constraint",
+      "when": "the verb is invoked and the batch fails",
+      "then": "the caller receives an error, and a follow-up read against table A shows no row corresponding to the first statement of the failed batch (D1 rolled the batch back)",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13105-3",
+      "description": "The facade does not export a public method whose contract implies atomicity across two separate facade calls; consumers do not chain facade calls under a transaction assumption because no facade surface offers one.",
+      "given": "the facade module's public surface and any documentation the facade emits",
+      "when": "the surface is inspected for begin/commit primitives, transaction-block wrappers, or documentation promising cross-call atomicity",
+      "then": "no such surface exists on the facade, and every atomicity claim in facade documentation is scoped to a single verb whose implementation uses `db.batch([...])`",
+      "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-13106.json

@@ -0,0 +1,46 @@
+{
+  "usId": "persistence-data-d1-US-13106",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-d1-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Recovery is available through Time Travel and through a scheduled export to a portable artifact",
+  "asA": "operator whose recovery model has to cover a fast in-place restore and an off-vendor durable copy",
+  "iWant": "Time Travel point-in-time recovery for the fast path and a scheduled `wrangler d1 export` for the durable path",
+  "soThat": "an accidental drop is a one-command restore inside the vendor window and a compliance-scale outage is recoverable from a portable artifact I hold",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13106-1",
+      "description": "The recovery runner supports `wrangler d1 time-travel restore <database> --timestamp=<unix-seconds>` as an operator-invocable command; a restore against a live database rewinds it to the recorded state at the named timestamp and the fresh Worker read reflects the restored state.",
+      "given": "a local or preview D1 database primed with a distinguishable pre-drop row set, a recorded Time Travel bookmark or timestamp before the drop, and a subsequent DROP TABLE or destructive write executed against the database",
+      "when": "the operator invokes `wrangler d1 time-travel restore <database> --timestamp=<pre-drop-timestamp>` and a fresh Worker request reads through the facade",
+      "then": "the facade reads return the pre-drop row set, the destructive write is not present, and the store event log records exactly one `timeTravelRestored` event whose fields carry the target database identifier, the restore timestamp or bookmark, and the ISO-8601 completion timestamp",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13106-2",
+      "description": "A scheduled invocation of `wrangler d1 export <database> --output <artifact-path> --remote` produces a portable `.sql` artifact at the requested path; a fresh D1 database primed by feeding that artifact back through `wrangler d1 execute --file <artifact-path>` boots to the same schema and row set as the source at export time.",
+      "given": "a D1 database with a distinguishable row set and a scheduled export step configured on the project's ops or CI surface",
+      "when": "the export step runs against the source database, and the artifact is loaded into a fresh D1 database via `wrangler d1 execute --file <artifact-path>` (with any BEGIN TRANSACTION or COMMIT statements stripped per the vendor's import guidance) and a fresh Worker request reads through the facade",
+      "then": "the artifact file exists at the requested path, the fresh database reports the same schema shape and row count for every domain table as the source at export completion, and the store event log records one `backupExported` event whose fields carry the source database identifier, the artifact path, and the ISO-8601 completion timestamp",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13106-3",
+      "description": "The recovery runner does not require a Worker code change to invoke either path; the operator invokes both commands from the project's ops or CI surface, and the store event log records the outcome.",
+      "given": "the project's ops or CI surface after either the Time Travel restore in AC-13106-1 or the export in AC-13106-2",
+      "when": "the source tree the Worker deploys from is inspected for diff against the deployed build",
+      "then": "no Worker source change is required to invoke either recovery path (the recovery runner is a project-side ops surface, not a facade verb), and both invocations produced their event log entry without a Worker redeploy",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1404-persistence-data-d1-recovery-runner",
+    "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-13107.json

@@ -0,0 +1,38 @@
+{
+  "usId": "persistence-data-d1-US-13107",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-d1-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Store events carry no secret material",
+  "asA": "operator who ships store event logs to a third-party observability provider",
+  "iWant": "every field on every store event to be limited to store metadata; no domain data, no credential material, no secret values",
+  "soThat": "a log-store breach is not a domain-data breach and the ops team does not have to negotiate a redaction rule with the provider",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-13107-1",
+      "description": "The fields on the facadeReady, migrationsApplied, backupExported, timeTravelRestored, and queryFailed events are restricted to store metadata: event name, ISO-8601 timestamp, binding name, environment name, 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 carries a value read from a domain row.",
+      "given": "the facade is exercised through open, one migrations-applied event on the ops surface, one export, one restore, and one deliberately failing query verb",
+      "when": "every event record captured on the sink is inspected",
+      "then": "every field on every record matches one of the metadata field types listed above, and no field's value equals a value read from any domain table",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-13107-2",
+      "description": "A grep of the facade source, the recovery runner source, and the deploy-gate hook source for domain-table column names and the values of well-known secret columns (session handles, token secrets, private keys, credential material) finds them referenced only inside the narrow CRUD verbs that read or write those columns, never inside event-emission call sites.",
+      "given": "the facade source, the recovery runner source, and the deploy-gate hook source alongside the domain schema definition",
+      "when": "the grep is executed",
+      "then": "matches appear only inside CRUD verb bodies (facade) or inside statements the recovery runner or deploy gate does not read for event-record construction, and never inside onEvent call arguments or event-record construction sites",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1401-persistence-data-d1-facade",
+    "TAC-1404-persistence-data-d1-recovery-runner",
+    "TAC-1403-persistence-data-d1-deploy-gate"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/persistence-data-d1/docs/topics.md

@@ -0,0 +1,59 @@
+# persistence-data-d1 blueprint coordination vocabulary
+
+This file is the persistence-data-d1 half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | persistence-data-d1 contribution | Origin | Composition note |
+|---|---|---|---|
+| `persistenceStore` | ADR-1401-persistence-data-d1-store-model | Reused from the persistence-data-sqlite vocabulary (persistence-data-sqlite contributes a single-file SQLite store on the same topic string). This blueprint contributes a Cloudflare D1 store on the same topic string on purpose. | The one project-wide decision on the primary durable store engine. Composing this blueprint with persistence-data-sqlite (or a future persistence-postgres, persistence-kv, event-sourced blueprint) conflicts here by design; the expected resolution is one project-level ADR that fixes the engine (D1 per this blueprint, or single-file SQLite, or another) and states the tier reasoning |
+| `migrationDiscipline` | ADR-1402-persistence-data-d1-migration-discipline | Reused from the persistence-data-sqlite vocabulary (persistence-data-sqlite contributes a boot-time forward-only runner discipline on the same topic string). This blueprint contributes a wrangler-CLI-owned deploy-pipeline-gated discipline on the same topic string on purpose. | The one project-wide schema-evolution discipline. Composing this blueprint with persistence-data-sqlite (whose discipline runs at boot inside the process) or a future event-sourced-projection or bidirectional-migration blueprint conflicts here by design; the expected resolution is one project-level ADR that fixes the discipline for the project |
+
+The persistence-data-d1 blueprint claims two global topics. Every other contribution is scope-local (the three operational ADRs, ADR-1403 through ADR-1405, do not contribute global topics; a composing blueprint that holds an opinion on event-secrecy, the module-boundary posture, or the recovery model authors its own project-level ADR if it wants to override).
+
+Note on the delineation from the application-api-rest blueprint's `logging` topic: `logging` (owned by application-api-rest ADR-304) governs the wire-log shape of the HTTP tier. This blueprint's ADR-1403 governs the STORE-EVENT log shape (facadeReady, migrationsApplied, backupExported, timeTravelRestored, queryFailed). The two log surfaces may share a shipper but do not share a topic. A blueprint that contributes a unified log discipline across all tiers would author its own scope:global ADR on `logging` and expect to conflict with the REST blueprint there, not here.
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-pipeline, observability-essentials, security-secrets-management, security-auth-clerk, and email-smtp-resend vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`store`, `dataStore`, `db`, `dbEngine`, `d1Store`, `edgeStore` are all wrong when `persistenceStore` already exists; `schemaMigrations`, `dbMigrations`, `wranglerMigrations`, `migrations` are all wrong when `migrationDiscipline` already exists).
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| ci-pipeline | 6101-6899 | 7xx | shipped v1.0.0 | `ciGates`, `strictCoverageGate` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 13101-13107 sit at the LOW end of the 13101-13899 band on purpose. A project-side story that mechanically derives from a persistence-data-d1 REQ id into the number `13107` would collide against persistence-data-d1-US-13107 in this package; the band leaves headroom at the HIGH end (US 13181-13899) so a project's own stories anchored to persistence-data-d1 REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+ADR and TAC suffixes for this blueprint use the 1401-1499 block, continuing the four-digit widening opened by security-auth-clerk at 1001-1099 (security-auth-clerk topics.md notes that the three-digit space fills at 9xx and forthcoming blueprints continue widening at 1101, 1201, 1301, and now 1401). Sibling round-2 blueprints (deploy-cloudflare-workers at 1301-1399, observability-probe-endpoints at 1501-1599) allocate on the same widening.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `persistenceStore` exactly as spelled here (matching persistence-data-sqlite's contribution on the same topic string) when your blueprint holds an opinion on the project's primary durable store engine; contribute your own scope:global ADR on that string and let composition surface the pairing. A vendor-committed persistence blueprint on a different engine (Postgres-hosted, KV-oriented, event-sourced) will conflict here by design; the operator resolves at apply.
+- Reuse `migrationDiscipline` exactly as spelled here (matching persistence-data-sqlite's contribution on the same topic string) when your blueprint holds an opinion on schema evolution. A blueprint that contributes a boot-time application-side runner discipline (persistence-data-sqlite), an out-of-band vendor-CLI discipline (this blueprint), or an event-sourced projection discipline (future) conflicts here by design.
+- Event-secrecy (ADR-1403), module boundary (ADR-1404), and recovery model (ADR-1405) are scope-local. A composing blueprint that holds an opinion on any of them authors its own project-level ADR; none of them are minted as globals because the space of legitimate variations is smaller than the space of legitimate `persistenceStore` or `migrationDiscipline` variations.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `messageSerialisation` and `deliverySemantics` (a message-consumer blueprint's natural globals), `caching` (unclaimed by every shipped blueprint), `metricsExport` and `tracingProtocol` (natural globals for a metrics or tracing blueprint), `deploymentTarget` (expected to land with the round-2 `deploy-cloudflare-workers` blueprint). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-1401 on `persistenceStore` and ADR-1402 on `migrationDiscipline` are a Cloudflare-D1-committed vendor sibling to persistence-data-sqlite's ADR-601 and ADR-602 on the same two topic strings. Applying both on one project raises two `globalAdrTopic` conflicts the operator resolves via one of the four documented resolutions per topic (adopt one, keep the existing one, author a project-level supersede ADR, or `--resolve <topic>=project:<ADR-id>` on the add). The pairing precedent is `application-spa` + `application-api-rest` on `errorEnvelope` and `authModel` (two globals conflict at once because the two blueprints jointly cover both halves of a shared decision), and `security-auth-clerk` + `security-auth-magic-link` on `authModel` (two vendor-committed siblings conflict on one global because they hold different answers on the same decision area). This blueprint combines both precedents: two vendor-committed siblings on two shared globals at once. The operator's resolution is a project-level ADR per topic that fixes the engine and the discipline together; a project that mixes D1 for one tier and single-file SQLite for another is a supersede-and-forge shape the mechanism does not encourage.
+
+## Rename awareness
+
+Cross-references in this blueprint's prose use the target-state slugs from the ratified renames pass: `persistence-data-sqlite` (for the shipped former `persistence` blueprint), `application-spa`, `application-api-rest`, `security-auth-magic-link`, `observability-essentials`. The rename pass merged before this blueprint shipped; every slug named above resolves against a currently-shipped blueprint or a currently-reserved round-2 sibling.