rcf-lite 0.25.0 → 0.27.0

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

@@ -1,12 +1,28 @@
+# Changelog
+
+## 1.1.2 - 2026-09-10
+
+Dimension-d single-definition-ownership cleanup on REQ-004: REQ description now references the transaction-helper interface owned on TAC-2803.interfaces.withTransaction rather than restating the driver control literals for begin, commit and rollback. Chain-consistency lint zero on pass 1 and pass 2.
+
+## 1.1.1 (register-sweep patch, 2026-09-10)
+
+- Register: neutral wording in shipped prose (no capability change).
+
+## 1.1.0 - 2026-09-09
+
+Adds the elicits block (connection-url, migrations-directory, migration-runner-tool, runner-mode, pool-size, idle-timeout-ms, connection-timeout-ms, recovery-destination, recovery-cadence, pitr-provider, advisory-lock-helper) that the REQs and guide were already describing in prose; each option is named in the description of the must-priority REQ that governs its runtime clause. Adds a runtime clause naming the relationalStore applied capability on REQ-001. Adds deliveredBy on REQ-003, REQ-005 and REQ-007. Adds ownerRef on AC-27104-1 (withTransaction). Adds disposition to every AC.
+
 # persistence-data-postgres changelog
 
 ## 1.0.0 - 2026-09-06
 
-Initial release. Contract for Postgres as the project's primary durable relational store on a server-tier deployment (Node process, container, non-Workers serverless), accessed through a store facade module that is the sole reader of the `pg` client. Landed via the infra round 5 spec (ratified 2026-09-06) as track T-1.
+Initial release. Contract for Postgres as the project's primary durable relational store on a server-tier deployment (Node process, container, non-Workers serverless), accessed through a store facade module that is the sole reader of the `pg` client. Landed via the infra round 5 spec (ratified 2026-09-06).
 
 - 26 contributions: 7 REQs on facade / migrations / prepared statements / transactions / recovery / pool posture / advisory-lock helper; 10 USs at 27101-27110; 4 TACs (2801 facade, 2802 migration runner, 2803 transaction helper, 2804 recovery runner); 5 ADRs (2801 driver with scope global on `persistenceStore`, 2802 migration shape with scope global on `migrationDiscipline`, 2803 runner mode, 2804 recovery, 2805 connection-pool posture).
-- Six Node-only probes under `contributions/probes/` proven against a live `postgres:17-alpine` container: `facade-round-trip`, `migration-apply`, `prepared-statement-scan`, `transaction-atomicity`, `recovery-restore-round-trip`, `pool-posture-smoke`. None account-bound; Postgres is local-first per Baz decision 8.
+- Six Node-only probes under `contributions/probes/` proven against a live `postgres:17-alpine` container: `facade-round-trip`, `migration-apply`, `prepared-statement-scan`, `transaction-atomicity`, `recovery-restore-round-trip`, `pool-posture-smoke`. None account-bound; Postgres is local-first per maintainer decision.
 - Sample-app fixture at `packages/rcf-lite/test/fixtures/infra-postgres/` boots `postgres:17-alpine` via docker compose, applies three toy forward-only `.sql` migrations, exposes the facade over `pg`, and hosts `SIMULATE_MIGRATION_FAILURE` and `SIMULATE_CONSTRAINT_VIOLATION` switches for the negative-run probe paths.
 - Declares `capabilities: ["relationalStore"]`, `suggestedCompanions: [{role: "logging"}, {role: "errorHandling"}]`, `providesRoles` absent, `requiresAppliedCapabilities` absent.
 - Reserves the round-6 Hyperdrive v1.1.0 adapter slot at ADR-2801 by keeping the driver reference opaque at the facade boundary.
 - Advisory-lock helper (REQ-007) ships in v1.0.0 as elicited with default `off` per the ratified Q1 answer on infra round 5 spec section 10.
+
+Review-fix (2026-09-09): Adds eleven option-binding ACs to close section 7c on the elicits catalogue - migration-runner-tool (AC-27102-4/5/6/7), runner-mode (AC-27102-8/9), recovery-cadence (AC-27105-3/4/5), pitr-provider (AC-27110-3/4). Adds deliveredBy on REQ-001, REQ-002, REQ-004 (three of seven mandatory REQs).

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

@@ -63,7 +63,7 @@ Each probe is a Node module under `contributions/probes/` exporting the round-5
 | `recovery-restore-round-trip` | AC-27105-1 | `pg_dump` artefact primes a fresh Postgres; row-count and checksum equality |
 | `pool-posture-smoke` | AC-27106-1 | Two facades at pool size 5 handle twenty concurrent queries with no timeout |
 
