rcf-lite 0.12.0 → 0.14.0

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

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