rcf-lite 0.12.0 → 0.14.0

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

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

@@ -0,0 +1,46 @@
+{
+  "usId": "persistence-data-sqlite-US-5106",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Store lifecycle emits structured events on a single sink",
+  "asA": "operator who needs to answer 'when did the store come up, what version did it migrate through, when did the last snapshot land' from the log stream",
+  "iWant": "the store to emit structured events at open, at every migration run that applied work, at every backup checkpoint, and at close",
+  "soThat": "the store's lifecycle is a first-class observable and my dashboards do not have to shell into the database to answer basic questions",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5106-1",
+      "description": "The store facade accepts an onEvent sink function at open time and invokes it with a structured record on every lifecycle moment: opened at successful open, migrated when the runner applied at least one migration, backupCheckpoint when a snapshot completes, closed on graceful shutdown.",
+      "given": "the store is opened with an injected onEvent sink and taken through open, migrate, backup, and close",
+      "when": "the sink is inspected after each lifecycle moment",
+      "then": "the sink has received one record for each moment with the event name field set to opened, migrated, backupCheckpoint, and closed respectively, each carrying a valid ISO-8601 timestamp",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5106-2",
+      "description": "The migrated event carries the schema version transition and the list of migration versions applied during that run.",
+      "given": "the store opens against a file at version v_k with the build at max known version v_n where v_n > v_k",
+      "when": "the migrated event fires",
+      "then": "the event record contains a from field equal to v_k, a to field equal to v_n, and an applied field whose value is the array of integers v_k+1 through v_n in ascending order",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5106-3",
+      "description": "The opened event carries the store identifier the facade was opened against; the backupCheckpoint event carries the artifact path the backup runner wrote to.",
+      "given": "the store is opened against identifier I and a subsequent backup writes to artifact path B",
+      "when": "the opened and backupCheckpoint events fire",
+      "then": "the opened event's store identifier field equals I and the backupCheckpoint event's artifact path field equals B, both as strings the operator can pass back into their tooling verbatim",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-601-persistence-data-sqlite-store",
+    "TAC-604-persistence-data-sqlite-backup-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-5107.json

@@ -0,0 +1,45 @@
+{
+  "usId": "persistence-data-sqlite-US-5107",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The store facade is the only module that talks to the underlying engine",
+  "asA": "developer who needs the engine to be swappable and the domain to be testable against a double",
+  "iWant": "one module to hold the engine binding and expose named verbs, with no consumer importing the engine directly",
+  "soThat": "the boundary between the domain and the engine is the only place that has to move when the engine changes and the only place tests have to mock",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5107-1",
+      "description": "Exactly one source-tree module imports the engine binding. Every other module that touches persistence imports the store facade.",
+      "given": "the running source tree after boot",
+      "when": "the import graph is inspected for uses of the engine binding module",
+      "then": "the engine binding is imported by exactly one file (the store facade) and no other file in the source tree imports it, verified by an import-graph query or a targeted grep",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5107-2",
+      "description": "The facade exposes named verbs for every persistence operation the domain requires; it does not expose a general-purpose query method that accepts raw engine-native queries from consumers.",
+      "given": "the store facade's public surface",
+      "when": "the surface is inspected",
+      "then": "every exported function has a domain-shaped name and typed parameters (not a raw query string parameter), and no exported function accepts an engine-native query object or raw SQL string as a call argument from consumer code",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5107-3",
+      "description": "Replacing the facade with an in-memory double that implements the same verb surface allows the domain code to run against it without importing the engine binding.",
+      "given": "a test double implementing the same named verbs as the facade with an in-memory backing store",
+      "when": "the domain code runs against the double in place of the facade",
+      "then": "the domain code executes to completion without importing the engine binding at any point in its call path and its behaviour is unchanged from a facade-backed run for the operations under test",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-601-persistence-data-sqlite-store"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "persistence-data-sqlite-US-5108",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-008",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Backup produces a self-contained artifact without downtime",
+  "asA": "operator who cannot take the application offline to take a backup",
+  "iWant": "a backup runner that snapshots the store to a portable artifact while the application keeps serving requests",
+  "soThat": "recovery is a matter of pointing a compatible build at the artifact, and the backup schedule is not blocked on planning a maintenance window",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5108-1",
+      "description": "The backup runner produces an artifact file at the requested output path while the application continues to serve reads and writes; requests served during the snapshot do not fail because of the snapshot.",
+      "given": "the store is open under normal load and the backup runner is invoked with an output path P",
+      "when": "the backup runner completes and the served-request log for the snapshot window is inspected",
+      "then": "an artifact file exists at P and every request served during the snapshot window reports its normal outcome, with no request marked failed on account of the backup operation",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5108-2",
+      "description": "A fresh process opening the snapshot artifact through the same facade boots to the same schema version as the source store held at snapshot completion, and reads the rows that were committed at or before the snapshot completion timestamp.",
+      "given": "a snapshot artifact at path P produced by AC-5108-1 and a fresh process invoking the open entry point against P",
+      "when": "the fresh process's boot sequence completes and consumer code reads through the facade",
+      "then": "the fresh process's opened event names P as its store identifier, the reported schema version equals the source store's schema version at snapshot completion, and reads of rows committed at or before the snapshot completion timestamp return the committed values",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5108-3",
+      "description": "The backup runner emits a backupCheckpoint event on the store's event log at snapshot completion, carrying the artifact path and the ISO-8601 completion timestamp.",
+      "given": "the backup runner completes an artifact at path P at time T",
+      "when": "the event log is inspected",
+      "then": "the log contains exactly one backupCheckpoint event whose artifact path field equals P and whose completion timestamp field equals T",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-604-persistence-data-sqlite-backup-runner",
+    "TAC-601-persistence-data-sqlite-store"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "persistence-data-sqlite-US-5109",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Migration failure names the failing version and leaves the store unchanged past it",
+  "asA": "operator diagnosing a deploy that failed at boot on a migration",
+  "iWant": "the failure to name the failing version and its description in a stable-coded error, and to leave the store on the previous version so recovery is a code fix and a redeploy",
+  "soThat": "the diagnostic loop is one step (open the failing migration, fix, redeploy) instead of a data-recovery incident",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5109-1",
+      "description": "When a migration's statements or its bookkeeping row fails, the migration runner throws an error whose code is a stable identifier for the migration-failed condition, whose message contains the failing version integer and the migration's description string.",
+      "given": "a store at version v_k and a pending migration v_k+1 whose statements throw",
+      "when": "the migration runner attempts v_k+1",
+      "then": "the thrown error's code is a stable string identifier documented in the store facade, and its message contains the integer v_k+1 and the description string configured on that migration",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5109-2",
+      "description": "The store facade's open entry point propagates the migration failure to its caller without swallowing it or converting it to a different error class.",
+      "given": "a boot sequence whose migration run fails on v_k+1",
+      "when": "the caller catches the error thrown by the open entry point",
+      "then": "the caught error is the same error the migration runner threw, with the same code and message, unwrapped or wrapped in a chain that preserves the original code and message",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5109-3",
+      "description": "A store whose migration failed at v_k+1 opens cleanly on a subsequent boot after v_k+1 is fixed and the build is redeployed; no manual recovery step is required against the on-disk artifact.",
+      "given": "the failing v_k+1 statement is corrected in the migration catalog and the same store artifact is opened by the corrected build",
+      "when": "the boot sequence invokes the open entry point",
+      "then": "the migration runner applies v_k+1 and any later pending migrations, the migrated event fires, and consumer code sees the store at the build's max known version",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-602-persistence-data-sqlite-migration-runner",
+    "TAC-601-persistence-data-sqlite-store"
+  ],
+  "createdAt": "2026-08-21T00:00:00Z",
+  "updatedAt": "2026-08-21T00:00:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "usId": "persistence-data-sqlite-US-5110",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-010",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Store events carry no secret material",
+  "asA": "operator who ships store event logs to a third-party observability provider",
+  "iWant": "every field on every store event to be limited to store metadata; no domain data, no credential material, no secret values",
+  "soThat": "a log-store breach is not a domain-data breach and the ops team does not have to negotiate a redaction rule with the provider",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5110-1",
+      "description": "The fields on the opened, migrated, backupCheckpoint, and closed events are restricted to store metadata: event name, ISO-8601 timestamp, store identifier, schema version integers, migration version integers, migration description strings, and backup artifact paths. No event field carries a value read from a domain row.",
+      "given": "the store is taken through open, migrate, backup, and close",
+      "when": "every event record captured on the sink is inspected",
+      "then": "every field on every record matches one of the metadata field types listed above, and no field's value equals a value read from any domain table",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5110-2",
+      "description": "A grep of the store facade source for domain-table column names, secret-flagged column names, and the values of well-known secret columns (session handles, token secrets, private keys) finds them referenced only inside the narrow CRUD verbs that read or write those columns, never inside the event-emission call sites.",
+      "given": "the store facade source and the domain schema definition",
+      "when": "the grep is executed",
+      "then": "matches appear only inside CRUD verb bodies and never inside onEvent call arguments or event-record construction sites",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-601-persistence-data-sqlite-store",
+    "TAC-604-persistence-data-sqlite-backup-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-5111.json

@@ -0,0 +1,37 @@
+{
+  "usId": "persistence-data-sqlite-US-5111",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-sqlite-REQ-011",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Opening a store already at target version is a silent no-op",
+  "asA": "operator whose routine boots must not emit spurious migrated events",
+  "iWant": "the migration runner to apply no work and emit no migrated event when the on-disk version already equals the build's max",
+  "soThat": "a migrated event in the log means real schema evolution and my post-migration bookkeeping does not fire on every boot",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-5111-1",
+      "description": "Opening a store whose bookkeeping table records the same schema version the build's max known migration version equals results in a migration run whose applied-versions array is empty and no changes to the store artifact.",
+      "given": "a store artifact whose highest bookkeeping row records version N and a build whose max known migration version is N",
+      "when": "the boot sequence invokes the open entry point",
+      "then": "the migration run's applied-versions array is empty, no new bookkeeping row has been written, and a byte-for-byte comparison of the store artifact before and after the open shows no schema-affecting change",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-5111-2",
+      "description": "On the no-op open path, the opened event fires but the migrated event does NOT fire; the sink receives one opened record and zero migrated records.",
+      "given": "the no-op open in AC-5111-1 with an event sink attached",
+      "when": "the sink is inspected after the open entry point returns",
+      "then": "the sink has received exactly one opened record and zero migrated records for this open",
+      "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/docs/topics.md

@@ -0,0 +1,49 @@
+# persistence-data-sqlite blueprint coordination vocabulary
+
+This file is the persistence-data-sqlite half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | persistence-data-sqlite contribution | Origin | Composition note |
+|---|---|---|---|
+| `persistenceStore` | ADR-601-persistence-data-sqlite-store-model | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), and the hello-panel walkthrough exemplar (`operatorPanel`) | The one primary durable store engine for the project. Any composing blueprint that holds an opinion on the store engine (a Postgres-first blueprint, a KV-store blueprint, an event-sourced blueprint) contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the engine and states the tier reasoning |
+| `migrationDiscipline` | ADR-602-persistence-data-sqlite-migration-discipline | Minted here; pre-cleared as unclaimed against application-spa, application-api-rest, security-auth-magic-link, and hello-panel | The one schema-evolution discipline for the project. A composing blueprint that holds an opinion on migration discipline (event-sourced projections, dual-write patterns, tenant-per-schema, bidirectional up/down migrations) conflicts here by design. Expected resolution: one project-level ADR fixing the discipline |
+
+The persistence-data-sqlite blueprint claims two global topics. Every other contribution is scope-local (the three operational ADRs, ADR-603 through ADR-605, do not contribute global topics; a composing blueprint that holds an opinion on event-secrecy, the module-boundary posture, or the backup model authors its own project-level ADR if it wants to override).
+
+Note on the delineation from the application-api-rest blueprint's `logging` topic: `logging` (owned by application-api-rest ADR-304) governs the wire-log shape of the HTTP tier. This blueprint's ADR-603 governs the STORE-EVENT log shape (opened, migrated, backupCheckpoint, closed). The two log surfaces may share a shipper but do not share a topic. A blueprint that contributes a unified log discipline across all tiers would author its own scope:global ADR on `logging` and expect to conflict with REST there, not here.
+
+Rules for new topics (inherited from the application-spa and REST vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`store`, `dataStore`, `db`, `dbEngine` are all wrong when `persistenceStore` already exists; `schemaMigrations`, `dbMigrations`, `migrations` are all wrong when `migrationDiscipline` already exists).
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 5101-5111 sit at the LOW end of the 5101-5899 band on purpose. A project-side story that mechanically derives from `persistence-data-sqlite-REQ-011` into the number `5111` would collide against persistence-data-sqlite-US-5111 in this package; the band leaves headroom at the HIGH end (US 5181-5899) so a project's own stories anchored to persistence-data-sqlite REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `persistenceStore` exactly as spelled here when your blueprint holds an opinion on the project's primary durable store engine; contribute your own scope:global ADR on that string and let composition surface the pairing. A Postgres-first blueprint (see the persistence guide 'when it does not fit') will conflict here by design.
+- Reuse `migrationDiscipline` exactly as spelled here when your blueprint holds an opinion on schema evolution; a blueprint that contributes an event-sourced projection story or a dual-write pattern conflicts here by design.
+- This blueprint's decision states the SQLite single-file engine plus the forward-only numbered-catalog discipline. Compose compatible caching, outbox, or projection blueprints, or expect the operator to supersede with one project-level ADR per topic.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `messageSerialisation` and `deliverySemantics` (a message-consumer blueprint's natural globals), `caching` (unclaimed by application-spa, application-api-rest, security-auth-magic-link, and this blueprint). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.