-None of the six probes carries `accountBound: true`; Postgres is local-first per infra round 5 spec Baz decision 8.
+None of the six probes carries `accountBound: true`; Postgres is local-first per infra round 5 spec maintainer decision.
 
 ## How to run the probes locally
 

package/blueprints/persistence-data-postgres/blueprint.json

@@ -1,8 +1,10 @@
 {
   "slug": "persistence-data-postgres",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "category": "persistence",
-  "capabilities": ["relationalStore"],
+  "capabilities": [
+    "relationalStore"
+  ],
   "suggestedCompanions": [
     {
       "role": "logging",
@@ -14,27 +16,111 @@
     }
   ],
   "contributions": [
-    { "id": "persistence-data-postgres-REQ-001", "kind": "req", "path": "requirements/persistence-data-postgres-req-001.json" },
-    { "id": "persistence-data-postgres-REQ-002", "kind": "req", "path": "requirements/persistence-data-postgres-req-002.json" },
-    { "id": "persistence-data-postgres-REQ-003", "kind": "req", "path": "requirements/persistence-data-postgres-req-003.json" },
-    { "id": "persistence-data-postgres-REQ-004", "kind": "req", "path": "requirements/persistence-data-postgres-req-004.json" },
-    { "id": "persistence-data-postgres-REQ-005", "kind": "req", "path": "requirements/persistence-data-postgres-req-005.json" },
-    { "id": "persistence-data-postgres-REQ-006", "kind": "req", "path": "requirements/persistence-data-postgres-req-006.json" },
-    { "id": "persistence-data-postgres-REQ-007", "kind": "req", "path": "requirements/persistence-data-postgres-req-007.json" },
-    { "id": "persistence-data-postgres-US-27101", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27101.json" },
-    { "id": "persistence-data-postgres-US-27102", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27102.json" },
-    { "id": "persistence-data-postgres-US-27103", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27103.json" },
-    { "id": "persistence-data-postgres-US-27104", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27104.json" },
-    { "id": "persistence-data-postgres-US-27105", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27105.json" },
-    { "id": "persistence-data-postgres-US-27106", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27106.json" },
-    { "id": "persistence-data-postgres-US-27107", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27107.json" },
-    { "id": "persistence-data-postgres-US-27108", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27108.json" },
-    { "id": "persistence-data-postgres-US-27109", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27109.json" },
-    { "id": "persistence-data-postgres-US-27110", "kind": "us", "path": "user-stories/persistence-data-postgres-us-27110.json" },
-    { "id": "TAC-2801-persistence-data-postgres-facade", "kind": "tac", "path": "tacs/tac-2801-persistence-data-postgres-facade.json" },
-    { "id": "TAC-2802-persistence-data-postgres-migration-runner", "kind": "tac", "path": "tacs/tac-2802-persistence-data-postgres-migration-runner.json" },
-    { "id": "TAC-2803-persistence-data-postgres-transaction-helper", "kind": "tac", "path": "tacs/tac-2803-persistence-data-postgres-transaction-helper.json" },
-    { "id": "TAC-2804-persistence-data-postgres-recovery-runner", "kind": "tac", "path": "tacs/tac-2804-persistence-data-postgres-recovery-runner.json" },
+    {
+      "id": "persistence-data-postgres-REQ-001",
+      "kind": "req",
+      "path": "requirements/persistence-data-postgres-req-001.json"
+    },
+    {
+      "id": "persistence-data-postgres-REQ-002",
+      "kind": "req",
+      "path": "requirements/persistence-data-postgres-req-002.json"
+    },
+    {
+      "id": "persistence-data-postgres-REQ-003",
+      "kind": "req",
+      "path": "requirements/persistence-data-postgres-req-003.json"
+    },
+    {
+      "id": "persistence-data-postgres-REQ-004",
+      "kind": "req",
+      "path": "requirements/persistence-data-postgres-req-004.json"
+    },
+    {
+      "id": "persistence-data-postgres-REQ-005",
+      "kind": "req",
+      "path": "requirements/persistence-data-postgres-req-005.json"
+    },
+    {
+      "id": "persistence-data-postgres-REQ-006",
+      "kind": "req",
+      "path": "requirements/persistence-data-postgres-req-006.json"
+    },
+    {
+      "id": "persistence-data-postgres-REQ-007",
+      "kind": "req",
+      "path": "requirements/persistence-data-postgres-req-007.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27101",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27101.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27102",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27102.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27103",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27103.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27104",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27104.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27105",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27105.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27106",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27106.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27107",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27107.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27108",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27108.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27109",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27109.json"
+    },
+    {
+      "id": "persistence-data-postgres-US-27110",
+      "kind": "us",
+      "path": "user-stories/persistence-data-postgres-us-27110.json"
+    },
+    {
+      "id": "TAC-2801-persistence-data-postgres-facade",
+      "kind": "tac",
+      "path": "tacs/tac-2801-persistence-data-postgres-facade.json"
+    },
+    {
+      "id": "TAC-2802-persistence-data-postgres-migration-runner",
+      "kind": "tac",
+      "path": "tacs/tac-2802-persistence-data-postgres-migration-runner.json"
+    },
+    {
+      "id": "TAC-2803-persistence-data-postgres-transaction-helper",
+      "kind": "tac",
+      "path": "tacs/tac-2803-persistence-data-postgres-transaction-helper.json"
+    },
+    {
+      "id": "TAC-2804-persistence-data-postgres-recovery-runner",
+      "kind": "tac",
+      "path": "tacs/tac-2804-persistence-data-postgres-recovery-runner.json"
+    },
     {
       "id": "ADR-2801-persistence-data-postgres-driver",
       "kind": "adr",
@@ -76,5 +162,97 @@
       "elicited": true,
       "standardsTraceClause": "generic enterprise practice"
     }
+  ],
+  "elicits": [
+    {
+      "id": "connection-url",
+      "prompt": "Connection URL for the pg client (project-config value; a security-secrets-management-applied project passes a secretRef instead of the literal URL). The facade dereferences this at boot and holds no other reference to it.",
+      "kind": "string",
+      "default": "postgres://localhost:5432/app"
+    },
+    {
+      "id": "migrations-directory",
+      "prompt": "Migrations directory: numbered forward-only .sql files, one file one transaction. Default db/migrations under the applying project root.",
+      "kind": "string",
+      "default": "db/migrations"
+    },
+    {
+      "id": "migration-runner-tool",
+      "prompt": "Migration runner tool per ADR-2802. node-pg-migrate wraps the pg driver; sqitch is a standalone Perl runner; flyway is the JVM-based runner; custom is a bespoke Node runner over pg. The discipline (numbered forward-only, one file one transaction) is fixed; the tool is elicited.",
+      "kind": "enum",
+      "options": [
+        "node-pg-migrate",
+        "sqitch",
+        "flyway",
+        "custom"
+      ],
+      "default": "node-pg-migrate"
+    },
+    {
+      "id": "runner-mode",
+      "prompt": "Migration runner mode per ADR-2803. atBoot runs migrations on process boot before the facade opens (right for a long-lived Node target). ciStep runs migrations as a discrete CI step before the deploy (right for Workers-adjacent or container-scheduled targets where the runtime lifecycle is not the migration lifecycle).",
+      "kind": "enum",
+      "options": [
+        "atBoot",
+        "ciStep"
+      ],
+      "default": "atBoot"
+    },
+    {
+      "id": "pool-size",
+      "prompt": "Connection pool size per node-postgres defaults. The shipped default is 10 on Node targets; a container target with a short-lived request scope may use a lower value.",
+      "kind": "string",
+      "default": "10"
+    },
+    {
+      "id": "idle-timeout-ms",
+      "prompt": "Idle-timeout milliseconds per node-postgres. Default 30000. A container target may set 0 to disable idle culling and rely on the request-scoped pool.",
+      "kind": "string",
+      "default": "30000"
+    },
+    {
+      "id": "connection-timeout-ms",
+      "prompt": "Connection-timeout milliseconds per node-postgres. Default 5000. The facade refuses to boot when the timeout expires without a successful ready-check.",
+      "kind": "string",
+      "default": "5000"
+    },
+    {
+      "id": "recovery-destination",
+      "prompt": "Destination path for the scheduled pg_dump artefact. A filesystem path, an S3 URL, or an operator-owned path. The recovery runner writes here and emits backupExported carrying the artefact path.",
+      "kind": "string",
+      "default": "backups/pg"
+    },
+    {
+      "id": "recovery-cadence",
+      "prompt": "Cadence for the scheduled pg_dump artefact. daily is the shipped default; hourly and weekly are alternatives per ADR-2804. off is not legal at v1.0.0 because the two-path recovery model requires the export path.",
+      "kind": "enum",
+      "options": [
+        "daily",
+        "hourly",
+        "weekly"
+      ],
+      "default": "daily"
+    },
+    {
+      "id": "pitr-provider",
+      "prompt": "Vendor point-in-time recovery provider. hosted (RDS, Cloud SQL, Neon, Supabase, etc., where the vendor exposes PITR) or self-managed (WAL archiving to a durable object store, restored via pg_basebackup). Both paths are required at v1.0.0.",
+      "kind": "enum",
+      "options": [
+        "hosted",
+        "self-managed"
+      ],
+      "default": "hosted"
+    },
+    {
+      "id": "advisory-lock-helper",
+      "prompt": "Advisory-lock helper mode per Postgres explicit-locking reference. off omits the helper entirely (Q1 ratified default). session takes pg_advisory_lock at session scope; transaction takes pg_advisory_xact_lock at transaction scope.",
+      "kind": "enum",
+      "options": [
+        "off",
+        "session",
+        "transaction"
+      ],
+      "default": "off"
+    }
   ]
 }

package/blueprints/persistence-data-postgres/contributions/adrs/adr-2801-persistence-data-postgres-driver.json

@@ -22,7 +22,7 @@
     {
       "name": "Hyperdrive as the shipped v1.0.0 driver",
       "summary": "Ship Hyperdrive-wrapped pg as the v1.0.0 default.",
-      "reasonNotChosen": "Hyperdrive is a Cloudflare-account-bound service and the round-5 spec ruling 5 (Baz decision 8) places Postgres as the local-first blueprint. Making Hyperdrive the default would force every project to bind to a Cloudflare account before applying the blueprint. Round 6 lands Hyperdrive as a v1.1.0 minor adapter behind an elicit, keeping local-first at v1.0.0."
+      "reasonNotChosen": "Hyperdrive is a Cloudflare-account-bound service and the round-5 spec ruling 5 (maintainer decision) places Postgres as the local-first blueprint. Making Hyperdrive the default would force every project to bind to a Cloudflare account before applying the blueprint. Round 6 lands Hyperdrive as a v1.1.0 minor adapter behind an elicit, keeping local-first at v1.0.0."
     }
   ],
   "createdAt": "2026-09-06T15:47:00.000Z",

package/blueprints/persistence-data-postgres/contributions/adrs/adr-2805-persistence-data-postgres-connection-pool-posture.json

@@ -17,7 +17,7 @@
     {
       "name": "Delegate every pool to Hyperdrive from v1.0.0",
       "summary": "Ship Hyperdrive as the pool manager for every target.",
-      "reasonNotChosen": "Hyperdrive is a Cloudflare-account-bound service; forcing every project to bind to Cloudflare before applying the blueprint conflicts with the local-first posture (round-5 spec ruling 5, Baz decision 8). Round 6 lands Hyperdrive as an elicit for the operator who wants it."
+      "reasonNotChosen": "Hyperdrive is a Cloudflare-account-bound service; forcing every project to bind to Cloudflare before applying the blueprint conflicts with the local-first posture (round-5 spec ruling 5, maintainer decision). Round 6 lands Hyperdrive as an elicit for the operator who wants it."
     }
   ],
   "createdAt": "2026-09-06T15:47:00.000Z",

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

@@ -2,7 +2,7 @@
   "reqId": "persistence-data-postgres-REQ-001",
   "prdId": "PRD-001",
   "title": "One facade module is the sole reader of the pg client and opens on boot",
-  "description": "The application accesses Postgres through a single facade module in the project's source tree that is the ONLY module in the tree that imports and reads the pg (node-postgres) client. Every other module that touches persistence imports the facade and calls its named domain verbs; no other module holds the raw pg client, a pg.Pool reference, or a pg.PoolClient reference. On process boot, the facade opens a pg.Pool against the elicited connection URL and, once the first successful ready-check completes, emits a facadeReady lifecycle event carrying the database name. The connection URL is elicited (project-config file by default; a security-secrets-management-applied project passes a secretRef).",
+  "description": "The application accesses Postgres through a single facade module in the project's source tree that is the ONLY module in the tree that imports and reads the pg (node-postgres) client. Every other module that touches persistence imports the facade and calls its named domain verbs; no other module holds the raw pg client, a pg.Pool reference, or a pg.PoolClient reference. On process boot, the facade opens a pg.Pool against the elicited connection URL and, once the first successful ready-check completes, emits a facadeReady lifecycle event carrying the database name. The connection URL is elicited (project-config file by default; a security-secrets-management-applied project passes a secretRef). This blueprint declares the relationalStore applied capability against a project through this facade: any downstream blueprint whose requiresAppliedCapabilities lists relationalStore is satisfied by an applied persistence-data-postgres pinning the facade module to its Pool client and the elicited connection URL.",
   "category": "functional",
   "domain": "persistence",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2801-persistence-data-postgres-facade",
+    "field": "responsibilities.facadeReady"
+  }
 }

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

@@ -2,7 +2,7 @@
   "reqId": "persistence-data-postgres-REQ-002",
   "prdId": "PRD-001",
   "title": "Schema evolution ships as numbered forward-only .sql migrations applied one file one transaction",
-  "description": "Schema evolution is expressed as a directory of numbered .sql migration files under the elicited migrations directory (default ./migrations/). Each filename begins with a monotonically increasing integer that is unique across the directory; the file body is engine-native SQL. An in-tree migration runner applies each file inside its own transaction (BEGIN, run the file body, COMMIT on success or ROLLBACK on error); the runner tracks applied filenames in a schema_version bookkeeping table it maintains inside the same database. There are no down migrations. Which runner tool the project reaches for is elicited (a node-pg-migrate wrap, a sqitch invocation, a flyway process, or a bespoke Node runner over pg); the discipline is what is fixed here, not the tool.",
+  "description": "Schema evolution is expressed as a directory of numbered .sql migration files under the elicited migrations directory (default ./migrations/). Each filename begins with a monotonically increasing integer that is unique across the directory; the file body is engine-native SQL. An in-tree migration runner applies each file inside its own transaction (BEGIN, run the file body, COMMIT on success or ROLLBACK on error); the runner tracks applied filenames in a schema_version bookkeeping table it maintains inside the same database. There are no down migrations. Which runner tool the project reaches for is elicited (a node-pg-migrate wrap, a sqitch invocation, a flyway process, or a bespoke Node runner over pg); the discipline is what is fixed here, not the tool. The migration-runner-tool is elicited between node-pg-migrate, sqitch, flyway and a custom Node runner; the discipline (numbered forward-only, one file one transaction) is fixed, the tool is not.",
   "category": "technical",
   "domain": "persistence",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2802-persistence-data-postgres-migration-runner",
+    "field": "responsibilities.migrations"
+  }
 }

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

@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2801-persistence-data-postgres-facade",
+    "field": "responsibilities.parameter"
+  }
 }

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

@@ -2,7 +2,7 @@
   "reqId": "persistence-data-postgres-REQ-004",
   "prdId": "PRD-001",
   "title": "Transactional atomicity: multi-statement writes through a transaction helper roll back on any error",
-  "description": "Multi-statement writes that require atomicity are issued through the facade's transaction helper, which wraps client.query('BEGIN') around a callback, awaits the callback's statements (each issued through pg.query with the prepared-statement discipline in REQ-003), and issues client.query('COMMIT') on the callback's successful completion. If any statement inside the callback throws (including a constraint violation the driver surfaces as an error), the helper issues client.query('ROLLBACK'), releases the client back to the pool, and emits a transactionRolledBack lifecycle event carrying the failing statement's zero-based index inside the callback. The helper does not swallow the underlying error; it re-throws after the rollback so the caller observes the failure and the facade's own error boundary constructs the internal error record.",
+  "description": "Multi-statement writes that require atomicity are issued through the facade's transaction helper owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction. The helper wraps the transaction-control primitives named there around a consumer callback, awaits the callback's statements (each issued through the prepared-statement discipline in REQ-003), commits on the callback's successful completion, and rolls back with a transactionRolledBack lifecycle event on any statement failure inside the callback (including a constraint violation the driver surfaces as an error). The lifecycle event carries the failing statement's zero-based index inside the callback. The helper does not swallow the underlying error; it re-throws after the rollback so the caller observes the failure and the facade's own error boundary constructs the internal error record.",
   "category": "functional",
   "domain": "persistence",
   "priority": "must",
@@ -11,8 +11,12 @@
     "blueprint:persistence-data-postgres",
     "category:04-transaction-helper"
   ],
