rcf-lite 0.11.0 → 0.13.0

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 `ci-pipeline` 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, ci-pipeline, 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.

package/blueprints/persistence-data-sqlite/assets/schema-samples/migration-shape.md

@@ -0,0 +1,76 @@
+# Migration entry shape
+
+Every entry in the migration catalog (TAC-603) has this exact shape:
+
+```
+{
+  version: <integer>,          // monotonic, starts at 1, no gaps
+  description: <string>,        // human-readable; ships in the migration-failed error
+  statements: [<string>, ...]   // one or more engine-native DDL/data statements
+}
+```
+
+The `statements` list executes inside one transaction opened by the migration runner (TAC-602); the version bookkeeping row inserts inside the same transaction. On any failure, the transaction rolls back and the on-disk version reflects the last successfully committed migration.
+
+## Worked example
+
+A four-migration catalog starting with an eleven-table initial schema, followed by a soft-delete column, a boot marker, and a notifier-schema expansion. Statements are SQLite dialect at the default engine (ADR-601); the shape is identical under any alternate engine ADR-601 is superseded to.
+
+```javascript
+export const MIGRATIONS = [
+  {
+    version: 1,
+    description: 'initial schema, eleven entities',
+    statements: [
+      `CREATE TABLE schemaVersion (
+        version   INTEGER PRIMARY KEY,
+        appliedAt TEXT    NOT NULL
+      )`,
+      `CREATE TABLE entityA (
+        id        TEXT PRIMARY KEY,
+        name      TEXT NOT NULL UNIQUE,
+        createdAt TEXT NOT NULL,
+        updatedAt TEXT NOT NULL
+      )`,
+      // ... nine more CREATE TABLE statements per the initial schema
+    ],
+  },
+  {
+    version: 2,
+    description: 'soft-delete: entityA.removedAt column for file-lane removal without eager history loss',
+    statements: [
+      `ALTER TABLE entityA ADD COLUMN removedAt TEXT`,
+    ],
+  },
+  {
+    version: 3,
+    description: 'boot markers: audit trail of process starts for honest-gap accounting',
+    statements: [
+      `CREATE TABLE bootMarker (
+        bootAt TEXT PRIMARY KEY
+      )`,
+    ],
+  },
+  {
+    version: 4,
+    description: 'notifier: per-entity channel routes and pending-delivery resume queue',
+    statements: [
+      `CREATE TABLE entityChannelRoute (
+        entityId  TEXT NOT NULL,
+        channelId TEXT NOT NULL,
+        PRIMARY KEY (entityId, channelId)
+      )`,
+      `ALTER TABLE channel ADD COLUMN isDefault INTEGER NOT NULL DEFAULT 0`,
+    ],
+  },
+];
+
+export const CURRENT_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
+```
+
+## Rules a project must not break
+
+- **Version integers are monotonic and start at 1 with no gaps.** A missing version between shipped entries breaks the ordering guarantee the runner relies on. Two contributors landing overlapping versions is a merge conflict, not a runtime bug.
+- **A shipped migration is never edited.** Adding a statement to an already-shipped entry is a silent schema divergence between production stores at different open cycles. Fixes ship as new numbered migrations.
+- **The statements list is engine-native.** Dialect matches the engine selected in ADR-601 (or its superseding project ADR). Statements are strings, not query builders; the runner does not interpret them.
+- **The bookkeeping insert is the runner's responsibility, not the migration's.** A migration whose statements include an `INSERT INTO schemaVersion` corrupts the runner's ordering; the runner already handles that insert inside the same transaction.

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

