rcf-lite 0.12.0 → 0.14.0

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, delivery-ci-workflows, 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` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| 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.

package/blueprints/persistence-data-d1/guide/persistence-data-d1.md

@@ -0,0 +1,77 @@
+# Persistence data D1 blueprint guide
+
+## What it is
+
+A default durable-store floor for small greenfield rcf-lite projects deployed on Cloudflare Workers. The blueprint contributes the WHAT of a Workers-tier persistence pattern: how the D1 binding is read, how the store facade wraps it, how schema evolves through wrangler-owned numbered migrations, how the deploy pipeline gates the Worker on the apply succeeding first, how the prepared-statement discipline closes the SQL-injection surface by construction, how multi-statement atomicity is expressed through batch, how the store event log looks, and how recovery is available on two paths (Time Travel in the vendor and portable export off the vendor). The default engine is one Cloudflare D1 database; other engines behind the same facade contract on supersede.
+
+Concretely, the blueprint ships seven requirements, seven user stories (twenty acceptance criteria), four architecture components, and five architecture decision records. Two ADRs are `scope: global` on the topics `persistenceStore` (the engine choice) and `migrationDiscipline` (the wrangler-owned deploy-gated posture); the other three are scope-local operational ADRs (event secrecy, module boundary, recovery model) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a domain schema. The tables the project's own entities live in are project-authored, on top of the migration directory the project maintains. The blueprint governs the store facade contract and the migration discipline; the domain shape is the project's own responsibility.
+
+Not an ORM. There is no query builder, no active-record layer, no framework-shaped abstraction between the facade's named verbs and the D1 prepared-statement surface. Projects that want an ORM (Drizzle, Kysely) wire it inside the facade's implementation and preserve the outward verb surface; the prepared-statement discipline (static SQL literals only) survives the ORM choice because most ORMs emit static SQL from typed queries at build time.
+
+Not a Worker deploy blueprint. The deploy-gate TAC assumes a `wrangler deploy` step exists on the CI surface; a companion `deploy-cloudflare-workers` blueprint (round-2 sibling, unshipped at v1.0.0) is the natural owner of that surface. Until it ships, projects wire their own `wrangler deploy` step and the deploy-gate contract binds against it.
+
+Not a secrets-management blueprint. The CI credential that runs `wrangler d1 migrations apply` and `wrangler deploy` (the `CLOUDFLARE_API_TOKEN`, or the OAuth-scoped credential the vendor issues) is a secret whose storage and rotation posture the `security-secrets-management` blueprint governs. This blueprint references the credential by role, not by name or storage path.
+
+Not a CI-pipeline blueprint. The deploy-gate TAC contributes the requirement that `wrangler d1 migrations apply` orders strictly before `wrangler deploy` and the deploy job refuses on apply failure; the CI file that implements that ordering is the concern of the `delivery-ci-workflows` blueprint or the project's own CI-authoring practice.
+
+Not a logical-dump story beyond the vendor's export. Backups are `wrangler d1 export` artifacts; cross-engine migration and portable dumps beyond D1's own `.sql` export are out of scope. Projects that need a schema-agnostic dump layer a project-authored dump runner beside the file-level runner.
+
+Not a connection pool. The D1 binding is request-scoped; the facade holds no long-lived engine handle. Projects that need connection pooling have picked the wrong engine tier; supersede ADR-1401.
+
+Not a replication or failover story. D1's read-replica surface (accessed via `withSession`) targets read scaling, not failover. Projects that need failover semantics supersede ADR-1401 with an alternate engine that provides them.
+
+## When to reach for it
+
+Reach for the persistence-data-d1 blueprint when:
+
+- The project is a small greenfield rcf-lite deployment on Cloudflare Workers (one deployable, one small team, no ops team standing by, the project's deploy target IS the Workers edge substrate).
+- The domain has a natural relational shape (bounded set of entities with well-defined relationships) that SQL expresses cleanly.
+- Zero-infrastructure persistence at the vendor tier is a feature (no database server to run, no connection pool to size, no network hop outside the vendor's edge substrate on the request path).
+- The steady-state working set fits inside D1's currently published per-database ceiling on the project's plan tier (a currently-published upper bound of 10 GB per D1 database on the Paid plan; 500 MB on the Free plan) and the per-Worker-invocation query count fits inside the plan's limit (currently 1000 on Paid, 50 on Free).
+- The recovery model that fits is 'rewind in place within the vendor recovery window, or reload from a portable off-vendor export artifact for anything longer'; Time Travel is the primary fast path.
+- The migration story that fits is 'wrangler CLI applies numbered `.sql` files, gated by the deploy pipeline, no boot-time runner'; the project accepts that a schema-behind-the-code state is closed at CI time, not at request time.
+
+## When it does not fit
+
+Do not reach for the persistence-data-d1 blueprint when:
+
+- The deploy target is not Cloudflare Workers. D1 is only accessible through the Workers runtime; a project deployed on a Node server, a container platform, or a non-Workers serverless surface picks a different engine. The sibling persistence-data-sqlite blueprint (single-file SQLite for a Node-tier deployment) is the natural pair; a project that needs Postgres supersedes ADR-1401 with a project-level ADR.
+- Multi-writer scale across regions, hot standby replication, or true failover are project requirements. D1's read-replica surface is a read-scaling primitive, not a failover primitive; a project that needs failover supersedes ADR-1401 with an alternate engine that provides them.
+- The working set is genuinely too large for the currently published per-database D1 ceiling on the project's plan tier. At that scale a project's options are to shard across multiple D1 databases (a shape the blueprint does not prescribe), or to supersede ADR-1401 with a Postgres or equivalent engine that lifts the ceiling.
+- The domain shape is genuinely non-relational (opaque blob storage, event streams, time-series with a fixed retention model). A different blueprint (a KV-store blueprint, an event-sourced blueprint, a time-series blueprint) owns those shapes; supersede with a project-level ADR and skip this blueprint.
+- The project has a hard requirement for a boot-time migration runner discipline (a service that reads the schema version at start and applies pending migrations before serving). Reach for the persistence-data-sqlite blueprint instead; its `migrationDiscipline` topic is exactly that shape. The two blueprints deliberately conflict on `migrationDiscipline` on this exact difference.
+- The project has a hard requirement to run the same store engine locally in the developer's process (a small tool that ships with an embedded store, a CLI that reads from the store without a Workers runtime). D1 is only fully realised inside a Workers runtime; `wrangler dev` provides a local D1 for development, but a project whose primary consumer is not a Worker picks a different engine.
+
+The blueprint round-2 ratification scoped persistence-data-d1 as the vendor sibling of persistence-data-sqlite on the shelf. The two blueprints ship the same two global topics on purpose (`persistenceStore` and `migrationDiscipline`) with different vendor answers. Composing both on one project surfaces the pairing as two `globalAdrTopic` conflicts the operator resolves; the expected shape is one project-level ADR per topic that fixes the tier reasoning. A project that mixes D1 for one deployable and single-file SQLite for another deployable does so through separate project-level ADR rulings, not through mixing both blueprints on one project.
+
+## What a good outcome looks like
+
+A project applies the persistence-data-d1 blueprint on a fresh tree, wires its own domain migration files into the wrangler-configured directory (starting at file number 0001), realises the four TACs in project-authored FBSes, wires the CI job with `wrangler d1 migrations apply` ordered strictly before `wrangler deploy`, and lands on a deployed Worker where:
+
+- The first Worker request per isolate imports the facade, reads the D1 binding once from `env`, and serves the request; the facadeReady event fires exactly once per isolate with the binding and environment names.
+- A schema change ships as a new numbered `.sql` file under the wrangler-configured directory; the next deploy's CI job applies the file to the target D1 database, the deploy proceeds, the migrationsApplied event fires with the applied filename, and consumer code reads through the facade at the new schema shape.
+- An accidental drop is a one-command Time Travel restore inside the plan's recovery window; the timeTravelRestored event fires with the restore timestamp; a fresh Worker request reads the pre-drop state.
+- A scheduled export runs on a cron against the live database; the backupExported event fires on the sink with the artifact path and the completion timestamp; a fresh D1 database primed from that artifact reads the rows committed at or before the export completion timestamp.
+- A rollback to an older Worker build against a database whose migration set is ahead of the older build's expectations serves cleanly, because the older Worker's SQL literals target a schema shape that is a prefix of the current schema; the vendor's SQLite semantics let the older SELECTs and INSERTs ignore columns added in later migrations.
+- The auth event log, the wire-request log, and every other domain log surface holds no store-lifecycle records; the store's event log holds no domain-row values, and a queryFailed event carries the domain-verb name plus the D1 error code, never the failed statement's parameter values.
+
+## Operator decisions that remain open after apply
+
+- Engine choice (D1 default, single-file SQLite for non-Workers deployables, or Postgres or KV-store by superseding ADR-1401 with a project-level ADR). Blueprint owns the facade contract on both sides of the boundary; project owns the engine.
+- Migration file naming pattern (wrangler default numbered form, or an ORM-compatible pattern set on `migrations_pattern`). Blueprint owns the shape; project owns the pattern at the ORM alignment cost the project accepts.
+- Binding name and database identifier (the wrangler config values). Blueprint owns the read shape (one binding, one facade); project owns the deployed values and how they are supplied per environment.
+- Domain schema (every table the domain requires). Blueprint owns the migration discipline; project owns the tables.
+- Export schedule and destination (cron cadence, artifact path template, retention, R2 bucket or repository asset choice). Blueprint owns the export runner and its event; project owns when and where.
+- Restore drill cadence (a backup you have not restored is a hope, not a backup). Blueprint owns the artifact shape and the Time Travel restore command; project owns proving both work.
+- Log sink implementation (where facadeReady, migrationsApplied, backupExported, timeTravelRestored, queryFailed events go). Blueprint owns the event shape and the metadata-only discipline; project owns the shipper.
+- CI pipeline choice (GitHub Actions, GitLab CI, whatever). Blueprint owns the ordering contract on the migrations-apply-before-deploy sequence; project owns the CI tool that implements it.
+- Facade verb catalogue (the named CRUD verbs the domain needs). Blueprint owns the boundary discipline (named verbs, prepared statements, batch atomicity, no raw-query passthrough); project owns the verbs.
+- Secrets storage for the CI credential (`CLOUDFLARE_API_TOKEN` and any deploy-specific secret). Blueprint references the credential by role; the security-secrets-management blueprint owns storage and rotation.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every deploy pipeline pays the migrations-apply latency (one wrangler invocation, one round trip to the D1 API) before the Worker deploy runs. Every facade verb is a project-authored function; the boundary discipline means new query shapes are a two-file edit (facade plus consumer) instead of a scattered raw SQL fragment. Every schema change is a numbered `.sql` file the project must not edit after shipping (a shipped migration is a fact of production; a correction is a new numbered file, applied on top). The deploy-gate ordering property makes a failed apply a red CI job rather than a customer-visible 5xx; that safety comes at the cost of a slower deploy loop on any migration change (the apply runs before the deploy; on rollback the operator ships the older code with a migration set that is a prefix, and the older SQL literals ignore added columns per SQLite semantics). Time Travel is the vendor's built-in fast path but bounded by the plan window (currently 30 days on Paid, 7 days on Free); a project whose compliance model demands longer retention runs the export step on a schedule and holds the artifacts off-vendor. 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. The store's event log is deliberately minimal; a project that needs richer per-operation events (row-level audit trail, hot-path timing) authors those on top of the facade's verbs, not inside the store event sink. The prepared-statement discipline closes the SQL-injection surface by construction, at the cost that consumers who want to hand-roll a new query shape have to add a named verb to the facade instead of reaching into the binding directly.

package/blueprints/persistence-data-sqlite/README.md

@@ -0,0 +1,50 @@
+# Persistence blueprint (v1.0.0)
+
+The fourth content blueprint on the rcf-build-lite blueprint mechanism (design brief v2, ratified; Phase 4 of the blueprint programme). Scope: single-file SQLite as the default durable store with a forward-only numbered migration catalog applied atomically at open, a store facade that is the sole boundary between the domain and the engine, a structured lifecycle event log, and a downtime-free file-level backup runner. Targeted at small greenfield rcf-lite projects. Postgres is a documented future variant behind the same facade; the v1.0.0 blueprint ships SQLite only.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/persistence-data-sqlite
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry; `rcf define blueprint remove persistence-data-sqlite` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, and the 31 contributions with scope/topic on the two global ADRs |
+| Doc set | `contributions/` | 11 REQs, 11 USs (25 ACs), 4 TACs, 5 ADRs, all schema-valid against rcf-schemas 0.4.5 and namespaced (`persistence-data-sqlite-REQ-001` prefix family; `ADR-601-persistence-data-sqlite-store-model` suffix family) |
+| Migration shape sample | `assets/schema-samples/migration-shape.md` | The exact shape of a migration catalog entry (version, description, statements) with a worked example |
+| Catalog layout sample | `assets/schema-samples/catalog-file-layout.md` | Two layouts the catalog module can take (one file, one file per migration) with a pick guide |
+| SQLite backup procedure | `assets/backup-procedures/sqlite-file-copy.md` | The downtime-free file-copy procedure under WAL, with the online-backup and checkpoint-then-copy paths |
+| WAL checkpoint note | `assets/backup-procedures/hot-checkpoint-note.md` | Why a checkpoint before a bare cp works, and when the online-backup API is the safer path |
+| Guide | `guide/persistence-data-sqlite.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signal for the future Postgres variant |
+| Coordination vocabulary | `docs/topics.md` | The two global-topic strings this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, delivery-ci-workflows, observability-essentials) |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the store facade contract, the migration runner contract, the migration catalog shape, the backup runner contract, the event log discipline); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: the domain schema (the tables the project's own entities live in are project-authored, not blueprint-authored; the blueprint governs the store facade and the migration discipline, not the domain shape); ORMs, query builders, and any framework-shaped abstraction above the named CRUD verbs (the facade is a project-authored surface; how it internally implements its verbs is not blueprint-owned); a Postgres engine TAC (deferred; see ADR-601's alternatives and the guide 'when it does not fit'); logical schema-aware dumps (out of scope; see ADR-605's alternatives); connection pooling (an implementation detail of the facade when a project selects an engine that benefits from it, not a blueprint contribution).
+
+## The two global decisions
+
+ADR-601-persistence-data-sqlite-store-model ships `scope: global` on topic `persistenceStore`. This is the project's primary durable store engine choice: single SQLite file, WAL mode, one entry point through the facade. A composing blueprint that holds a different engine opinion (a Postgres-first blueprint, a KV-store blueprint, an event-sourced blueprint) conflicts here by design and expects a project-level ADR resolution.
+
+ADR-602-persistence-data-sqlite-migration-discipline ships `scope: global` on topic `migrationDiscipline`. This is the project's schema-evolution posture: forward-only numbered migrations, atomic per-migration, refuse-newer-than-build at open. A composing blueprint that holds an opinion on migration discipline (event-sourced projections, bidirectional migrations, tenant-per-schema) conflicts here by design.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, the delineation from the application-api-rest blueprint's `logging` topic (which governs the wire-log shape, not the store-event log shape), and the AC id band allocation (persistence-data-sqlite owns 5101-5899).
+
+## Quality bar
+
+Single durable store opened via one boot-time entry point that runs migrations before returning; numbered forward-only migration catalog committed in-tree with a monotonic version integer per entry; refuse-newer-than-build at open with a stable error code naming both versions and no writes on that path; atomic per-migration transactions covering statements and the version bookkeeping row together; kill-9 tolerant durability posture (WAL plus synchronous commit floor under SQLite; engine-native equivalent otherwise) set at open by the facade; structured event log at four defined moments (opened, migrated, backupCheckpoint, closed) with metadata-only fields; store facade as the sole importer of the engine binding, exposing named domain verbs with no raw-query passthrough on the public surface; downtime-free file-level backup emitting a checkpoint event with artifact path and completion timestamp; migration-failed error naming the failing version and preserving the previous version on disk; no domain-row values on the event sink; idempotent no-op open when the store is already at target version. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+None at v1.0.0. Every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable in the deployed application (event-log record inspection, store-artifact snapshot comparison, engine-native introspection queries through the facade, source-tree import-graph queries for the boundary properties). The mechanism-reach principle from the authoring standard section 7 is satisfied at ship: a project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. The one operational responsibility a project must own on its own is the engine choice itself, if it supersedes ADR-601 with a project-level ADR; that responsibility is stated as an ADR alternative (see ADR-601 and the guide 'when it does not fit'), not as a smuggled runtime probe.

package/blueprints/persistence-data-sqlite/assets/backup-procedures/hot-checkpoint-note.md

@@ -0,0 +1,22 @@
+# Why the checkpoint-then-copy path works, and when to prefer online-backup
+
+## The setup
+
+Under SQLite in WAL mode (ADR-601's default posture), committed writes land in a write-ahead log file (`<db>-wal`) and are periodically checkpointed into the main database file. Readers see committed writes across both the main file and the WAL; a bare `cp` of the main file captures only the pre-checkpoint state and can miss recent committed writes.
+
+## Why the checkpoint fixes it
+
+`PRAGMA wal_checkpoint(TRUNCATE)` forces every committed WAL page into the main file and truncates the WAL. After the checkpoint, the main file alone holds every committed write as of the checkpoint moment; a subsequent `cp` captures a consistent snapshot as of that moment. Writers on the source connection stay available: writes committed after the checkpoint land in a new WAL segment and are outside the artifact (which is the intended semantics: the artifact is a snapshot as of the checkpoint, not as of the `cp` completion).
+
+## Why online-backup is still preferred
+
+Two properties online-backup gives that checkpoint-then-copy does not:
+
+- **Streaming rather than dual-storage.** The online-backup API streams pages to the destination without materialising the main file at a specific moment; for a large store, checkpointing everything into the main file at once is an operator-visible I/O spike.
+- **No writer blocking on the checkpoint call.** `PRAGMA wal_checkpoint(TRUNCATE)` waits for readers to release the WAL; on a busy store this can pause the writer for the duration of the wait. Online-backup does not have this pause.
+
+For rcf-lite-tier stores (small working sets, one host, human-scale write rate) the difference is not operator-visible and either path is defensible. Bindings that expose online-backup cleanly (node:sqlite, better-sqlite3) should use it; bindings that don't (older builds, unusual environments) use checkpoint-then-copy without apology.
+
+## What breaks if you skip the checkpoint
+
+A bare `cp` of a WAL-mode SQLite file without checkpointing produces an artifact that is missing every committed write in the WAL at copy time. On restore the missing writes are gone. This is the failure mode ADR-605's alternatives paragraph refers to: the operator sees a backup file that opens cleanly and reports the right schema version but is missing an unpredictable tail of recent writes. The runner never takes this path; the checkpoint-then-copy path in `sqlite-file-copy.md` is the fallback the runner uses when online-backup is not available.

package/blueprints/persistence-data-sqlite/assets/backup-procedures/sqlite-file-copy.md

@@ -0,0 +1,70 @@
+# SQLite backup procedure (default engine, ADR-601 + ADR-605)
+
+The backup runner (TAC-604) produces a self-contained artifact without downtime. Under SQLite in WAL mode (the default engine), two paths satisfy the AC-5108-1 downtime-free property; pick the one the project's SQLite binding supports cleanly.
+
+## Path 1: online-backup API (preferred)
+
+The SQLite online-backup API opens a second connection in backup mode and streams pages from the source to the destination file. Writers on the source connection stay available for the full duration; the copy is transactionally consistent at the point the API completes.
+
+```javascript
+// Inside TAC-604's backup implementation, using the node:sqlite binding.
+import { DatabaseSync } from 'node:sqlite';
+
+export async function backup(sourceDb, outputPath) {
+  const dest = new DatabaseSync(outputPath);
+  try {
+    // Bindings vary in shape; the essence is 'open a backup handle from
+    // source to dest and step it to completion'. node:sqlite exposes
+    // sourceDb.backup(dest); some bindings require .step(-1) loops.
+    await sourceDb.backup(dest);
+    return {
+      artifactPath: outputPath,
+      completedAt: new Date().toISOString(),
+    };
+  } finally {
+    dest.close();
+  }
+}
+```
+
+Emit the `backupCheckpoint` event on the store's event sink at completion (AC-5108-3), carrying `{ event: 'backupCheckpoint', ts, artifactPath, completedAt }`.
+
+## Path 2: checkpoint-then-copy
+
+For bindings that do not expose the online-backup API, a WAL checkpoint followed by a filesystem-level copy of the main file is a defensible fallback. The checkpoint flushes all committed WAL pages into the main file; the copy captures every committed write as of the checkpoint moment. Writers on the source connection stay available; concurrent writes after the checkpoint land in a new WAL segment and are not in the artifact (which is the intended semantics: the artifact is a snapshot as-of the checkpoint).
+
+```javascript
+// Inside TAC-604's backup implementation.
+import { copyFile } from 'node:fs/promises';
+
+export async function backup(sourceDb, sourcePath, outputPath) {
+  sourceDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+  await copyFile(sourcePath, outputPath);
+  return {
+    artifactPath: outputPath,
+    completedAt: new Date().toISOString(),
+  };
+}
+```
+
+Emit the `backupCheckpoint` event as above.
+
+## Recovery
+
+Recovery is opening the artifact through the store facade against a compatible build:
+
+```
+cp backup.sqlite /path/to/deployed/store.sqlite
+# restart the process; facade openStore({ path: '/path/to/deployed/store.sqlite' })
+# runs, opened event fires, schemaVersion matches the artifact's version
+```
+
+The refuse-newer property (AC-5103-1) applies here: recovering a newer-than-build artifact under an older build fails at boot; the fix is to recover under a build at or ahead of the artifact's schema version.
+
+## What this procedure is not
+
+Not a logical dump. The artifact is a SQLite file, not a portable SQL script; a project that needs cross-engine restore layers a project-authored dump runner beside this one (see ADR-605's alternatives).
+
+Not a replication story. Cross-region replication is engine-native (SQLite Litestream or the alternate engine ADR-601 is superseded to); the backup runner produces one artifact per invocation and does not orchestrate shipping.
+
+Not a retention manager. The artifact filename and the delete-old-artifacts cadence are project concerns; the runner writes the artifact and emits the checkpoint event.

package/blueprints/persistence-data-sqlite/assets/schema-samples/catalog-file-layout.md

@@ -0,0 +1,73 @@
+# Migration catalog layout
+
+The catalog exports `MIGRATIONS` (the ordered array) and `CURRENT_VERSION` (the max version integer). Two layouts satisfy TAC-603; pick one at project start and stay with it.
+
+## Layout A: one file (recommended up to ~30 entries)
+
+```
+src/store/
+  schema.js          // exports MIGRATIONS array and CURRENT_VERSION
+  store.js           // the facade (TAC-601)
+  migrationRunner.js // the runner (TAC-602)
+```
+
+`src/store/schema.js`:
+
+```javascript
+export const MIGRATIONS = [
+  { version: 1, description: '...', statements: ['...'] },
+  { version: 2, description: '...', statements: ['...'] },
+  // ... more entries appended over the project's history
+];
+
+export const CURRENT_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
+```
+
+Pros: every version is visible on one screen; grep for a table name lands on the migration that created and every migration that altered it; PR review of a schema change is one file.
+
+Cons: file size grows with history; large teams may see merge conflicts on the array-tail append.
+
+## Layout B: one file per migration (recommended past ~30 entries)
+
+```
+src/store/
+  schema.js          // aggregates the migrations directory into MIGRATIONS + CURRENT_VERSION
+  migrations/
+    001-initial-schema.js
+    002-soft-delete-column.js
+    003-boot-markers.js
+    004-notifier-schema.js
+    // ... one file per migration
+  store.js
+  migrationRunner.js
+```
+
+Each migration file:
+
+```javascript
+// src/store/migrations/002-soft-delete-column.js
+export default {
+  version: 2,
+  description: 'soft-delete: entityA.removedAt column',
+  statements: [`ALTER TABLE entityA ADD COLUMN removedAt TEXT`],
+};
+```
+
+`src/store/schema.js` aggregates:
+
+```javascript
+import migration001 from './migrations/001-initial-schema.js';
+import migration002 from './migrations/002-soft-delete-column.js';
+// ... one import per migration file
+
+export const MIGRATIONS = [migration001, migration002, /* ... */];
+export const CURRENT_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
+```
+
+Pros: one migration is one file; PR review is a fresh file, not an array edit; merge conflicts are structurally rare (contributors touch different filenames).
+
+Cons: two-file edit per new migration; grep for a table name lands on multiple files; version integers appear in filenames and in the file body and must agree.
+
+## Migration between layouts
+
+Layout A converts to Layout B by extracting each array entry into a numbered file and rewriting `schema.js` to aggregate. The exported names (`MIGRATIONS`, `CURRENT_VERSION`) stay identical, so the runner and the facade do not change. Do the conversion in a single commit with no logical schema change.