-  "version": "1.0.0",
+  "version": "1.0.1",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-10T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2803-persistence-data-postgres-transaction-helper",
+    "field": "responsibilities.transactionAtomicity"
+  }
 }

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

@@ -2,7 +2,7 @@
   "reqId": "persistence-data-postgres-REQ-005",
   "prdId": "PRD-001",
   "title": "Two-path recovery: scheduled pg_dump artefact PLUS vendor point-in-time recovery, both elicited, both required",
-  "description": "The recovery model is two-path and both paths are required at v1.0.0: (a) a scheduled export runner drives pg_dump via child_process.execFile against the elicited connection URL, writes the artefact to the elicited destination (a filesystem path, an S3 URL, an operator-owned path), and emits a backupExported lifecycle event carrying the artefact path and a completion timestamp; (b) the deploy target's own point-in-time recovery is enabled and its cadence and retention window are elicited (a managed Postgres cluster's PITR window, a self-managed cluster's WAL-archive posture). Neither path is optional. A fresh Postgres primed from a pg_dump artefact reads the rows committed at or before the artefact's completion timestamp; a fresh Postgres restored to a PITR point reads the rows committed at or before that point.",
+  "description": "The recovery model is two-path and both paths are required at v1.0.0: (a) a scheduled export runner drives pg_dump via child_process.execFile against the elicited connection URL, writes the artefact to the elicited destination (a filesystem path, an S3 URL, an operator-owned path), and emits a backupExported lifecycle event carrying the artefact path and a completion timestamp; (b) the deploy target's own point-in-time recovery is enabled and its cadence and retention window are elicited (a managed Postgres cluster's PITR window, a self-managed cluster's WAL-archive posture). Neither path is optional. A fresh Postgres primed from a pg_dump artefact reads the rows committed at or before the artefact's completion timestamp; a fresh Postgres restored to a PITR point reads the rows committed at or before that point. The recovery-destination is elicited at apply time (a filesystem path, an S3 URL, or an operator-owned path). The recovery-cadence is elicited (daily is the shipped default; hourly is the higher-frequency alternative; weekly is the lower-frequency alternative, per ADR-2804). The pitr-provider path is elicited (hosted vendor PITR, or self-managed WAL archiving); both paths are required together at v1.0.0.",
   "category": "functional",
   "domain": "persistence",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2804-persistence-data-postgres-recovery-runner",