@@ -0,0 +1,50 @@
+{
+  "slug": "persistence-data-sqlite",
+  "version": "1.0.0",
+  "category": "persistence",
+  "contributions": [
+    { "id": "persistence-data-sqlite-REQ-001", "kind": "req", "path": "requirements/persistence-data-sqlite-req-001.json" },
+    { "id": "persistence-data-sqlite-REQ-002", "kind": "req", "path": "requirements/persistence-data-sqlite-req-002.json" },
+    { "id": "persistence-data-sqlite-REQ-003", "kind": "req", "path": "requirements/persistence-data-sqlite-req-003.json" },
+    { "id": "persistence-data-sqlite-REQ-004", "kind": "req", "path": "requirements/persistence-data-sqlite-req-004.json" },
+    { "id": "persistence-data-sqlite-REQ-005", "kind": "req", "path": "requirements/persistence-data-sqlite-req-005.json" },
+    { "id": "persistence-data-sqlite-REQ-006", "kind": "req", "path": "requirements/persistence-data-sqlite-req-006.json" },
+    { "id": "persistence-data-sqlite-REQ-007", "kind": "req", "path": "requirements/persistence-data-sqlite-req-007.json" },
+    { "id": "persistence-data-sqlite-REQ-008", "kind": "req", "path": "requirements/persistence-data-sqlite-req-008.json" },
+    { "id": "persistence-data-sqlite-REQ-009", "kind": "req", "path": "requirements/persistence-data-sqlite-req-009.json" },
+    { "id": "persistence-data-sqlite-REQ-010", "kind": "req", "path": "requirements/persistence-data-sqlite-req-010.json" },
+    { "id": "persistence-data-sqlite-REQ-011", "kind": "req", "path": "requirements/persistence-data-sqlite-req-011.json" },
+    { "id": "persistence-data-sqlite-US-5101", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5101.json" },
+    { "id": "persistence-data-sqlite-US-5102", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5102.json" },
+    { "id": "persistence-data-sqlite-US-5103", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5103.json" },
+    { "id": "persistence-data-sqlite-US-5104", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5104.json" },
+    { "id": "persistence-data-sqlite-US-5105", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5105.json" },
+    { "id": "persistence-data-sqlite-US-5106", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5106.json" },
+    { "id": "persistence-data-sqlite-US-5107", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5107.json" },
+    { "id": "persistence-data-sqlite-US-5108", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5108.json" },
+    { "id": "persistence-data-sqlite-US-5109", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5109.json" },
+    { "id": "persistence-data-sqlite-US-5110", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5110.json" },
+    { "id": "persistence-data-sqlite-US-5111", "kind": "us", "path": "user-stories/persistence-data-sqlite-us-5111.json" },
+    { "id": "TAC-601-persistence-data-sqlite-store", "kind": "tac", "path": "tacs/tac-601-persistence-data-sqlite-store.json" },
+    { "id": "TAC-602-persistence-data-sqlite-migration-runner", "kind": "tac", "path": "tacs/tac-602-persistence-data-sqlite-migration-runner.json" },
+    { "id": "TAC-603-persistence-data-sqlite-migration-catalog", "kind": "tac", "path": "tacs/tac-603-persistence-data-sqlite-migration-catalog.json" },
+    { "id": "TAC-604-persistence-data-sqlite-backup-runner", "kind": "tac", "path": "tacs/tac-604-persistence-data-sqlite-backup-runner.json" },
+    {
+      "id": "ADR-601-persistence-data-sqlite-store-model",
+      "kind": "adr",
+      "path": "adrs/adr-601-persistence-data-sqlite-store-model.json",
+      "scope": "global",
+      "topic": "persistenceStore"
+    },
+    {
+      "id": "ADR-602-persistence-data-sqlite-migration-discipline",
+      "kind": "adr",
+      "path": "adrs/adr-602-persistence-data-sqlite-migration-discipline.json",
+      "scope": "global",
+      "topic": "migrationDiscipline"
+    },
+    { "id": "ADR-603-persistence-data-sqlite-event-secrecy", "kind": "adr", "path": "adrs/adr-603-persistence-data-sqlite-event-secrecy.json" },
+    { "id": "ADR-604-persistence-data-sqlite-store-boundary", "kind": "adr", "path": "adrs/adr-604-persistence-data-sqlite-store-boundary.json" },
+    { "id": "ADR-605-persistence-data-sqlite-backup-model", "kind": "adr", "path": "adrs/adr-605-persistence-data-sqlite-backup-model.json" }
+  ]
+}

package/blueprints/persistence-data-sqlite/contributions/adrs/adr-601-persistence-data-sqlite-store-model.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-601-persistence-data-sqlite-store-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Single SQLite file with WAL-mode crash safety as the project's default durable store; Postgres as a documented future variant",
+  "context": "A project has one primary durable store: the substrate every domain entity lives in and every domain query resolves against. Choice of engine sets the crash-safety story, the backup story, the deploy story, the ops footprint, and the scale ceiling. The rcf-lite tier this blueprint targets is small single-deployable greenfield: one team, one host or one small container fleet, no ops team standing by. That tier has a natural answer.",
+  "decision": "The default primary durable store is a single SQLite file opened in WAL journal mode with synchronous=NORMAL, foreign_keys=ON, accessed through the store facade (TAC-601) which is the only module that imports the SQLite binding. One file per deployed instance; the file path is a configuration input to the open entry point; backups are file-level snapshots taken through the backup runner (TAC-604) without downtime; migrations are numbered forward-only entries in the in-tree catalog (TAC-603) applied at open by the runner (TAC-602). Postgres is a documented future variant behind the same facade: a project that outgrows SQLite supersedes this ADR with a project-level ADR selecting the alternate engine, replaces the facade's engine binding, and rewrites the migration catalog into the alternate dialect. The blueprint mechanism does not ship a Postgres variant as an alternate contribution at v1.0.0 because the mechanism has no variant/profile selector: two engine TACs contributed together would both need realising or both leave dangling references. One default plus a documented promotion path is the shape that fits the mechanism today.",
+  "consequences": "The project inherits zero-infrastructure persistence: no database server, no connection pool, no network round trip; the store is a file on the same host the process runs on. Backups are file copies. Deploys move the file with the container image or with the volume mount. Kill-9 tolerance is a WAL property, not a hand-rolled invariant. The scale ceiling is a single-writer envelope: multi-writer workloads and cross-host replication are out of reach without switching engines, and the promotion signal is real (see guide 'when it does not fit'). Composing blueprints that hold an opinion on the store engine conflict on the persistenceStore topic; the expected resolution is one project-level ADR that fixes the engine and states the reasoning for the tier, superseding this ADR and any composing blueprint's contribution.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship Postgres as a co-contributed alternate engine TAC alongside SQLite in v1.0.0",
+      "summary": "The blueprint contributes TAC-601-sqlite-store and TAC-601-postgres-store side by side; the project picks one at apply time.",
+      "reasonNotChosen": "The rcf-lite blueprint mechanism (Phase 1) has no variant/profile selector. Two TACs contributed together are both applied, and both leave dangling tacIds references on their user stories if the project only realises one. Adding a mechanism-level variant concept is a v1.1 investment; deferring the second engine to a superseding project-level ADR keeps v1.0.0 shippable and mirrors the security-auth-magic-link blueprint's keycloak-local deferral (see the auth guide 'when it does not fit')."
+    },
+    {
+      "name": "Postgres-first with SQLite as a test-only shim",
+      "summary": "Default to Postgres for production and offer SQLite as an ephemeral engine for tests.",
+      "reasonNotChosen": "Wrong shape for the tier. A single-deployable rcf-lite project should not carry a database server as a hard dependency at v1. Test-only in-memory doubles satisfy the test story more cheaply than a schema-mirrored SQLite for a Postgres deployment, at the cost of test fidelity that projects can trade explicitly."
+    },
+    {
+      "name": "Schema-agnostic KV store (RocksDB, LMDB)",
+      "summary": "Drop the relational shape and use a byte-oriented KV store as the substrate.",
+      "reasonNotChosen": "The relational shape is what makes the query story sane for the domain the rcf-lite tier typically ships. A KV substrate pushes the query problem into application code and gives up the constraint-checking safety net that SQLite provides for free. Projects whose domain is genuinely KV-shaped (opaque blob storage, event streams) supersede this ADR."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/adrs/adr-602-persistence-data-sqlite-migration-discipline.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-602-persistence-data-sqlite-migration-discipline",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Forward-only numbered migrations applied atomically at open; refuse to boot against a store newer than the build",
+  "context": "Schema evolution in a running system has three failure modes: silent drift (the deployed schema does not match the code's assumptions), half-application (a migration ran partway and left the store in an undefined shape), and reverse-compatibility hazard (an older build opens a newer store and reads through unknown columns). The migration story has to close all three at the substrate level; asking every future contributor to hand-implement the discipline is the shape that produces the incident.",
+  "decision": "Schema evolution is a forward-only numbered migration catalog. Each migration entry carries a monotonic version integer, a description string, and one or more DDL/data statements. The migration runner (TAC-602) applies pending entries in ascending order at store open; each entry runs inside one transaction whose scope covers every statement plus the version bookkeeping insert. A per-migration failure rolls back the transaction, throws a migration-failed error naming the failing version, and does not attempt later entries. When the on-disk highest version is strictly greater than the catalog's max, the runner throws a refuse-newer error with a stable code and does not open the store. There are no down migrations: a rollback to an older schema is a redeploy against the older build, and the newer store refuses to open under the older build (that refusal is the safety property).",
+  "consequences": "Deploys are reproducible from a git ref because the catalog and the code that opens the store ship in one commit. Half-migrations are structurally impossible: a mid-migration crash rolls back the transaction and the on-disk version remains the last successfully committed one. Reverse-compatibility incidents fail loudly at boot instead of silently at the first read. The cost is that a botched schema change is a code fix and a redeploy, not a schema-side undo: projects that need to revert a migration in-place cannot, and must instead ship a compensating forward migration under a new version. Composing blueprints that hold their own opinion on migration discipline (event-sourced projections, dual-write patterns, tenant-per-schema) conflict on the migrationDiscipline topic; the expected resolution is one project-level ADR that fixes the discipline for the project.",
+  "alternativesConsidered": [
+    {
+      "name": "Bidirectional up/down migrations",
+      "summary": "Every migration ships an up statement set and a down statement set; the runner supports rolling back to an older version by executing the down statements in reverse order.",
+      "reasonNotChosen": "Down migrations are notoriously wrong (contributors write them from imagination, not from testing, and the first time they run in anger is when they are needed). The refuse-newer property gives the safety a down migration is supposed to give (older code cannot damage a newer store), without the maintenance cost of a shipping-and-testing down path that is exercised approximately never."
+    },
+    {
+      "name": "Best-effort tolerant reads under an older build",
+      "summary": "The older build opens the newer store, ignores unknown columns, and serves reads it can express.",
+      "reasonNotChosen": "The failure mode is silent data damage on writes: an INSERT that does not name a NOT NULL column added in the newer schema fails at the engine, and an UPDATE that overwrites structured data with the older shape corrupts the newer data. Refuse-at-boot is the only reliable posture; the operator sees the error at deploy time rather than at 03:00 when a customer notices."
+    },
+    {
+      "name": "Migrations run through an external tool (e.g. Flyway, Alembic) invoked out-of-band at deploy",
+      "summary": "The store code assumes the schema is already at the right version; a deploy step external to the process runs the migrations.",
+      "reasonNotChosen": "Adds a moving part to the deploy pipeline and to the ops runbook, decouples the migration-run success signal from the process-start success signal, and introduces the possibility of a process starting against a store the migrations have not been run on. Running migrations at open ties the two success signals together and makes the process refuse to start on any deploy that skipped the migration step."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/adrs/adr-603-persistence-data-sqlite-event-secrecy.json

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

package/blueprints/persistence-data-sqlite/contributions/adrs/adr-604-persistence-data-sqlite-store-boundary.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-604-persistence-data-sqlite-store-boundary",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The store facade is the only module that imports the engine binding; consumers use named domain verbs, not raw queries",
+  "context": "A persistence boundary that leaks (the domain code imports the engine binding, or the facade exposes a general-purpose raw-query passthrough) is a boundary the swap-out story does not work through, the test-double story does not work through, and the reasoning-about-persistence-code-paths story does not work through. Every one of those benefits depends on the boundary being narrow at the point of consumption, not merely intended to be narrow.",
+  "decision": "One module (the store facade, TAC-601) imports the engine binding for the engine chosen in ADR-601. Every other module in the source tree that touches persistence imports the store facade and calls its named verbs. The facade's public surface exposes named domain verbs (insertX, findX, updateX, deleteX and the domain equivalents) with typed parameters; it does not expose a general-purpose query method whose parameter is a raw SQL string or an engine-native query object supplied by consumer code. When a consumer needs a query the facade does not currently express, the fix is to add a named verb to the facade, not to bypass the facade with a raw query.",
+  "consequences": "The engine choice is swappable because there is exactly one place that changes. Domain tests run against an in-memory double that implements the same verb surface, without importing the engine binding at any point in the test's call path. Every persistence code path is discoverable by grepping for the facade's exports. Consumers pay a small cost when they need a new query shape (a facade edit and a consumer edit, in one commit); the size of that cost is the mechanism enforcing the boundary. Composing blueprints that contribute persistence-adjacent components (a cache, an outbox, a projection) contribute their own facade modules on the same discipline; every one of them imports the store facade for its persistence needs, not the engine binding.",
+  "alternativesConsidered": [
+    {
+      "name": "General-purpose raw-query passthrough on the facade",
+      "summary": "The facade exposes execute(sql, params) that consumers use for ad-hoc queries the facade does not otherwise express.",
+      "reasonNotChosen": "Any raw-query passthrough migrates over time from 'occasional escape hatch' to 'the way consumers write queries'. Every such call site is a code path that has to be re-audited on an engine swap, a code path that cannot be tested against an in-memory double, and a code path where the reasoning about the store's shape lives in string literals scattered across the codebase. The escape hatch is not worth the boundary erosion."
+    },
+    {
+      "name": "Domain-code direct engine imports for hot-path queries",
+      "summary": "Performance-sensitive queries import the engine binding directly and skip the facade.",
+      "reasonNotChosen": "Performance is not a defensible reason to erode the boundary at the rcf-lite tier: the facade adds no measurable overhead over the engine binding, and hot-path queries that genuinely need it are a rare-enough case to justify a specialised facade verb rather than an import-graph shortcut. Projects that outgrow the tier and need a different posture do so by superseding this ADR with reasoning."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/adrs/adr-605-persistence-data-sqlite-backup-model.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-605-persistence-data-sqlite-backup-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Backup is a file-level snapshot of the store artifact taken without downtime",
+  "context": "A backup story has three axes: what the artifact is (a file, a logical dump, a stream), when it can run (with the application quiesced, with the application live), and how it recovers (point a build at the artifact, run a restore tool). For the rcf-lite tier with the SQLite default engine and the store-facade boundary, the file-level snapshot is the natural answer: the engine already writes the store as one file, the WAL posture already tolerates concurrent snapshot, and recovery is 'point a compatible build at the file'.",
+  "decision": "The backup runner (TAC-604) snapshots the store to a portable artifact while the application keeps serving reads and writes. Under the SQLite default engine, the runner uses the online-backup API or a WAL-checkpoint-then-file-copy; the writer connection stays available. The artifact is engine-native: a SQLite file, not a schema-agnostic dump. Recovery is opening the artifact through the same store facade against a compatible build. A backupCheckpoint event fires on completion carrying the artifact path and the ISO-8601 completion timestamp. Cross-engine migration (a SQLite backup restored into Postgres) is out of scope for this blueprint; projects that need it author a project-side logical-dump runner beside this one, and the file-level runner remains the primary recovery path.",
+  "consequences": "The backup story is cheap to run and cheap to test: a scheduler invokes store.backup(outputPath) on a cron, the operator inspects the backupCheckpoint event stream for freshness, and a recovery exercise is opening a copied file with the same build. No maintenance window is planned; no ops-side backup daemon is deployed. The cost is that the artifact is engine-native: switching engines is not restore-and-go, and a project that needs a portable dump does so on top of the file-level story. Projects that need cross-region replication supersede this ADR with an engine-native replication decision (SQLite Litestream, Postgres physical replication, or the engine promoted by ADR-601).",
+  "alternativesConsidered": [
+    {
+      "name": "Logical schema-aware dump as the primary backup",
+      "summary": "The backup runner produces a SQL script that recreates the schema and the rows; recovery replays the script.",
+      "reasonNotChosen": "Logical dumps are portable but slow on the write path (encoding every value as SQL) and slow on the recovery path (replaying every statement). For the rcf-lite tier the size and frequency of backups make the portability trade uneconomic. Projects that need portability author a logical dump runner beside the file-level one, kept in sync by the schema catalog."
+    },
+    {
+      "name": "Quiesce-and-copy (planned downtime for backup)",
+      "summary": "The application takes a maintenance window; the backup runner copies the file with no writers active.",
+      "reasonNotChosen": "Any backup story that requires downtime is a backup story the operator skips. The engine's online-backup posture makes the downtime unnecessary; the cost of the online path is a small pause on the writer during the final page copy, which is invisible at the request timescale."
+    }
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}