rcf-lite 0.11.0 → 0.13.0

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` |
+| ci-pipeline | 6101-6899 | 7xx | shipped v1.0.0 | `ciGates`, `strictCoverageGate` |
+| 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.

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

@@ -0,0 +1,69 @@
+# Persistence blueprint guide
+
+## What it is
+
+A default durable-store floor for small greenfield rcf-lite projects. The blueprint contributes the WHAT of a persistence pattern: how the store gets opened, how the schema evolves, how migrations apply, how a mid-migration crash is handled, how the store event log looks, how the boundary between the domain and the engine is drawn, and how backups are taken. The default engine is a single SQLite file in WAL mode; Postgres is a documented future variant behind the same facade.
+
+Concretely, the blueprint ships eleven requirements, eleven user stories (twenty-five acceptance criteria), four architecture components, and five architecture decision records. Two ADRs are `scope: global` on the topics `persistenceStore` (the engine choice) and `migrationDiscipline` (the forward-only refuse-newer-at-open posture); the other three are scope-local operational ADRs (event secrecy, store-boundary discipline, backup model) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a domain schema. The tables the project's own entities live in are project-authored, on top of the migration catalog the project maintains. The blueprint governs the store facade and the migration discipline; the domain shape is the project's own responsibility.
+
+Not an ORM. There is no query builder, no active-record layer, no framework-shaped abstraction between the facade's named verbs and the engine binding. Projects that want an ORM wire it inside the facade's implementation and preserve the outward verb surface.
+
+Not a Postgres blueprint. A future `persistence-postgres` blueprint (see 'when it does not fit') will contribute a Postgres-flavoured store TAC and an ADR on `persistenceStore` that deliberately conflicts with this one; until then, projects that need Postgres supersede ADR-601 with a project-level ADR.
+
+Not a logical dump story. Backups are file-level engine-native snapshots. Cross-engine migration and portable dumps are out of scope; projects that need them layer a dump runner beside the file-level backup runner.
+
+Not a connection pool. The facade holds one handle for the process lifetime. Projects that select an engine that benefits from a pool (Postgres) wire it inside the facade and preserve the outward interface.
+
+Not a replication story. Cross-region replication and hot standbys are engine-native decisions a project makes on top of the file-level backup story; the blueprint's backup runner does not orchestrate them.
+
+## When to reach for it
+
+Reach for the persistence-data-sqlite blueprint when:
+
+- The project is a small greenfield rcf-lite deployment (single deployable, one small team, one host or a small container fleet, no ops team standing by).
+- The domain has a natural relational shape (bounded set of entities with well-defined relationships) that SQL expresses cleanly.
+- Zero-infrastructure persistence is a feature (no database server to run, no connection pool to size, no network round trip between the process and the store).
+- The scale envelope is single-writer (concurrent writers negotiate through the same process, not across processes on different hosts) and the working set fits on the same host the process runs on.
+- The recovery story that fits is 'copy the file to safe storage, point a compatible build at the copy'; downtime-free file-level backup is the primary recovery path.
+
+## When it does not fit
+
+Do not reach for the persistence-data-sqlite blueprint when:
+
+- Multi-writer scale across hosts, hot standby replication, or cross-region durability are project requirements. A `persistence-postgres` blueprint (unshipped at v1.0.0, promotion signal: the third project asks for it) will own this. Until then, a project with these needs supersedes ADR-601 with a project-level ADR selecting the alternate engine and rewrites the migration catalog into the alternate dialect. The store facade contract, the migration runner contract, and the backup runner contract are preserved.
+- The working set is genuinely too large for a single host to hold with reasonable performance (tens of gigabytes of hot data, hundreds of writes per second sustained). At that scale the single-writer envelope becomes an operator experience problem, and Postgres (or the engine ADR-601 promotes) is the more defensible shape.
+- The domain shape is genuinely non-relational (opaque blob storage, event streams, time-series with a fixed retention model). A different blueprint (a KV-store blueprint, an event-sourced blueprint, a time-series blueprint) owns those shapes; supersede with a project-level ADR and skip this blueprint.
+- The project has a hard requirement for a portable schema-agnostic dump as the primary backup (compliance mandate, cross-engine restore drill). File-level backup is the primary recovery path in ADR-605; projects that need the logical dump layer it on top, or supersede ADR-605 with a project-level ADR.
+- The deploy target does not have a persistent filesystem the SQLite file can live on (ephemeral containers with no volume mount, serverless functions). The blueprint assumes a stable path the file survives at across deploys; a project without that assumption picks a different engine.
+
+The design brief `w-2026-07-28-029` originally scoped store-selection separately from the persistence-data-sqlite blueprint. The persistence-data-sqlite blueprint at v1.0.0 does not include a Postgres engine variant because the rcf-lite blueprint mechanism (Phase 1) has no variant/profile selector: two engine TACs contributed together are both applied, and both leave dangling tacIds references if only one is realised. Shipping SQLite-first with Postgres as a documented promotion path mirrors the security-auth-magic-link blueprint's keycloak-local deferral (see the auth guide) and keeps v1.0.0 shippable. A future `persistence-postgres` blueprint plus a mechanism-side variant concept (v1.1 candidate) is the natural evolution.
+
+## What a good outcome looks like
+
+A project applies the persistence-data-sqlite blueprint on a fresh tree, wires its own domain migration entries into the catalog (starting at version 1), realises the four TACs in project-authored FBSes, and lands on a deployed application where:
+
+- The boot sequence opens the store once through the facade; the opened event fires with the configured store path; the schemaVersion read returns the catalog's max version.
+- A schema change ships as a new numbered entry in the catalog; the next deploy's boot fires a migrated event whose applied array contains exactly the new version; consumer code reads through the facade at the new schema.
+- A SIGKILL of the process while a write is in flight leaves the store openable on the next boot, with committed writes intact and the in-flight transaction rolled back; the opened event fires cleanly, no corruption error surfaces.
+- A rollback to an older build against a store the newer build wrote fails at boot with a stable-coded refuse-newer error naming both versions; the operator diagnoses in one step (the older build cannot run against the newer store) and redeploys the newer build.
+- A backup runs on a cron against the live store; the backupCheckpoint event fires on the sink with the artifact path and the completion timestamp; a fresh process opens the artifact and reads the rows committed at or before the completion timestamp.
+- The auth event log, the wire-request log, and every other domain log surface holds no store-lifecycle records; the store's event log holds no domain-row values.
+
+## Operator decisions that remain open after apply
+
+- Engine choice (SQLite default, Postgres or KV-store or event-sourced by superseding ADR-601). Blueprint owns the facade contract on both sides of the boundary; project owns the engine.
+- Migration catalog layout (one file or one file per migration, under the schema-samples reference). Blueprint owns the shape; project owns the layout choice at whatever history size feels comfortable.
+- Store path or connection string (the configuration input to the open entry point). Blueprint owns the entry point signature; project owns the deployed value and how it is supplied (env var, config file, container volume).
+- Domain schema (every table beyond the schemaVersion bookkeeping table). Blueprint owns the migration discipline; project owns the tables.
+- Backup schedule and destination (cron cadence, artifact path template, retention). Blueprint owns the backup runner and its event; project owns when and where.
+- Restore drill cadence (a backup you have not restored is a hope, not a backup). Blueprint owns the artifact shape; project owns proving it works.
+- Log sink implementation (where opened / migrated / backupCheckpoint / closed events go). Blueprint owns the event shape and the metadata-only discipline; project owns the shipper.
+- Facade verb catalogue (the named CRUD verbs the domain needs). Blueprint owns the boundary discipline (named verbs, no raw-query passthrough); project owns the verbs.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every boot pays the migration runner's cost (a single SELECT against the bookkeeping table on a routine boot; the full migration cost on a schema evolution boot). Every facade verb is a project-authored function; the boundary discipline means new query shapes are a two-file edit (facade plus consumer) instead of a scattered raw SQL fragment. Every schema change is a numbered entry the project must not edit after shipping (a shipped migration is a fact of production; a correction is a new migration). The refuse-newer property makes rollback deploys fail at boot rather than silently; that safety comes at the cost of ops running the older build against the older data (or accepting that a data-shape change is one-way). File-level backup is fast and cheap but engine-native; a project that needs a portable dump layers it on top and keeps both in sync. The store's event log is deliberately minimal; a project that needs richer per-operation events (row-level audit trail, hot-path timing) authors those on top of the facade's verbs, not inside the store event sink.

package/blueprints/security-auth-clerk/README.md

@@ -0,0 +1,50 @@
+# Security auth Clerk blueprint (v1.0.0)
+
+The tenth content blueprint on the rcf-build-lite blueprint mechanism, category `security`. A Clerk-committed sibling to `security-auth-magic-link` on the `authModel` global topic: Clerk hosts the identity surface (users, sessions, sign-in UX, credential storage, MFA, account recovery); the project owns a framework-agnostic middleware boundary, a session verifier confined to one module, a Clerk-claim-to-project-verb authorisation adapter, and a reduced principal shape the rest of the codebase reasons against. Targeted at small greenfield rcf-lite projects that want hosted identity without building the user-and-session surface themselves; larger deployments supersede the vendor by superseding ADR-1001 with a project-level ADR and swapping the middleware and verifier adapters.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/security-auth-clerk
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry grouped under the `security` category; `rcf define blueprint remove security-auth-clerk` cleanly removes an unreferenced application.
+
+Composing with `security-auth-magic-link` (or any other blueprint contributing `scope: global` on `authModel`, which includes `application-spa` and `application-api-rest`) raises a `globalAdrTopic` conflict at add time. The four documented resolutions apply (adopt the incoming, keep the existing, project-level supersede ADR, or `--resolve authModel=project:<ADR-id>` on the add). See `docs/topics.md` for the deliberate-conflict statement.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `security`, and the 29 contributions with scope/topic on the one global ADR |
+| Doc set | `contributions/` | 9 REQs, 11 USs (25 ACs), 4 TACs, 5 ADRs, all schema-valid and namespaced (`security-auth-clerk-REQ-001` prefix family; `ADR-1001-security-auth-clerk-auth-model` suffix family) |
+| React-family sample | `assets/wiring/clerk-provider-react.md` | The shape of a `ClerkProvider` wiring in a React-family client tier: where the provider mounts, what the SPA blueprint's session-and-redirect posture composes with |
+| Vue-family sample | `assets/wiring/clerk-provider-vue.md` | The same shape rendered for a Vue-family client tier so the operator can pattern-match without a framework translation step |
+| Middleware sample | `assets/middleware/node-middleware-shape.md` | The framework-agnostic middleware boundary contract (`verify(request)`), with adapter samples for Express and Fastify |
+| Role-claim mapping | `assets/authorisation/role-claim-mapping-sample.md` | A worked verb-to-role mapping-table example, with the reduction from Clerk's `org:role` claim shape into the project's `roles` array |
+| Guide | `guide/security-auth-clerk.md` | Operator-facing: when to use it, when not, the promotion signals for the OAuth2 and Keycloak siblings, the operator decisions that remain open, the cost-honesty paragraph |
+| Coordination vocabulary | `docs/topics.md` | The one global-topic string this blueprint contributes and the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, email-smtp-resend, persistence-data-sqlite, ci-pipeline, observability-essentials, security-secrets-management, security-auth-clerk) |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (Clerk-hosted identity, the `__session` cookie transport, the middleware boundary shape, the authorisation-adapter contract, the claims-mapping discipline, the session-lifecycle posture, the `signInStrategy` config surface, the read-only provisioning posture, the delegated rate-limit posture, the accountBound runtime-verify posture); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: a Clerk SDK version pin (the blueprint fixes the shape, not the version; the project's package manifest pins the SDK); MFA configuration (Clerk owns MFA at the hosted surface; the blueprint delegates); a Clerk-webhook consumer contract (out of scope for the default; a project that needs one adds one project-authored TAC and one scope-local ADR); a project-side user table or organisation table (Clerk is authoritative; a project that mirrors state into a local table does so through a project-authored consumer, not through this blueprint); a project-side rate limiter or anti-enumeration defence on the sign-in flow (Clerk-delegated per REQ-007); a fixed sign-in strategy choice (fixed shape per REQ-005, choice is project-owned); an OAuth2 provider list (that is the sibling `security-auth-oauth2` blueprint's territory when it ships); a Keycloak realm configuration (that is `security-auth-keycloak`'s territory when it ships).
+
+## The one global decision
+
+ADR-1001-security-auth-clerk-auth-model ships `scope: global` on topic `authModel`. This is the project's single decision on how identity is proven, where credentials live, and what the wire credential looks like. Composing with `security-auth-magic-link`, `application-spa`, `application-api-rest`, or any future `security-auth-*` blueprint conflicts here by design and expects a project-level ADR resolution. The composition-precedent (SPA + REST on `errorEnvelope` and `authModel`) is the same pattern.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, and the AC id band allocation (security-auth-clerk owns 9101-9899, ADR/TAC suffix block 10xx / 1001-1099; this is the first blueprint whose ADR/TAC suffix crosses into four digits).
+
+## Quality bar
+
+A framework-agnostic middleware boundary as the single point of authentication decision on the server; every runtime path that needs the caller's identity reads the reduced Principal shape attached at `request.auth`; the Clerk SDK is imported by exactly two modules (middleware wiring and session verifier); the wire credential is Clerk's `__session` cookie with Secure, HttpOnly, and SameSite=Lax; a tampered cookie is rejected with an audit event carrying no cookie value; every authorisation check goes through the adapter's `can` or `assert` and speaks in project verbs, never in Clerk role or claim vocabulary; role-based UI slots render only when the adapter grants the verb and the corresponding server-side handler enforces the same verb through `assert`; a Clerk-initiated sign-out invalidates subsequent requests within the documented `revocationCheckIntervalMs`; the sign-in surface applies no project-authored rate limiter (Clerk-delegated); user and organisation mutations against Clerk are confined to a provisioning script directory (not a request handler); the `signInStrategy` config surface fixes the shape not the choice; runtime-verify ACs are `accountBound` and skip with a stable-coded reason when Clerk is unreachable rather than passing on a fake. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+None at v1.0.0, given the same posture the security-secrets-management blueprint takes: every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable (cookie-jar inspection for the transport contract, `request.auth` shape inspection for the principal reduction, source-tree import scans for the Clerk-SDK boundary, `can` and `assert` return values for the authorisation adapter, page-render inspection for the UI-slot gating, live sign-out plus replay for the revocation behaviour, live rate-limit burst against Clerk for the delegation posture, and source-tree call-site scans for the read-only provisioning posture). The mechanism-reach principle from the authoring standard section 7 is satisfied at ship: a project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. The one operational surface a project must own is the middleware boundary implementation for its specific HTTP framework (an Express shim, a Fastify plugin, a Workers fetch wrapper) plus the vendor adapter inside the session verifier; those responsibilities are stated as TAC interfaces, not as smuggled runtime probes. Two ACs whose runtime observability depends on the operator's Clerk deployment reachability are AC-9107-2 (revocation propagation window) and AC-9109-2 (Clerk-documented rate-limit response shape): both are accountBound and the runtime-verify skip mechanism named on AC-9110-2 covers them when Clerk is unreachable.

package/blueprints/security-auth-clerk/assets/authorisation/role-claim-mapping-sample.md

@@ -0,0 +1,99 @@
+# Verb-to-role mapping sample
+
+A worked example of the project-authored mapping table the authorisation adapter (TAC-1002) consumes, plus a worked example of the claims-mapper reduction (TAC-1004) that turns Clerk's raw claim shape into the `Principal.roles` and `Principal.organisationIds` the adapter reasons against.
+
+## The mapping table
+
+The mapping table is a project-authored module the adapter loads once at construction. Verbs are project vocabulary; roles are the strings Clerk propagates. A verb absent from the table evaluates to `false` on `can` and throws on `assert`.
+
+```
+// src/authz/mapping-table.ts
+export const mappingTable = {
+  // Editorial workflow
+  'article.read':   { roles: ['reader', 'editor', 'admin'] },
+  'article.edit':   { roles: ['editor', 'admin'] },
+  'article.delete': { roles: ['admin'] },
+
+  // Billing surface
+  'billing.invoice.view': { roles: ['billing', 'admin'] },
+  'billing.invoice.void': { roles: ['admin'] },
+
+  // Admin dashboard
+  'admin.dashboard.view':  { roles: ['admin'] },
+  'admin.users.view':      { roles: ['admin'] },
+  'admin.users.impersonate': { roles: ['admin'] },
+};
+```
+
+## The claims-mapper reduction
+
+The claims mapper reads a raw Clerk claim bag (as returned by the session verifier on success) and produces the `Principal` the adapter reasons against. The `CLERK_CLAIM_KEYS` constant is the one place in the module that hard-codes Clerk-side claim key strings; a Clerk-side rename is a one-file change here.
+
+```
+// src/auth/claims-mapper.ts
+const CLERK_CLAIM_KEYS = {
+  userId: 'sub',                     // Clerk emits the user id on the JWT-standard sub claim
+  organisationMemberships: 'org_memberships',
+  organisationId: 'org_id',
+  organisationRole: 'org_role',
+  publicMetadata: 'public_metadata',
+  // Adjust these values against Clerk's currently-canonical claim vocabulary at
+  // the SDK version the project builds against.
+};
+
+export function reduceClaims(rawClaims) {
+  const principalId = rawClaims?.[CLERK_CLAIM_KEYS.userId];
+  if (!principalId || typeof principalId !== 'string') {
+    const err = new Error('PRINCIPAL_REDUCTION_FAILED: missing or invalid user id claim');
+    err.code = 'PRINCIPAL_REDUCTION_FAILED';
+    throw err;
+  }
+
+  const orgMemberships = rawClaims[CLERK_CLAIM_KEYS.organisationMemberships] ?? [];
+  const organisationIds = orgMemberships.map((m) => m[CLERK_CLAIM_KEYS.organisationId]);
+  const orgRoles = orgMemberships.map((m) => m[CLERK_CLAIM_KEYS.organisationRole]);
+
+  // Global roles (from publicMetadata.roles by convention) plus per-org roles
+  // flatten into one bare-string roles array; the set membership is what the
+  // adapter reasons against.
+  const globalRoles = rawClaims?.[CLERK_CLAIM_KEYS.publicMetadata]?.roles ?? [];
+  const roles = Array.from(new Set([...globalRoles, ...orgRoles]));
+
+  return {
+    principalId,
+    roles,
+    organisationIds,
+    claims: rawClaims,
+  };
+}
+```
+
+## Downstream code speaks in verbs
+
+```
+// src/handlers/article-edit.ts
+import { assert } from '../authz/adapter';
+
+export async function handleArticleEdit(request, response) {
+  assert(request.auth, 'article.edit', { organisationId: request.body.organisationId });
+  // If assert did not throw, the caller is allowed.
+  // Proceed with the edit.
+}
+```
+
+Never:
+
+```
+// ANTI-PATTERN: bypasses the adapter, reads Clerk vocabulary in a handler.
+if (request.auth.roles.includes('editor') || request.auth.roles.includes('admin')) {
+  // ...
+}
+```
+
+The scan on AC-9104-3 catches the anti-pattern; the discipline is that every check goes through `can` or `assert`.
+
+## Notes
+
+- The mapping table is small enough at project boot that adding a verb is a one-line edit; a project whose table grows past a hundred verbs is signal to consolidate at a coarser verb grain, not to bypass the adapter.
+- The organisation-scoping subject shape (`{ organisationId }` on the second argument of `assert`) is the blueprint's default. Projects that need finer subject shapes (record-owner predicates, hierarchical org trees) layer them above the adapter's return value rather than replacing the adapter.
+- The `publicMetadata.roles` convention above is one of several ways to propagate global roles from Clerk into the session; the specific convention is a Clerk-configuration choice the operator makes on the Clerk dashboard, and the claims mapper adjusts accordingly.