+    "field": "responsibilities.pg_dump"
+  }
 }

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

@@ -2,7 +2,7 @@
   "reqId": "persistence-data-postgres-REQ-006",
   "prdId": "PRD-001",
   "title": "Connection-pool posture per deploy target: long-lived pool on Node, request-scoped isolation on container",
-  "description": "The facade opens a long-lived pg.Pool for the lifetime of the Node process on a long-lived-Node deploy target (a monolithic Node server, a container platform holding warm instances). On a request-scoped container platform (a serverless-container target that spins fresh instances per request, a Workers-adjacent target via the round-6 Hyperdrive adapter at ADR-2801), the facade opens a pool sized to the request budget and disposes it at request end, or delegates the pool to the round-6 Hyperdrive-managed connection pool without holding a Node-side long-lived pool. Pool size, idle timeout, and query timeout are elicited defaults that the operator overrides per target; the shipped defaults are pool size 10, idleTimeoutMillis 30000, connectionTimeoutMillis 5000, per the node-postgres pool defaults. The pool-posture-smoke probe drives twenty concurrent queries at pool size 5 and asserts all return with no timeout; the probe does not impose a sizing formula.",
+  "description": "The facade opens a long-lived pg.Pool for the lifetime of the Node process on a long-lived-Node deploy target (a monolithic Node server, a container platform holding warm instances). On a request-scoped container platform (a serverless-container target that spins fresh instances per request, a Workers-adjacent target via the round-6 Hyperdrive adapter at ADR-2801), the facade opens a pool sized to the request budget and disposes it at request end, or delegates the pool to the round-6 Hyperdrive-managed connection pool without holding a Node-side long-lived pool. Pool size, idle timeout, and query timeout are elicited defaults that the operator overrides per target; the shipped defaults are pool size 10, idleTimeoutMillis 30000, connectionTimeoutMillis 5000, per the node-postgres pool defaults. The pool-posture-smoke probe drives twenty concurrent queries at pool size 5 and asserts all return with no timeout; the probe does not impose a sizing formula. Runner-mode is elicited per ADR-2803: atBoot runs migrations on process boot before the facade opens (right for a long-lived Node target); ciStep runs migrations as a discrete CI step before the deploy (right for Workers-adjacent or container-scheduled targets). Pool posture reads the elicited idle-timeout-ms (default 30000 per node-postgres) and connection-timeout-ms (default 5000) at boot; a container target may set idle-timeout-ms to zero.",
   "category": "technical",
   "domain": "persistence",
   "priority": "must",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-2801-persistence-data-postgres-facade",
