rcf-lite 0.11.0 → 0.13.0

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Every persistent entity lives in a single durable store opened via one boot-time entry point",
+  "description": "The application persists every stateful entity (session records, work items, audit trail, whatever the project's domain model requires) in a single durable store. The store is opened exactly once at process boot through a single entry point that other components import; nothing else in the process opens the underlying database file or connection. When the entry point returns, migrations have run and the store is ready to serve consumer calls.",
+  "category": "functional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Multiple entry points into the same durable substrate is the shape that produces stale caches, dueling migrations, and lock contention. One entry point at boot means one migration pass, one connection posture, one place to test and one place to fix. Consumers that need a persistence surface import the facade, not the engine.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:01-store-facade"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-002",
+  "prdId": "PRD-001",
+  "title": "The store schema is versioned; every schema change is a numbered forward-only migration committed in-tree",
+  "description": "Schema evolution is expressed as an ordered catalog of numbered migrations. Each migration carries a monotonic version integer, a human description, and one or more DDL/data statements. The catalog lives in-tree next to the store code and is the sole source of schema truth; the store's current version is a fact recorded in a bookkeeping row inside the store itself and updated only by the migration runner.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "A schema catalog committed in-tree makes deploys reproducible: the code that opens the store and the migrations it expects ship together in one commit. Numbered forward-only migrations avoid the two failure modes of ad-hoc schema drift (undocumented change, incompatible rollback). Bookkeeping inside the store means the fact of a version cannot desync from the tables the version describes.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:02-migration-catalog"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-003",
+  "prdId": "PRD-001",
+  "title": "The store refuses to open when the on-disk schema version is newer than the build's max known version",
+  "description": "At open time, the migration runner reads the on-disk schema version from the bookkeeping table and compares it against the build's max known migration version. When the on-disk version is strictly greater than the build's max, the runner throws a specific error with a stable code and a message naming both versions; the process fails to start. The store makes no writes on this path.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Deploying an older build against a newer store is not a safe operation: the older build does not know about the schema shape the newer build wrote, and reads and writes against unknown columns are the shape that corrupts data silently. Refusing at open is the only place the check is cheap; once a request has been served, the damage is done.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:03-refuse-newer"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Migrations apply in order, each inside a single transaction; a mid-migration crash leaves the store on the previous version",
+  "description": "The migration runner iterates pending migrations in ascending version order. For each migration, the runner opens a transaction, executes every statement in the migration, writes the version row into the bookkeeping table, and commits. A failure at any step aborts the transaction and rolls back; the on-disk version reflects the last successfully committed migration. The runner surfaces the failure with a specific error code naming the version that failed.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Half-applied migrations are the shape that turns a schema evolution into a hand-recovery incident. Wrapping each migration in one transaction with its version bump means the store is always at a version the code knows how to interpret. Naming the failing version in the error means the operator can inspect the exact statement set that failed.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:04-atomic-migration"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-005",
+  "prdId": "PRD-001",
+  "title": "The store survives ungraceful process termination without corrupting on-disk state",
+  "description": "An abrupt SIGKILL, host power loss, or container OOM-kill of the running process leaves the on-disk store openable on the next boot with every committed write intact and every in-flight transaction rolled back. The store's durability posture (write-ahead log with a synchronous commit floor, or the engine-native equivalent) is set at open time and is not a caller concern.",
+  "category": "nonFunctional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "A store that corrupts on an ungraceful shutdown is a store that will corrupt in production sooner or later: hosts die, containers get killed, the OOM killer picks the process at 03:00. Making crash safety a store-side default rather than a per-call ceremony means every consumer inherits it without having to remember.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:05-crash-safety"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-006",
+  "prdId": "PRD-001",
+  "title": "A structured event log records store lifecycle events with defined fields",
+  "description": "The store emits structured events at four defined moments: opened (at successful open), migrated (once per migration run that applied at least one migration, carrying the version transition and the list of versions applied), backupCheckpoint (on each snapshot completion), and closed (on graceful shutdown). Every event carries an event name, an ISO-8601 timestamp, and the fields defined for that event class. Consumers subscribe via a single sink function injected at open time.",
+  "category": "functional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Silent stores are stores that surprise the operator. A structured event log makes 'when did the store come up, what version did it migrate through, when did the last snapshot land' answerable from the log stream without a database query. The four events are the minimum viable surface: opened proves boot, migrated proves schema state, backupCheckpoint proves the recovery story is live, closed proves a clean shutdown.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:06-event-log"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-007",
+  "prdId": "PRD-001",
+  "title": "The store facade is the only module that talks to the underlying engine; consumers use narrow verbs, not raw queries",
+  "description": "One module (the store facade) imports the engine binding and holds the connection or file handle. Every other module in the process talks to persistence exclusively through named verbs exposed by the facade (insertX, findX, updateX, deleteX and their domain equivalents). No consumer imports the engine binding directly; no consumer constructs raw SQL or engine-native query objects and hands them to the facade for execution.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "A single boundary between the domain and the engine is what makes swapping the engine possible, what makes testing the domain against an in-memory double possible, and what makes reasoning about which code paths touch persistence tractable. Raw-query passthrough defeats every one of those benefits without adding capability the facade cannot express.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:07-module-boundary"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/requirements/persistence-data-sqlite-req-008.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-008",
+  "prdId": "PRD-001",
+  "title": "A backup is a file-level snapshot of the store artifact taken without downtime",
+  "description": "The backup procedure produces a self-contained artifact (a copy of the SQLite file, an engine-native snapshot, or the equivalent) that, when opened by a compatible build, boots to the same schema version and holds the same committed rows as the source store at the snapshot moment. The procedure runs against a live store: no request quiescence, no consumer freeze, no application shutdown. The backup runner emits a backupCheckpoint event on the store's event log with the artifact path and the ISO-8601 completion timestamp.",
+  "category": "nonFunctional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "A backup story that requires downtime is a backup story the operator will skip until it is too late. A file-level snapshot inherits the durability posture of the underlying engine (WAL checkpointing for SQLite, replication slots for Postgres) and turns 'do we have a recent backup' into a stat call on the artifact path. The event on completion is what makes 'when did the last snapshot land' answerable from the log without a filesystem walk.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:08-backup"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/requirements/persistence-data-sqlite-req-009.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-009",
+  "prdId": "PRD-001",
+  "title": "A failed migration surfaces a specific error code and leaves the on-disk store unchanged",
+  "description": "When a migration statement or its version bookkeeping row fails, the migration runner rolls back the transaction, throws an error with a stable code and a message naming the failing version and the description of that migration, and does not attempt further migrations. The on-disk schema version reflects the last successfully committed migration, not the failed one. The store facade propagates the failure to the caller of the open entry point.",
+  "category": "technical",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "Silent partial migrations are the shape that produces the worst production incidents: the store is in a state no code knows how to interpret and the operator has no error to search on. A stable error code that names the failing version turns the diagnostic loop into a one-step operation (open the migration, read the statement, fix, redeploy).",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:09-migration-failure"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/requirements/persistence-data-sqlite-req-010.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-010",
+  "prdId": "PRD-001",
+  "title": "The store event log holds no secret material",
+  "description": "No field on any store event (opened, migrated, backupCheckpoint, closed) carries user data, credential material, session handles, token secrets, private keys, or the values of any column marked as secret in the domain schema. Event fields are limited to store metadata: the store path or identifier, ISO-8601 timestamps, schema version numbers, migration version numbers, migration descriptions, applied-version arrays, backup artifact paths.",
+  "category": "security",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "A store event log is safe to ship to a third-party observability provider only if it holds no secret material. Store events describe the store's own lifecycle, not the domain data it holds; conflating the two produces a log stream that becomes a session-takeover breach the moment it leaks. The discipline has to be enforced at emit time; downstream redaction misses cases.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:10-log-secrecy"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/requirements/persistence-data-sqlite-req-011.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "persistence-data-sqlite-REQ-011",
+  "prdId": "PRD-001",
+  "title": "Opening a store already at the target schema version is a no-op that emits no migrated event",
+  "description": "When the on-disk schema version equals the build's max known migration version, the migration runner applies no migrations and returns a result whose applied-versions array is empty. The store facade emits the opened event as usual but does NOT emit a migrated event on this path. Consumers that key off the migrated event to fire post-migration bookkeeping do not fire spuriously on a routine boot.",
+  "category": "nonFunctional",
+  "domain": "persistence",
+  "priority": "must",
+  "rationale": "A store that emits a migrated event on every boot destroys the signal that migration-adjacent bookkeeping (cache warmup, index rebuild, replica reseeding) needs to fire. Idempotent open is what makes routine boots cheap and rare boots observable; conflating them costs both signals.",
+  "tags": [
+    "blueprint:persistence-data-sqlite",
+    "category:11-idempotent-open"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/tacs/tac-601-persistence-data-sqlite-store.json

@@ -0,0 +1,57 @@
+{
+  "tacId": "TAC-601-persistence-data-sqlite-store",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Store facade",
+  "purpose": "The single module that opens the underlying engine, holds the connection or file handle for the process lifetime, runs the migration runner at open, and exposes narrow named verbs to consumer code. Consumers never import the engine binding directly; the facade is the one place the engine choice lives.",
+  "responsibilities": [
+    "Open the underlying engine against a configured store identifier (path or connection string), set the crash-safety posture the engine needs for kill-9 tolerance, and hold the handle exclusively for the process lifetime (AC-5101-1, AC-5101-2, AC-5105-3).",
+    "Invoke the migration runner (TAC-602) at open, propagating its outcome to the caller: refuse-newer errors and migration-failed errors are thrown up unwrapped or wrapped with the original code preserved (AC-5101-3, AC-5103-1, AC-5109-2).",
+    "Expose a schemaVersion read operation whose return value equals the highest applied migration version recorded in the bookkeeping table (AC-5102-2).",
+    "Expose the domain CRUD verbs as named exports with typed parameters; refuse a general-purpose raw-query passthrough on the public surface (AC-5107-2).",
+    "Emit structured events (opened, migrated, backupCheckpoint, closed) on the injected onEvent sink; carry only store-metadata fields; never carry values read from domain rows (AC-5106-1, AC-5106-3, AC-5110-1)."
+  ],
+  "internalStructure": "One module that exports an openStore({ path, onEvent }) entry point returning a facade object whose methods are the named CRUD verbs plus schemaVersion, backup, and close. The engine binding import is scoped to this module; the migration runner (TAC-602) is imported here and invoked before the facade returns. Consumers destructure the verbs they need at their top level and hold the facade reference for the process lifetime.",
+  "interfaces": [
+    {
+      "name": "openStore",
+      "kind": "factory",
+      "description": "openStore({ path, onEvent }) -> Store; the sole entry point the boot sequence calls. Returns a Store facade with the migration runner already run and the crash-safety posture already set."
+    },
+    {
+      "name": "onEvent",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with { event, ts, ... } for opened, migrated, backupCheckpoint, and closed events. Never invoked with domain-row values."
+    },
+    {
+      "name": "store.verbs",
+      "kind": "read-write-api",
+      "description": "The named domain CRUD verbs the facade exposes. Each verb has typed parameters; no verb accepts a raw query string or engine-native query object from consumer code."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Migration runner",
+      "kind": "tac",
+      "tacId": "TAC-602-persistence-data-sqlite-migration-runner",
+      "description": "Invoked at open with the loaded migration catalog and the open engine handle; its result feeds the opened/migrated events."
+    },
+    {
+      "name": "Migration catalog",
+      "kind": "tac",
+      "tacId": "TAC-603-persistence-data-sqlite-migration-catalog",
+      "description": "Loaded at open and handed to the migration runner. The catalog's max version anchors the schemaVersion contract."
+    },
+    {
+      "name": "Backup runner",
+      "kind": "tac",
+      "tacId": "TAC-604-persistence-data-sqlite-backup-runner",
+      "description": "Exposed as store.backup(outputPath); emits the backupCheckpoint event on completion through the same event sink."
+    }
+  ],
+  "tradeoffs": "The facade owns the engine handle for the process lifetime; consumer code cannot pool or share handles across the boundary. That cost buys the one-boundary invariant every other AC on this blueprint depends on. Projects that need a per-request connection pool (a shape more natural to Postgres than to SQLite) wire the pool inside this module and preserve the facade's outward interface unchanged.",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/tacs/tac-602-persistence-data-sqlite-migration-runner.json

@@ -0,0 +1,34 @@
+{
+  "tacId": "TAC-602-persistence-data-sqlite-migration-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Migration runner",
+  "purpose": "Owns the forward-only migration semantics. Reads the on-disk schema version, compares against the build's max known version, applies pending migrations in order inside one transaction each, and returns the version transition. Refuses to run when the on-disk version is newer than the build knows about. Rolls back and reports on any per-migration failure without attempting later migrations.",
+  "responsibilities": [
+    "Ensure the bookkeeping table (schemaVersion with version PRIMARY KEY and appliedAt timestamp) exists idempotently before reading the on-disk version. This is the only DDL statement outside a versioned migration (AC-5102-3).",
+    "Read the on-disk highest version from the bookkeeping table. Compare against the max version in the loaded catalog. Throw a refuse-newer error with a stable code and a message naming both versions when the on-disk version is strictly greater (AC-5103-1, AC-5103-2).",
+    "For each pending migration in ascending order, open a transaction, execute every statement in the migration's statements list, insert the version bookkeeping row, and commit. On any failure, roll back and throw a migration-failed error naming the failing version and description; do not attempt later migrations (AC-5104-1, AC-5104-2, AC-5104-3, AC-5109-1).",
+    "Return a { from, to, applied } result carrying the pre-run highest version, the post-run highest version, and the array of versions applied during this run (empty on a no-op at target version) (AC-5106-2, AC-5111-1)."
+  ],
+  "internalStructure": "One migrate(engineHandle, catalog) function that reads the on-disk version, filters the catalog to pending entries, iterates them in order, and returns the transition record. Idempotent bookkeeping-table DDL runs once at entry. The transaction boundary is expressed in whatever primitive the engine binding provides (BEGIN IMMEDIATE / COMMIT / ROLLBACK for SQLite; BEGIN / COMMIT / ROLLBACK for Postgres). No state is retained between invocations.",
+  "interfaces": [
+    {
+      "name": "migrate",
+      "kind": "function",
+      "description": "migrate(engineHandle, catalog) -> { from, to, applied }; the sole entry point the store facade calls at open. Throws refuse-newer or migration-failed errors with stable codes on the failure paths."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Migration catalog",
+      "kind": "tac",
+      "tacId": "TAC-603-persistence-data-sqlite-migration-catalog",
+      "description": "Consumed as the ordered list of pending migrations to apply. The catalog's max version anchors the refuse-newer comparison."
+    }
+  ],
+  "tradeoffs": "Forward-only means no down migrations; a rollback to an older schema is a redeploy against the older code with the older catalog, and the newer store artifact refuses to open under the older build. That refusal is the safety property (see ADR-602); the cost is that a botched schema change is a code fix and a redeploy, not a schema-side undo. The runner holds no state, which means every open re-checks the on-disk version against the catalog and re-applies pending work idempotently on retry.",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/tacs/tac-603-persistence-data-sqlite-migration-catalog.json

@@ -0,0 +1,31 @@
+{
+  "tacId": "TAC-603-persistence-data-sqlite-migration-catalog",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Migration catalog",
+  "purpose": "The in-tree source of schema truth. An ordered list of migration entries, each carrying a monotonic version integer, a human description string, and one or more DDL/data statements. The catalog lives next to the store facade and is imported by the migration runner at open. Its max version is the build's max known migration version, which the refuse-newer comparison and the schemaVersion read both anchor against.",
+  "responsibilities": [
+    "Expose an ordered sequence of migration entries starting at version 1 with no gaps; each entry has fields { version, description, statements } where statements is a non-empty list of engine-native DDL/data statements (AC-5102-1).",
+    "Expose the max version integer as a named export the store facade reads for schemaVersion contract validation and refuse-newer comparison (AC-5102-2).",
+    "Hold every schema change ever shipped in this project's history; a schema change that is not a new numbered entry in this catalog is not a shipped schema change (AC-5102-1)."
+  ],
+  "internalStructure": "One source-tree module exporting MIGRATIONS (the ordered array) and CURRENT_VERSION (the max version integer). Entries are appended, never edited: a shipped migration is a fact of production and any correction is a new migration that supersedes it. The statements field's dialect matches the engine ADR-601 selected; SQLite dialect at v1.0.0 unless a project supersedes ADR-601.",
+  "interfaces": [
+    {
+      "name": "MIGRATIONS",
+      "kind": "constant",
+      "description": "The ordered array of { version, description, statements } entries, exported as a named module-level constant."
+    },
+    {
+      "name": "CURRENT_VERSION",
+      "kind": "constant",
+      "description": "The max version integer across MIGRATIONS. Equals MIGRATIONS[MIGRATIONS.length - 1].version by construction."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "One central catalog file is trivial to reason about at small history (up to a few dozen entries) and starts to strain review at large history. Projects that outgrow one file split into one-file-per-migration under a directory the module aggregates, preserving the exported MIGRATIONS shape. Statements-as-strings keeps the catalog readable but couples it to one engine dialect; supporting two engines from one catalog requires a per-entry dialect indirection the v1.0.0 shape does not carry and the blueprint does not recommend before a project needs it.",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/tacs/tac-604-persistence-data-sqlite-backup-runner.json

@@ -0,0 +1,33 @@
+{
+  "tacId": "TAC-604-persistence-data-sqlite-backup-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Backup runner",
+  "purpose": "Produces a self-contained snapshot of the store artifact without downtime: the application keeps serving reads and writes while the runner copies the file (SQLite: online-backup API or checkpoint-then-file-copy) or requests an engine-native snapshot (Postgres: pg_basebackup or file-system snapshot). Emits a backupCheckpoint event on completion carrying the artifact path and the ISO-8601 completion timestamp.",
+  "responsibilities": [
+    "Snapshot the store to the requested output path while consumer requests continue to serve. No request may be marked failed on account of the backup operation (AC-5108-1).",
+    "Produce an artifact a fresh process can open through the same store facade at the same schema version and read the rows committed at or before the snapshot completion timestamp (AC-5108-2).",
+    "Emit exactly one backupCheckpoint event on the store's event log at snapshot completion, carrying the artifact path and the completion timestamp (AC-5108-3, AC-5106-1)."
+  ],
+  "internalStructure": "One backup(outputPath) method exposed on the store facade. Under the SQLite engine (ADR-601 default), the implementation opens a second connection in backup mode and uses the online-backup API to stream pages to the output path, or issues a WAL checkpoint and then copies the main file; either way the writer's connection stays available. Under an alternate engine the implementation uses the engine-native equivalent behind the same facade method.",
+  "interfaces": [
+    {
+      "name": "backup",
+      "kind": "async-method",
+      "description": "store.backup(outputPath) -> Promise<{ artifactPath, completedAt }>; the sole backup entry point on the facade. Emits backupCheckpoint on completion via the store's event sink."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Store facade",
+      "kind": "tac",
+      "tacId": "TAC-601-persistence-data-sqlite-store",
+      "description": "The backup runner is exposed as a method on the store facade and reuses the facade's event sink for backupCheckpoint emission."
+    }
+  ],
+  "tradeoffs": "File-level backup is fast, portable, and cheap to restore (point a compatible build at the file), and it does not require a logical schema-aware dump. The cost is that the artifact is engine-native: a SQLite file is not restorable into a Postgres cluster. Cross-engine migration is out of scope for this blueprint. Projects that need a logical dump alongside the file-level backup add a project-authored dump runner beside this one; the file-level runner remains the primary recovery path.",
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/user-stories/persistence-data-sqlite-us-5101.json

@@ -0,0 +1,46 @@
+{
+  "usId": "persistence-data-sqlite-US-5101",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The store opens once at boot and is ready when the entry point returns",
+  "asA": "operator whose deploy needs a persistence surface ready before the first request is served",
+  "iWant": "the store to be opened exactly once at boot through a single entry point that runs migrations before returning",
+  "soThat": "the application starts in a known persistence state and no request runs against a half-initialised store",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5101-1",
+      "description": "The application exposes a single named function or module export that opens the store, and the process invokes it exactly once during boot before any request handler binds.",
+      "given": "the application is starting cold",
+      "when": "the boot sequence runs",
+      "then": "the store event log contains exactly one opened event whose timestamp precedes the timestamp of the first served request",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5101-2",
+      "description": "The store opens with a path or connection string sourced from application configuration; no consumer code hard-codes the store location.",
+      "given": "the application is configured with a store path or connection string",
+      "when": "the boot sequence runs the open entry point",
+      "then": "the store event log's opened event carries the same store identifier the configuration supplied, and a grep of the source tree finds the identifier resolved from configuration rather than hard-coded",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5101-3",
+      "description": "The open entry point returns only after migrations have run to the build's max known schema version; consumer code that runs after the entry point returns sees a schema at that version.",
+      "given": "the boot sequence has invoked the open entry point and control has returned",
+      "when": "consumer code queries the schema version via the store facade",
+      "then": "the reported version equals the build's max known migration version",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-601-persistence-data-sqlite-store",
+    "TAC-602-persistence-data-sqlite-migration-runner"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/user-stories/persistence-data-sqlite-us-5102.json

@@ -0,0 +1,46 @@
+{
+  "usId": "persistence-data-sqlite-US-5102",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Schema evolution is expressed as a numbered forward-only migration catalog committed in-tree",
+  "asA": "operator who needs deploys to be reproducible from a git ref",
+  "iWant": "every schema change to live in an ordered numbered migration catalog next to the store code",
+  "soThat": "the schema shape at any deployed version can be read directly from the committed catalog and no schema state exists outside version control",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5102-1",
+      "description": "The migration catalog exists as a source-tree artifact whose entries carry a monotonic version integer, a description string, and one or more statements. Loading the catalog yields entries in ascending version order with no gaps.",
+      "given": "the source tree at any commit that produces a running application",
+      "when": "the store facade imports the catalog at boot",
+      "then": "the loaded catalog is an ordered sequence whose version integers start at 1 and increase by exactly 1 per entry, and every entry carries a non-empty description and a non-empty statements list",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5102-2",
+      "description": "The store facade exposes a schemaVersion read operation whose return value equals the highest version present in the bookkeeping table after the last successful migration run.",
+      "given": "the store has been opened and any pending migrations have applied",
+      "when": "consumer code calls the schemaVersion read operation",
+      "then": "the returned integer equals the max value of the bookkeeping table's version column, and matches the max version integer in the loaded catalog",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5102-3",
+      "description": "The migration runner writes exactly one bookkeeping row per successfully applied migration, carrying the migration's version integer and an ISO-8601 appliedAt timestamp.",
+      "given": "the store opens against a file older than the build's max known version",
+      "when": "the migration runner completes",
+      "then": "the bookkeeping table holds one row per applied migration with the appliedAt timestamp set to a value not in the future and not preceding the store-opened event",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-602-persistence-data-sqlite-migration-runner",
+    "TAC-603-persistence-data-sqlite-migration-catalog"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/user-stories/persistence-data-sqlite-us-5103.json

@@ -0,0 +1,37 @@
+{
+  "usId": "persistence-data-sqlite-US-5103",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The store refuses to boot when it is newer than the build",
+  "asA": "operator whose deploy rollback must never corrupt production data",
+  "iWant": "the store to refuse to open when its on-disk schema version is newer than this build knows about",
+  "soThat": "an accidental rollback to an older build fails loudly at boot instead of silently reading and writing against unknown schema shapes",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5103-1",
+      "description": "Opening a store whose bookkeeping table records a schema version strictly greater than the build's max known migration version throws an error with a stable code and a message naming both versions; the process does not enter its request-serving state.",
+      "given": "a store artifact whose highest bookkeeping row records version N and a build whose max known migration version is M with M < N",
+      "when": "the boot sequence invokes the open entry point",
+      "then": "the entry point throws an error whose code is a stable identifier for the refuse-newer condition, whose message contains both the integer N and the integer M, and the process fails to reach its request-serving state",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5103-2",
+      "description": "The refuse-newer path performs no writes against the store; the bookkeeping table and every domain table are byte-identical before and after the failed open.",
+      "given": "a store artifact snapshot taken before the failed open attempt in AC-5103-1",
+      "when": "the failed open attempt returns control",
+      "then": "a fresh snapshot of the same store artifact is byte-identical to the pre-attempt snapshot, and no new bookkeeping row has been written",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-601-persistence-data-sqlite-store",
+    "TAC-602-persistence-data-sqlite-migration-runner"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/user-stories/persistence-data-sqlite-us-5104.json

@@ -0,0 +1,45 @@
+{
+  "usId": "persistence-data-sqlite-US-5104",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Migrations apply atomically; a crash mid-migration leaves the previous version intact",
+  "asA": "operator whose deploy must never leave the store in a half-migrated state",
+  "iWant": "each migration to run inside a single transaction with the version bookkeeping row committed alongside its statements",
+  "soThat": "an abrupt failure during migration N leaves the store on version N-1, not on some undefined mixture",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5104-1",
+      "description": "The migration runner applies pending migrations in ascending version order; for each migration, the version bookkeeping row and the migration's statements are committed in one transaction.",
+      "given": "a store opened against a file older than the build's max known version with pending migrations v_k+1 through v_n",
+      "when": "the migration runner completes successfully",
+      "then": "the bookkeeping table holds one row for each of v_k+1 through v_n in ascending order, and every domain table shape reflects the union of statements from those migrations",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5104-2",
+      "description": "A migration whose statements or version bookkeeping row fails is rolled back; the on-disk highest bookkeeping row after the failed run is the last successfully committed version.",
+      "given": "a store at version v_k and a pending migration v_k+1 whose statements will throw at execution time",
+      "when": "the migration runner attempts v_k+1 and its transaction fails",
+      "then": "the bookkeeping table's highest row remains v_k, no partial DDL from v_k+1 is present, and the migration runner throws an error naming version v_k+1 and the failing description",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5104-3",
+      "description": "The migration runner does not attempt migrations later than the first failing one; a failure at v_k+1 leaves v_k+2 and beyond unattempted.",
+      "given": "a store at version v_k and pending migrations v_k+1 (failing) and v_k+2 (would succeed)",
+      "when": "the migration runner runs and fails on v_k+1",
+      "then": "no domain-table statements from v_k+2 have been executed and the bookkeeping table holds no row for v_k+2",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-602-persistence-data-sqlite-migration-runner"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

package/blueprints/persistence-data-sqlite/contributions/user-stories/persistence-data-sqlite-us-5105.json

@@ -0,0 +1,45 @@
+{
+  "usId": "persistence-data-sqlite-US-5105",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The store survives an ungraceful process kill without corruption",
+  "asA": "operator whose hosts die and whose containers get OOM-killed at unhelpful moments",
+  "iWant": "the store to open cleanly on the next boot after an ungraceful termination, with every committed write intact and every in-flight transaction rolled back",
+  "soThat": "a SIGKILL, a power loss, or an OOM event does not turn into a data-recovery incident",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5105-1",
+      "description": "A write committed before the process is SIGKILL'd is present when a fresh process opens the same store artifact afterward.",
+      "given": "a running process that commits a distinguishable write W through a facade verb and then receives SIGKILL",
+      "when": "a fresh process opens the same store artifact and reads through the facade",
+      "then": "the read returns W with the same values that were committed, and the store event log's opened event for the fresh process is present with no accompanying corruption error",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5105-2",
+      "description": "An in-flight transaction that had not committed at the moment of SIGKILL is not visible after the fresh open.",
+      "given": "a running process that opens a transaction, executes writes W_a, and receives SIGKILL before commit",
+      "when": "a fresh process opens the same store artifact and reads through the facade",
+      "then": "the reads for W_a's affected rows return the pre-transaction state and no post-transaction state, and no partial subset of W_a is visible",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5105-3",
+      "description": "The store's durability posture (write-ahead log and synchronous commit floor, or engine-native equivalent) is set at open time by the facade; no consumer configures it.",
+      "given": "the store has been opened by the facade",
+      "when": "the durability posture is inspected via an engine-native introspection query executed through the facade",
+      "then": "the returned posture matches the facade's declared crash-safety configuration, and a grep of consumer code finds no direct configuration of these pragmas or engine-native equivalents",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-601-persistence-data-sqlite-store"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}