rcf-lite 0.21.0 → 0.22.0

package/blueprints/persistence-data-postgres/contributions/tacs/tac-2804-persistence-data-postgres-recovery-runner.json

@@ -0,0 +1,40 @@
+{
+  "tacId": "TAC-2804-persistence-data-postgres-recovery-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Postgres scheduled-export runner",
+  "purpose": "The scheduled export runner that drives pg_dump against the live database, writes the artefact to the elicited destination, and emits backupExported with the artefact path and completion timestamp. Pairs with the deploy target's own point-in-time recovery on ADR-2804; the runner covers the portable-artefact half of the two-path recovery model.",
+  "responsibilities": [
+    "Invoke pg_dump via child_process.execFile against the elicited connection URL with an elicited pg_dump argument set (default: --no-owner --no-acl --format=plain) (AC-27105-1).",
+    "Stream the pg_dump stdout to a temporary file, atomically rename to the elicited destination path (a filesystem path in the shipped fixture; an operator-owned path in production) (AC-27105-1).",
+    "On successful completion, emit backupExported on the injected event sink with { artefactPath, completedAt } (AC-27105-1).",
+    "On pg_dump non-zero exit, emit backupExportFailed with the exit code and stderr tail, delete the partial temp file, exit non-zero.",
+    "Cadence is elicited (a cron string, a systemd timer spec, or off for CI-only invocation); the runner does not schedule itself; a project-side scheduler invokes it."
+  ],
+  "internalStructure": "One Node module exporting an exportDatabase({ connectionUrl, destination, onEvent, pgDumpArgs }) async function. The module resolves pg_dump on PATH via child_process.execFile, streams stdout to a temp file inside the destination's directory, and atomically renames on success. The recovery-drill helper in the same module invokes exportDatabase, brings up a fresh Postgres via docker compose or podman, streams the artefact into psql, and compares row-count and checksum on both databases.",
+  "interfaces": [
+    {
+      "name": "exportDatabase",
+      "kind": "read-write-api",
+      "description": "await exportDatabase({ connectionUrl, destination, onEvent, pgDumpArgs }) -> { artefactPath, completedAt }. Runs pg_dump, writes the artefact, fires backupExported."
+    },
+    {
+      "name": "recoveryDrill",
+      "kind": "read-write-api",
+      "description": "await recoveryDrill({ sourceUrl, destination, onEvent }) -> { count, checksum }. Runs exportDatabase, primes a fresh Postgres from the artefact, compares row-count and checksum on the fixture table, fires recoveryDrillPassed."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Postgres facade",
+      "kind": "tac",
+      "tacId": "TAC-2801-persistence-data-postgres-facade",
+      "description": "Shares the facade's event sink for backupExported and recoveryDrillPassed."
+    }
+  ],
+  "tradeoffs": "child_process.execFile against pg_dump requires the pg_dump binary to be on PATH (or a full path passed via config). On a container platform the runner ships a Postgres client image alongside the app for pg_dump availability; the guide names the CI-seam pattern. The runner does not implement WAL-shipping or a streaming backup; that path is the deploy target's own PITR obligation on ADR-2804.",
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27101.json

@@ -0,0 +1,34 @@
+{
+  "usId": "persistence-data-postgres-US-27101",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One facade module opens a pg.Pool on boot and emits facadeReady with the database name",
+  "asA": "developer whose Node process needs a durable Postgres store behind a swappable boundary",
+  "iWant": "one facade module to hold the pg client and expose named domain verbs, with a facadeReady lifecycle event on the first successful pool ready-check",
+  "soThat": "the boundary between the domain and the pg vendor surface is the only place that has to move when the driver changes and the boot ordering is observable via the event",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27101-1",
+      "description": "On process boot, the facade opens a pg.Pool against the elicited connection URL; once the first successful pool ready-check completes, a facadeReady event fires on the injected event sink carrying the database name.",
+      "given": "a Node process with the facade module imported and its factory invoked",
+      "when": "the process boots and the facade's pool ready-check returns",
+      "then": "a facadeReady event fires on the injected event sink with a payload containing databaseName, and the pool is ready to accept queries; the facade exposes named domain verbs and does not re-export the raw pg client",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-27101-2",
+      "description": "Exactly one source-tree module inside the facade directory imports pg; every other module in the applied project's source tree that touches persistence imports the facade and calls its named domain verbs, verified by a targeted grep on the applied fixture.",
+      "given": "the applied project's source tree after apply",
+      "when": "grep 'from \\'pg\\'' or grep 'require(\\'pg\\')' walks the tree outside the facade directory",
+      "then": "no match is found outside the facade directory; the facade's public surface exports named domain verbs only, no raw pg reference",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27102.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27102",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Numbered forward-only .sql migrations apply one file one transaction; schema_version advances",
+  "asA": "operator who needs deploys reproducible from a git ref with no schema state outside version control",
+  "iWant": "every schema change to be a new numbered .sql file under the elicited migrations directory, applied by the in-tree runner one file at a time inside its own transaction",
+  "soThat": "the schema shape at any deployed version can be read from committed files, each apply either commits or leaves the schema exactly as it was, and the schema_version bookkeeping table is the one source of truth on what has been applied",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27102-1",
+      "description": "Given a fresh Postgres database at schema_version 0 and three numbered forward-only .sql migration files (001, 002, 003), when the migration runner opens the store and applies them, then each file applies inside its own transaction (BEGIN, file body, COMMIT), a migrationsApplied event fires with the applied filename list, and the schema_version bookkeeping table records three rows keyed by filename.",
+      "given": "a fresh Postgres instance and a migrations directory with 001_*.sql, 002_*.sql, 003_*.sql each a single statement inside an implicit transaction",
+      "when": "the migration runner applies the directory against the database",
+      "then": "each file runs inside a BEGIN/COMMIT pair; after all three succeed a migrationsApplied event fires with the filename list ['001_*.sql', '002_*.sql', '003_*.sql'] and the schema_version table (or the runner's configured bookkeeping table name) carries a row per applied filename",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2802-persistence-data-postgres-migration-runner"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27103.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27103",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every pg.query call site inside the facade passes a static string literal as its first argument",
+  "asA": "reviewer of an rcf-lite Postgres project auditing for SQL injection risk at the driver boundary",
+  "iWant": "an AST scan over the facade directory to prove every pg.query first argument is a static string literal with $N parameters, per the node-postgres parameterised-queries contract",
+  "soThat": "a call site that concatenates or template-literal-interpolates consumer values into SQL text is caught at build time before it ships",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27103-1",
+      "description": "An AST scan over every .ts/.js/.mjs file under the applied fixture's facade directory finds every call to pg.query and asserts each first-argument node is a StringLiteral (Literal node with a string value), not a TemplateLiteral, not a BinaryExpression whose operator is '+' with a string operand. Parameters are supplied as an array whose values bind to $1, $2, ... $N placeholders in the string.",
+      "given": "the applied fixture's src/store.mjs and any sibling module inside the facade directory",
+      "when": "a Node built-in AST parser walks every call expression whose callee is 'pg.query' or resolves to a method named 'query' on a pg.Client, pg.Pool, or pg.PoolClient reference",
+      "then": "every first-argument node is a Literal with typeof value === 'string'; no first-argument node is a TemplateLiteral or a string-concatenation expression",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27104.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27104",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Transaction helper rolls back on any statement error and fires transactionRolledBack with the failing index",
+  "asA": "developer whose domain requires atomic multi-statement writes",
+  "iWant": "a transaction helper that wraps BEGIN and COMMIT around a callback and issues ROLLBACK on any error",
+  "soThat": "no partial commit lands on the shipped database and the failing statement's index is observable on the event sink",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27104-1",
+      "description": "Given the transaction helper wrapping a callback that issues two INSERTs where the second violates a UNIQUE constraint, when the helper runs, then client.query('BEGIN') is issued, the first INSERT lands on the transaction, the second INSERT throws a constraint error the helper catches, client.query('ROLLBACK') is issued, a transactionRolledBack event fires with statementIndex 1, the client is released back to the pool, and the underlying error is re-thrown to the caller. The database after rollback carries neither row from the aborted transaction.",
+      "given": "the facade's withTransaction helper, a table with a UNIQUE constraint on a column, and a callback issuing two INSERTs with the same value for that column",
+      "when": "await withTransaction(callback) runs",
+      "then": "BEGIN is issued, the first INSERT lands inside the transaction, the second INSERT throws, ROLLBACK is issued, transactionRolledBack fires on the event sink with { statementIndex: 1, code: '<pg error code>' }, the client is released, the promise rejects with the underlying error, and a subsequent SELECT against the table returns no rows from the aborted transaction",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2803-persistence-data-postgres-transaction-helper"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27105.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27105",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Scheduled pg_dump lands an artefact and a fresh Postgres primed from it round-trips the row set",
+  "asA": "operator responsible for restoring a Postgres project after a cluster loss or a data-integrity incident",
+  "iWant": "a scheduled export runner that drives pg_dump against the live database and writes an artefact to the elicited destination",
+  "soThat": "a fresh Postgres primed from the artefact returns the row set the source held at the artefact's completion timestamp",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27105-1",
+      "description": "Given a live Postgres containing a small fixture rowset, when the scheduled export runner runs, then it invokes pg_dump via child_process.execFile against the elicited connection URL, writes the artefact to the elicited destination, and emits backupExported with { artefactPath, completedAt }. A fresh Postgres primed by psql-restoring the artefact returns the same rowset (row count and row checksum both equal) as the source.",
+      "given": "a live Postgres seeded with a fixture rowset and the recovery runner configured to write to a temporary destination",
+      "when": "the recovery runner runs pg_dump against the source and a second Postgres is primed from the artefact",
+      "then": "the runner exits 0, backupExported fires with the artefact path and completion timestamp, the artefact file exists at the elicited destination, and a query against the restored Postgres returns the same row count and same checksum of the fixture rowset as the source",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2804-persistence-data-postgres-recovery-runner"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27106.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27106",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Two facades at pool size 5 handle twenty concurrent queries with no timeout",
+  "asA": "developer running a long-lived Node process with a warm pg pool",
+  "iWant": "the shipped pool defaults to handle a burst of twenty concurrent queries across two facade instances at pool size 5 without timing out",
+  "soThat": "the pool posture per deploy target is proven at the shape the shipped defaults name, not just at the single-query level",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27106-1",
+      "description": "Given two facade instances opened concurrently against the same Postgres at pool size 5 each, when twenty concurrent SELECT queries are issued across the two facades, then all twenty return with no timeout inside the shipped connectionTimeoutMillis (5000) and idleTimeoutMillis (30000) defaults, and the pool metric on each facade reports at most 5 in-use connections at any point.",
+      "given": "two facade instances opened against the same postgres:17-alpine container at pool size 5 each",
+      "when": "twenty SELECT queries are dispatched concurrently across the two facades via Promise.all",
+      "then": "all twenty promises resolve inside the connectionTimeoutMillis budget; no query throws; the observed maximum concurrent in-use pool connections on either facade is at most the configured pool size (5)",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27107.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27107",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-007",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Advisory-lock helper is elicited off by default; when enabled it wraps pg_advisory_lock or pg_advisory_xact_lock per the elicited scope",
+  "asA": "developer building a workflow that needs cross-process coordination on a shared Postgres",
+  "iWant": "an optional advisory-lock helper on the facade that acquires and releases a session-level or transaction-level lock per an elicited key",
+  "soThat": "cross-process ordering is expressible through the engine's own primitive without a bespoke locks table",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27107-1",
+      "description": "The elicited advisoryLockHelper parameter has one of three values (off, session, transaction) with default off; when off the facade does not expose the helper on its public surface. When session or transaction, the facade exposes a withAdvisoryLock(key, callback) verb that acquires pg_advisory_lock (session) or pg_advisory_xact_lock (transaction) with the integer key, runs the callback, and releases the lock via pg_advisory_unlock on the session-level shape; the transaction-level shape releases automatically at COMMIT or ROLLBACK per the Postgres explicit-locking reference.",
+      "given": "the facade's public surface after apply, with the advisoryLockHelper elicit answered on each of the three permitted values",
+      "when": "the surface is inspected and the helper is invoked with a valid integer key on a supported answer",
+      "then": "the surface exposes withAdvisoryLock only when the answer is session or transaction; the helper acquires the correct lock verb per the answer, runs the callback, and releases (session) or lets COMMIT release (transaction); the sidecar records the elicited answer for later validation",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27108.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27108",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Facade boot survives a first-connect race and does not double-emit facadeReady",
+  "asA": "developer whose process may issue queries against the facade before its pool's first ready-check completes",
+  "iWant": "the facade to serialise consumer queries behind the pool's ready-check without dropping any and to emit facadeReady exactly once per facade instance",
+  "soThat": "boot-time races do not surface as unhandled promise rejections and the ready event is not double-counted by an observability sink",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27108-1",
+      "description": "Given a facade instance and five concurrent domain-verb calls issued before the pool's first ready-check completes, when the pool becomes ready, then all five calls succeed against the pool once ready, the facadeReady event fires exactly once with the database name, and no consumer sees a NotReady error.",
+      "given": "a fresh facade instance and five concurrent getUserById calls issued immediately after construction",
+      "when": "the pool completes its first ready-check",
+      "then": "all five calls resolve successfully; facadeReady fires exactly once on the event sink; no unhandled rejection is raised",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27109.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27109",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A failing migration rolls back its own transaction and the runner exits non-zero without advancing schema_version",
+  "asA": "operator running migrations at boot on a long-lived Node process",
+  "iWant": "a failing migration to roll back its own transaction and stop the runner with a non-zero exit and the failing filename in the diagnostic",
+  "soThat": "the runner never leaves a partially-applied migration on the database and the operator can name the failing file to un-jam the deploy",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27109-1",
+      "description": "Given a migrations directory whose second file contains an invalid SQL statement (simulated in the fixture by the SIMULATE_MIGRATION_FAILURE switch), when the migration runner runs, then the first file commits, the second file's transaction rolls back on the invalid statement, the runner exits non-zero, and the failing filename appears in the runner's diagnostic output. The schema_version bookkeeping table records only the first file's row.",
+      "given": "a Postgres at schema_version 0 and three migration files where the second is intentionally broken",
+      "when": "the migration runner applies the directory with SIMULATE_MIGRATION_FAILURE=true",
+      "then": "the first file's transaction commits and its row lands in the bookkeeping table; the second file's transaction rolls back; the runner exits non-zero with the failing filename in its stderr; the third file is not attempted; the bookkeeping table shows exactly one applied row",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2802-persistence-data-postgres-migration-runner"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/contributions/user-stories/persistence-data-postgres-us-27110.json

@@ -0,0 +1,25 @@
+{
+  "usId": "persistence-data-postgres-US-27110",
+  "prdId": "PRD-001",
+  "reqId": "persistence-data-postgres-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A recovery drill primes a fresh Postgres from the pg_dump artefact and the row-count and checksum match the source",
+  "asA": "operator running a recovery drill on a schedule to prove the pg_dump path works",
+  "iWant": "the drill to prime a fresh Postgres from the artefact and compare the restored dataset against the source by row-count and checksum",
+  "soThat": "the recovery path is proven end to end and drift on the artefact shape is caught before an incident forces a live restore",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-27110-1",
+      "description": "Given a live Postgres with a fixture rowset and a pg_dump artefact produced by the scheduled runner, when the drill primes a fresh Postgres from the artefact and computes the row-count and checksum of the fixture table on both databases, then the row-count and checksum on the restored Postgres equal those on the source and a recoveryDrillPassed event fires on the event sink carrying the two matched values.",
+      "given": "a source Postgres seeded with a fixture rowset and a pg_dump artefact at the elicited destination",
+      "when": "the drill primes a fresh Postgres from the artefact and runs SELECT count(*) and a checksum aggregate on the fixture table against both databases",
+      "then": "the two counts are equal; the two checksums are equal; recoveryDrillPassed fires on the event sink with { count, checksum }; the fresh Postgres and its artefact primer are torn down on exit",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-2804-persistence-data-postgres-recovery-runner"],
+  "createdAt": "2026-09-06T15:47:00.000Z",
+  "updatedAt": "2026-09-06T15:47:00.000Z"
+}

package/blueprints/persistence-data-postgres/docs/topics.md

@@ -0,0 +1,64 @@
+# persistence-data-postgres blueprint coordination vocabulary
+
+This file is the persistence-data-postgres 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-postgres contribution | Origin | Composition note |
+|---|---|---|---|
+| `persistenceStore` | ADR-2801-persistence-data-postgres-driver | Reused from persistence-data-sqlite and persistence-data-d1 (both contribute the same topic string). This blueprint contributes a Postgres store on the same topic string on purpose. | The one project-wide decision on the primary durable store engine. Composing this blueprint with persistence-data-sqlite or persistence-data-d1 conflicts here by design; expected resolution is one project-level ADR that fixes the engine end to end |
+| `migrationDiscipline` | ADR-2802-persistence-data-postgres-migration-shape | Reused from persistence-data-sqlite (boot-time forward-only runner discipline) and persistence-data-d1 (wrangler-CLI-owned deploy-pipeline discipline). This blueprint contributes numbered forward-only .sql migrations applied by an in-tree runner one file one transaction. | The one project-wide schema-evolution discipline. Composing this blueprint with persistence-data-sqlite or persistence-data-d1 conflicts here by design; expected resolution is one project-level ADR |
+
+The persistence-data-postgres blueprint claims two global topics. Every other contribution is scope-local (ADR-2803 runner mode, ADR-2804 recovery, ADR-2805 connection-pool posture do not contribute global topics; a composing blueprint that holds an opinion on any of them authors its own project-level ADR).
+
+Note on the round-6 reserved Hyperdrive adapter slot: the v1.0.0 facade holds the driver reference OPAQUE at ADR-2801 boundary so the round-6 v1.1.0 Hyperdrive adapter slots in as an additive minor without a topic conflict. See infra round 5 spec section 5.7 for the reserved-slot register.
+
+Rules for new topics: lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer.
+
+## Id number bands (registry bootstrap)
+
+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 v2.0.0 | `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `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.1.0 | `healthProbes`, `readinessSemantics` |
+| observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
+| application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+
+US 27101-27110 sit at the LOW end of the 27101-27899 band on purpose (watchpost run-4 lesson). A project-side story mechanically derived from a persistence-data-postgres REQ id into the number 27110 would collide against the shipped US-27110; band headroom (27111-27899) leaves that space.
+
+Postgres suffixes for this blueprint use the 2801-2899 block, continuing the widening pattern (persistence-data-sqlite 6xx, persistence-data-d1 14xx, and persistence-data-postgres 28xx).
+
+## 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.
+- Reuse `migrationDiscipline` exactly as spelled here when your blueprint holds an opinion on schema evolution.
+- Round-6 reserved slot: the Hyperdrive adapter inside `persistence-data-postgres` v1.1.0 wraps the same facade contract with the Cloudflare Hyperdrive connection-pool and query-cache surface. No topic conflict, no facade re-shape; the driver reference is opaque at the ADR-2801 boundary.
+
+## Deliberate-conflict statement
+
+This blueprint's ADR-2801 on `persistenceStore` and ADR-2802 on `migrationDiscipline` are a Postgres-committed vendor sibling to persistence-data-sqlite (ADR-601, ADR-602) and persistence-data-d1 (ADR-1401, ADR-1402) on the same two topic strings. Applying two of the three on one project raises two `globalAdrTopic` conflicts the operator resolves via one of the four documented resolutions per topic (adopt one, keep the existing one, author a project-level supersede ADR, or `--resolve <topic>=project:<ADR-id>` on the add).

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

@@ -0,0 +1,172 @@
+# persistence-data-postgres guide
+
+## What this blueprint gets you
+
+Postgres as your project's primary durable relational store on any server-tier deployment (a long-lived Node process, a container platform, a non-Workers serverless target). The store facade is the sole reader of the `pg` (node-postgres) client in your source tree; consumer code calls named domain verbs on the facade and never touches `pg` directly. Schema evolution is numbered forward-only `.sql` files applied one file per transaction; a `schema_version` bookkeeping table is the single source of truth on what has been applied. Multi-statement writes with atomicity go through a transaction helper that wraps `BEGIN` and `COMMIT` around a callback and rolls back on any error. Recovery is two-path: a scheduled `pg_dump` artefact plus the deploy target's own point-in-time recovery. The v1.0.0 facade holds the driver reference opaque at the ADR-2801 boundary so the round-6 Hyperdrive v1.1.0 adapter slots in as an additive minor without a facade re-shape.
+
+## Apply this blueprint
+
+```sh
+rcf define blueprint add persistence-data-postgres
+```
+
+On a fresh project this applies cleanly. On a project that already applied `persistence-data-sqlite` or `persistence-data-d1`, `rcf define blueprint add persistence-data-postgres` surfaces a DELIBERATE conflict on the `persistenceStore` and `migrationDiscipline` global-ADR topics. Resolve with one project-level ADR per topic; the operator picks the engine end to end.
+
+## Facade shape
+
+```js
+import { createStore } from './store.mjs';
+
+const store = createStore({
+  connectionUrl: process.env.DATABASE_URL,
+  onEvent: (evt) => logger.info(evt),
+  poolConfig: { max: 10 },
+});
+
+await store.ready();
+const id = await store.createUser('alice', 'alice@example.com');
+const row = await store.getUserById(id);
+```
+
+The facade opens a `pg.Pool` against the elicited connection URL and emits `facadeReady` exactly once on the first successful ready-check. Every `.query` call passes a static string literal as its first argument with parameters as `$1, $2, ... $N` per the node-postgres parameterised-queries contract at https://node-postgres.com/features/queries. Consumers destructure the verbs they need at their top level and hold the facade reference for the process lifetime (or, on a request-scoped container platform, for the request lifetime).
+
+## Migrations
+
+Numbered forward-only `.sql` files under an elicited `migrations/` directory. Each filename begins with a monotonic integer (`001_...`, `002_...`, `003_...`); the file body is engine-native SQL. The in-tree runner (TAC-2802) applies each file inside its own transaction and records the applied filename in `schema_version`.
+
+```sh
+node src/migrate.mjs
+```
+
+Which runner tool the project reaches for is elicited on ADR-2802 (bespoke Node runner is the shipped default; `node-pg-migrate`, `sqitch`, and `flyway` are named alternatives). Every runner honours the same discipline: numbered forward-only files, one file one transaction, a `schema_version` bookkeeping row per applied file.
+
+Runner mode is elicited on ADR-2803:
+
+- `atBoot` (default for long-lived Node): the facade invokes the runner on process start before opening the first query.
+- `ciStep` (default for Workers-adjacent or request-scoped container targets): the CI pipeline invokes the runner as a deploy step against the target's own connection before the artefact promotes.
+
+## Transactions
+
+```js
+await store.withTransaction(async (tx) => {
+  await tx.query('INSERT INTO orders(user_id, total) VALUES ($1, $2)', [userId, total]);
+  await tx.query('INSERT INTO order_lines(order_id, sku, qty) VALUES ($1, $2, $3)', [orderId, sku, qty]);
+});
+```
+
+The helper wraps `BEGIN` and `COMMIT` around the callback. If any statement throws, the helper issues `ROLLBACK`, fires `transactionRolledBack` with the failing statement's zero-based index and the pg error code, and re-throws the underlying error. No partial commit lands on the shipped database.
+
+## Recovery
+
+Two paths, both required:
+
+```js
+import { exportDatabase, recoveryDrill } from './recovery.mjs';
+
+const { artefactPath, completedAt } = await exportDatabase({
+  connectionUrl: process.env.DATABASE_URL,
+  destination: process.env.BACKUP_DESTINATION,
+  onEvent: (evt) => logger.info(evt),
+});
+```
+
+Scheduled `pg_dump` runs on your project's cadence (an elicited cron string, a systemd timer spec, or off for CI-only invocation); the runner writes the artefact via `child_process.execFile` and emits `backupExported` on completion. The deploy target's own point-in-time recovery is enabled with an elicited retention window; on a managed cluster, the window is the cluster's PITR setting; on a self-managed cluster, the WAL-archive retention.
+
+Run a periodic recovery drill (US-27110):
+
+```js
+const { count, checksum } = await recoveryDrill({
+  sourceUrl: process.env.DATABASE_URL,
+  destination: process.env.BACKUP_DESTINATION,
+  onEvent: (evt) => logger.info(evt),
+});
+```
+
+The drill primes a fresh Postgres from the artefact and compares row-count and checksum on a fixture table on both databases; a mismatch signals artefact-shape drift before an incident forces a live restore.
+
+## Pool posture per deploy target
+
+Elicited on ADR-2805:
+
+- `longLivedNode` (default): long-lived `pg.Pool` for the process lifetime; shipped defaults pool size 10, `idleTimeoutMillis 30000`, `connectionTimeoutMillis 5000`.
+- `requestScopedContainer`: a pool sized to the request budget, disposed at request end; shipped defaults pool size 2, `idleTimeoutMillis 5000`, `connectionTimeoutMillis 3000`.
+- `hyperdriveManaged` (reserved for the round-6 v1.1.0 adapter): inherits Hyperdrive's own pool settings and holds no Node-side pool.
+
+Every default is overridable by the operator via elicited pool-config fields at apply time.
+
+## Advisory-lock helper (optional)
+
+Elicited on REQ-007 default `off`. When enabled to `session` or `transaction`, the facade exposes `withAdvisoryLock(key, callback)` that acquires and releases a session-level (via `pg_advisory_lock` / `pg_advisory_unlock`) or transaction-level (via `pg_advisory_xact_lock`; released automatically at COMMIT or ROLLBACK) lock per https://www.postgresql.org/docs/current/explicit-locking.html.
+
+Session-level locks survive rolled-back transactions; use `transaction` for the common case and pick `session` only when cross-transaction locking is the intent.
+
+## CI seam (GitHub Actions service containers)
+
+Add a `services:` block declaring `postgres:17-alpine` to your workflow. Per https://docs.github.com/en/actions/using-containerized-services/about-service-containers, the runner exposes the service either at the label hostname (for container-hosted jobs) or at the mapped port (for host-runner jobs); both patterns are supported.
+
+Container-hosted job (hostname exposure):
+
+```yaml
+jobs:
+  postgres-integration:
+    runs-on: ubuntu-latest
+    container: node:24
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: rcf
+          POSTGRES_PASSWORD: rcf-dev-only
+          POSTGRES_DB: rcf_test
+        options: >-
+          --health-cmd "pg_isready -U rcf -d rcf_test"
+          --health-interval 2s
+          --health-timeout 3s
+          --health-retries 20
+    steps:
+      - uses: actions/checkout@v4
+      - run: pnpm install --frozen-lockfile
+      - run: node src/migrate.mjs
+        env:
+          DATABASE_URL: postgres://rcf:rcf-dev-only@postgres:5432/rcf_test
+```
+
+Host-runner job (port mapping):
+
+```yaml
+jobs:
+  postgres-integration:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: rcf
+          POSTGRES_PASSWORD: rcf-dev-only
+          POSTGRES_DB: rcf_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U rcf -d rcf_test"
+          --health-interval 2s
+          --health-timeout 3s
+          --health-retries 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: pnpm install --frozen-lockfile
+      - run: node src/migrate.mjs
+        env:
+          DATABASE_URL: postgres://rcf:rcf-dev-only@localhost:5432/rcf_test
+```
+
+Adding this seam is the applying project's concern per `delivery-ci-workflows` v2.2.0. The `delivery-ci-workflows` blueprint's alternate-provider four-point mapping (job trigger, Node setup, entry-point invocation, artefact upload) covers non-GHA CI targets against the same `postgres:17-alpine` image.
+
+## What this blueprint does not do
+
+- It does not choose an ORM. Kysely, Drizzle, Prisma, or your team's own module sits inside the facade at operator choice; the outward interface stays orm-neutral.
+- It does not build the Hyperdrive adapter. That is a round-6 v1.1.0 additive minor; the v1.0.0 facade holds the driver reference opaque at ADR-2801 so the minor slots in without a facade re-shape.
+- It does not schedule the recovery runner. Cadence is elicited (a project-side cron string, a systemd timer, or off for CI-only); a project-side scheduler invokes `exportDatabase`.
+- It does not choose a migration tool. Numbered forward-only `.sql` files with one file one transaction is the discipline; the tool is elicited.

package/blueprints/persistence-data-sqlite/docs/topics.md

@@ -31,7 +31,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | 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 v2.0.0 | `statusPageContract` |
-| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `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` |
@@ -43,6 +43,13 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
 | application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
 | application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
 
 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.
 

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

@@ -1,5 +1,9 @@
 # security-auth-clerk CHANGELOG
 
+## 1.3.0 (visual round T-4, spec 2026-09-06 section 5.4.2, Baz Q2 default)
+
+- Declares `capabilities: [principalDirectory, roleModel, sessionInventory, hostedIdentityUi]` on `blueprint.json`. Additive per section 6 of `blueprint-authoring.md` (an additive optional field with no global-topic change is a minor bump). Consumed at apply time by the visual round T-4 `application-account-settings` blueprint to gate the sessions surface (probe pack check `AC-25106-1`) and the security surface hosted-UI branch (`AC-25105-1`). Clerk exposes an inventory of active sessions with device labels and a terminate action, and hosts identity screens (sign-in, sign-up, account, security) that a link-out or embed can consume.
+
 ## 1.2.0 (visual round T-5, spec 2026-09-04 section 5.5.2, Baz Q2 default)
 
 - Declares `capabilities: [principalDirectory, roleModel]` on `blueprint.json`. No other change. The new field is additive per section 6 of `blueprint-authoring.md` (an additive optional field with no global-topic change is a minor bump), and it is consumed by the visual round T-5 `application-admin-console` blueprint at apply time to gate surfaces on what the applied identity blueprint actually provides.

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

@@ -2,6 +2,9 @@
 
 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.
 
+
+> Latest: **v1.3.0** (visual round T-4, 2026-09-06). `capabilities: [principalDirectory, roleModel, sessionInventory, hostedIdentityUi]`. See [CHANGELOG.md](CHANGELOG.md).
+
 ## Apply
 
 ```