+    "field": "responsibilities.pool"
+  }
 }

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

@@ -2,10 +2,10 @@
   "reqId": "persistence-data-postgres-REQ-007",
   "prdId": "PRD-001",
   "title": "Advisory-lock helper (optional): session or transaction level per the Postgres explicit-locking reference, elicited default off",
-  "description": "The facade exposes an optional advisory-lock helper that wraps pg_advisory_lock and pg_advisory_unlock for session-level locks, and pg_advisory_xact_lock for transaction-level locks. The helper takes an integer lock key, acquires the lock, runs a callback, and releases the lock via the paired unlock verb on the session-level shape (transaction-level locks release automatically at COMMIT or ROLLBACK per https://www.postgresql.org/docs/current/explicit-locking.html). Whether the helper ships in the applied surface is elicited (advisoryLockHelper: off, session, or transaction); default off per the ratified Q1 answer on the round-5 spec section 10. The elicited value is recorded on the applied sidecar so a later validation pass can flag surfaces that never activated the option.",
+  "description": "The facade exposes an optional advisory-lock helper that wraps pg_advisory_lock and pg_advisory_unlock for session-level locks, and pg_advisory_xact_lock for transaction-level locks. The helper takes an integer lock key, acquires the lock, runs a callback, and releases the lock via the paired unlock verb on the session-level shape (transaction-level locks release automatically at COMMIT or ROLLBACK per https://www.postgresql.org/docs/current/explicit-locking.html). Whether the helper ships in the applied surface is elicited (advisoryLockHelper: off, session, or transaction); default off per the ratified Q1 answer on the round-5 spec section 10. The elicited value is recorded on the applied sidecar so a later validation pass can flag surfaces that never activated the option. The advisory-lock helper is elicited off (default, no helper shipped in the applied surface), session (pg_advisory_lock at session scope) or transaction (pg_advisory_xact_lock at transaction scope).",
   "category": "functional",
   "domain": "persistence",
-  "priority": "should",
+  "priority": "must",
   "rationale": "Cross-process coordination on a shared Postgres (a migration coordinator, a lock-per-tenant workflow, a one-writer-per-partition pattern) is served cleanly by advisory locks; the alternative (a bespoke locks table) reinvents what the engine already gives. Shipping the helper in v1.0.0 pins the semantics before a project depends on a workaround; defaulting off keeps the applied surface small for projects that do not need it. The session-vs-transaction distinction is load-bearing: session-level locks survive rolled-back transactions per the explicit-locking reference, and pinning the choice in the ADR is what avoids the reader-side confusion.",
   "tags": [
     "blueprint:persistence-data-postgres",
@@ -14,5 +14,9 @@
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "adrId": "ADR-2801-persistence-data-postgres-driver",
+    "field": "decision.advisoryLock"
+  }
 }

package/blueprints/persistence-data-postgres/contributions/tacs/tac-2802-persistence-data-postgres-migration-runner.json

@@ -9,8 +9,8 @@
   "responsibilities": [
     "Read the elicited migrations directory (default ./migrations/); enumerate .sql files sorted by their leading integer; reject a duplicate leading integer at load time (AC-27102-1).",
     "Ensure the schema_version bookkeeping table exists on first invocation; upsert only via the applied-filename row it inserts on each successful file (AC-27102-1).",
-    "For each un-applied file, in order, issue client.query('BEGIN'), read the file body, execute it, insert the applied-filename row into schema_version, issue client.query('COMMIT') (AC-27102-1).",
-    "On any statement failure inside a file's transaction, issue client.query('ROLLBACK'), emit migrationApplyFailed with the failing filename, stop the runner, exit non-zero (AC-27109-1).",
+    "For each un-applied file, in order, open the per-file transaction through the BEGIN primitive owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction, read the file body, execute it, insert the applied-filename row into schema_version, close through the COMMIT primitive owned on the same interface (AC-27102-1).",
+    "On any statement failure inside a file's transaction, unwind through the ROLLBACK primitive owned on TAC-2803-persistence-data-postgres-transaction-helper.interfaces.withTransaction, emit migrationApplyFailed with the failing filename, stop the runner, exit non-zero (AC-27109-1).",
     "On successful completion of every file, emit migrationsApplied with the applied-filename list."
   ],
   "internalStructure": "One CLI-invokable Node module plus a library entry point the facade may call from atBoot mode. The module reads its config (connection URL, migrations directory, bookkeeping table name) from an elicited config source; enumerates the directory; loops over un-applied files; issues one BEGIN/apply/COMMIT per file; writes the schema_version row inside the same transaction so a mid-COMMIT crash never leaves a row behind for a file whose body did not land.",

package/blueprints/persistence-data-postgres/contributions/tacs/tac-2803-persistence-data-postgres-transaction-helper.json

@@ -5,12 +5,12 @@
   "version": "1.0.0",
   "status": "approved",
   "name": "Postgres transaction helper",
-  "purpose": "The helper that wraps client.query('BEGIN') and client.query('COMMIT') around a consumer callback and issues client.query('ROLLBACK') with a transactionRolledBack event on any error, tracking the zero-based index of the failing statement inside the callback.",
+  "purpose": "The helper that wraps the transaction-control primitives around a consumer callback and rolls back with a transactionRolledBack event on any error, tracking the zero-based index of the failing statement inside the callback. The transaction-control shape is owned on `interfaces.withTransaction` below.",
   "responsibilities": [
-    "Acquire a pg.PoolClient from the facade's pool; issue client.query('BEGIN') (AC-27104-1).",
+    "Acquire a pg.PoolClient from the facade's pool; open the transaction through the BEGIN primitive owned on interfaces.withTransaction (AC-27104-1).",
     "Invoke the consumer callback with a wrapped client whose query(sql, params) delegates to the underlying client and increments a statement counter each time it is called (AC-27104-1).",
-    "On the callback's successful completion, issue client.query('COMMIT'), release the client, resolve the outer promise (AC-27104-1).",
-    "On any error thrown from a wrapped-client query or from the callback body, issue client.query('ROLLBACK'), fire transactionRolledBack on the injected event sink with { statementIndex, code }, release the client, re-throw the underlying error (AC-27104-1).",
+    "On the callback's successful completion, close the transaction through the COMMIT primitive owned on interfaces.withTransaction, release the client, resolve the outer promise (AC-27104-1).",
+    "On any error thrown from a wrapped-client query or from the callback body, unwind the transaction through the ROLLBACK primitive owned on interfaces.withTransaction, fire transactionRolledBack on the injected event sink with { statementIndex, code }, release the client, re-throw the underlying error (AC-27104-1).",
     "Preserve the underlying pg error object (code, detail, position, table, constraint) on the re-thrown error so the facade's own error boundary constructs the internal error record correctly."
   ],
   "internalStructure": "A single async function withTransaction({ pool, onEvent }) that returns a call helper. The helper wraps the pg.PoolClient in a proxy that intercepts .query() to increment the counter, forwards the arguments to the underlying client, and re-throws on error after firing the event.",
@@ -18,7 +18,7 @@
     {
       "name": "withTransaction",
       "kind": "read-write-api",
-      "description": "await store.withTransaction(async (tx) => { await tx.query(...); await tx.query(...); }). Commits on successful return, rolls back on any thrown error, fires transactionRolledBack with statementIndex on rollback."
+      "description": "await store.withTransaction(async (tx) => { await tx.query(...); await tx.query(...); }). The helper acquires a pg.PoolClient from the pool and issues the transaction-control primitives around the callback: `client.query('BEGIN')` before the first wrapped-client query, `client.query('COMMIT')` on the callback's successful return, and `client.query('ROLLBACK')` on any thrown error before releasing the client. On rollback the helper fires transactionRolledBack on the injected event sink with { statementIndex, code } and re-throws the underlying pg error."
     }
   ],
   "dependencies": [

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

@@ -16,7 +16,8 @@
       "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"
+      "scope": "runtime",
+      "disposition": "template"
     },
     {
       "id": "AC-27101-2",
@@ -25,10 +26,27 @@
       "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"
+      "scope": "runtime",
+      "disposition": "template"
+    },
+    {
+      "id": "AC-27101-3",
+      "description": "Credential missing at boot. Given the elicited connection-url resolves to a rejected value (an empty string or a secretRef the resolver refuses), when the facade opens on boot, then the facade refuses with a named error kind (missingConnectionUrl) and no facadeReady fires on the event sink; the error record carries no fragment of the connection URL substring.",
+      "given": "connection-url resolves to an empty string or the secretRef resolver refuses",
+      "when": "the facade opens on boot",
+      "then": "facade refuses with missingConnectionUrl; no facadeReady fires; the error record carries no URL substring",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-2801-persistence-data-postgres-facade",
+        "field": "interfaces.createStore"
+      },
+      "disposition": "template"
     }
   ],
-  "tacIds": ["TAC-2801-persistence-data-postgres-facade"],
+  "tacIds": [
+    "TAC-2801-persistence-data-postgres-facade"
+  ],
   "createdAt": "2026-09-06T15:47:00.000Z",
-  "updatedAt": "2026-09-06T15:47:00.000Z"
+  "updatedAt": "2026-09-09T00:00:00Z"
 }