@rehearsal-db/core 0.1.0-beta.12 → 0.1.0-beta.13

package/CHANGELOG.md

@@ -5,6 +5,46 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+### Added
+
+- Runtime and CI compatibility now cover maintained Node.js 22, 24, and 26 releases;
+  Node.js 24 LTS remains the recommended default and release-build runtime.
+- Source access policies can use an externally provisioned, database-expiring
+  PostgreSQL reader without administrator credentials. Rehearsal binds canonical export
+  view definitions, verifies the complete approved read surface and deny controls, and
+  never changes or retires provider-owned source objects.
+- `rehearsal --version`, its conventional `-V` alias, and `rehearsal version` now
+  report the installed package version without requiring project configuration.
+- Privacy policy version 2 can use one reviewed identity-aware path mapping for both
+  database references and physical Storage destinations. Owner prefixes stay in the
+  environment, review plans retain only their hashes, and unsafe or mismatched paths
+  fail closed.
+- Related timestamps can share a named deterministic date-shift group, preserving their
+  ordering and duration without consumer callbacks.
+- The baseline verification corpus now exercises two unrelated target schemas, a
+  10,003-row packed-package stream, concurrent row/schema/ledger changes, malformed and
+  truncated results, connection loss, low disk, interruption, and deterministic
+  fixed-key output.
+
+### Fixed
+
+- Baseline preparation now rejects missing, negative, overflowing, malformed, or
+  oversized PostgreSQL estimate and cursor results before activation. Every preparation
+  failure preserves the active baseline, removes private staging, and leaves an edited
+  runtime untouched.
+- Approved-owner UUID columns are no longer confused with PostgreSQL sequence-backed
+  identities. Restore checks the actual local schema before resetting a sequence, while
+  genuine numeric identity columns retain correct next-value behavior.
+- A failed Storage transfer now recursively restores write permission only within its
+  owned staging tree, removes that incomplete generation, and preserves the original
+  safe preparation error instead of replacing it with a cleanup error.
+- Storage preparation now records a canonical media type from reviewed object metadata,
+  removing response-only parameters such as a text charset that local bucket MIME
+  allowlists reject during restore.
+- Container startup and health failures are now classified as runtime dependency
+  failures and include safe Docker/Colima capacity context instead of being mislabeled
+  as migration verification failures.
+
 ## [0.1.0-beta.12] - 2026-10-04
 
 ### Added

package/COMPATIBILITY.md

@@ -21,6 +21,12 @@ The first stable `1.0.0` requires external beta evidence, a support policy, and
 public API. Supporting additional database families, package managers, or operating
 systems is not implied by the 0.x contract.
 
+Rehearsal supports maintained even-numbered Node.js release lines that pass its CI
+matrix. Beta.13 supports Node.js 22, 24, and 26; Node.js 24 LTS is the recommended
+default and the release-build runtime. End-of-life and odd-numbered Node.js releases are
+not supported. A future release may remove a Node.js line after its upstream end-of-life
+date, with that change called out in the changelog.
+
 The npm install hook may create project scaffolding only when it proves one application
 root. Ordinary npm application installs are covered. A workspace is automatic only when
 one declaring consumer is already visible in its manifest or lockfile; npm can save a

package/README.md

@@ -22,7 +22,7 @@ production deployment tool.
 
 ## What you need
 
-- Node.js 24 and npm
+- Node.js 22, 24, or 26 and npm (Node.js 24 LTS recommended)
 - Docker Desktop, Colima, or another Docker-compatible engine
 - timestamped `.sql` migration files
 - a project test command that can prove the migrated application works
@@ -169,7 +169,7 @@ problems belong in the private process described in [SECURITY.md](SECURITY.md).
 
 ## For contributors
 
-Use Node.js 24, run `npm ci`, then run:
+Use a supported Node.js release (22, 24, or 26), run `npm ci`, then run:
 
 ```bash
 npm run check

package/docs/commands.md

@@ -43,17 +43,17 @@ existing config.
 These commands are separate from ordinary rehearsals. Configure `preparation` only after
 reviewing [the standalone security contract](standalone-workflow.md).
 
-| Command                                                       | What it does                                                         |
-| ------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `npx rehearsal privacy key`                                   | Preview the owner-only pseudonym-key path.                           |
-| `npx rehearsal privacy key --write`                           | Create the key once; refuses to replace an existing key.             |
-| `npx rehearsal source plan`                                   | Preview the exact temporary reader, views, columns, and asset scope. |
-| `npx rehearsal source apply --confirm-source-access=<sha256>` | Create only the reviewed, time-limited source access.                |
-| `npx rehearsal baseline refresh`                              | Replace only the baseline from a reviewed source.                    |
-| `npx rehearsal refresh`                                       | Preview a complete safe refresh of the baseline and local runtime.   |
-| Add `--confirm-refresh=<sha256>`                              | Create the replacement, reset locally, and prune listed old copies.  |
-| `npx rehearsal source retire`                                 | Preview exact reader/view/credential retirement.                     |
-| Add `--confirm-source-retirement=<sha256>`                    | Apply that retirement plan and verify the exact object inventory.    |
+| Command                                                       | What it does                                                            |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `npx rehearsal privacy key`                                   | Preview the owner-only pseudonym-key path.                              |
+| `npx rehearsal privacy key --write`                           | Create the key once; refuses to replace an existing key.                |
+| `npx rehearsal source plan`                                   | Preview the exact temporary reader, views, columns, and asset scope.    |
+| `npx rehearsal source apply --confirm-source-access=<sha256>` | Create managed access, or verify external access without source writes. |
+| `npx rehearsal baseline refresh`                              | Replace only the baseline from a reviewed source.                       |
+| `npx rehearsal refresh`                                       | Preview a complete safe refresh of the baseline and local runtime.      |
+| Add `--confirm-refresh=<sha256>`                              | Create the replacement, reset locally, and prune listed old copies.     |
+| `npx rehearsal source retire`                                 | Preview managed retirement or external local-secret cleanup.            |
+| Add `--confirm-source-retirement=<sha256>`                    | Apply that retirement plan and verify the exact object inventory.       |
 
 Source credentials are read from environment variables named in the reviewed source
 policy. Never paste a connection string into an argument. `baseline refresh` leaves the
@@ -176,6 +176,8 @@ belonging to other projects are never included. This follows
 
 | Option                                 | Meaning                                                          |
 | -------------------------------------- | ---------------------------------------------------------------- |
+| `--help`, `-h`                         | Show the installed command reference.                            |
+| `--version`, `-V`                      | Print the installed package version and exit.                    |
 | `--json`                               | Return the versioned machine-readable result.                    |
 | `--verbose`                            | Show more safe detail.                                           |
 | `--debug`                              | Show the most diagnostic detail; still review it before sharing. |
@@ -193,6 +195,8 @@ belonging to other projects are never included. This follows
 | `--write`                              | Apply a setup, policy, or cleanup preview.                       |
 
 Run `npx rehearsal --help` to print the command list available in your installed version.
+Run `npx rehearsal --version` to print only its version number. Add `--json` when a
+script also needs the package name.
 
 When a project has more than one config, pass `--config=<path>` on every command for the
 non-default one. Rehearsal keeps that exact config selected through status, run, reset,

package/docs/getting-started.md

@@ -7,7 +7,8 @@ Want to experiment first? Use the [safe hands-on tutorial](tutorial.md).
 
 ## 1. Check the required tools
 
-You need Node.js 24, npm, and a running Docker-compatible engine:
+You need Node.js 22, 24, or 26, npm, and a running Docker-compatible engine. Node.js 24
+LTS is the recommended default:
 
 ```bash
 node --version
@@ -15,8 +16,8 @@ npm --version
 docker info
 ```
 
-`node --version` must begin with `v24`. If `docker info` fails, start Docker Desktop,
-Colima, or your usual Docker engine.
+`node --version` must begin with `v22`, `v24`, or `v26`. If `docker info` fails, start
+Docker Desktop, Colima, or your usual Docker engine.
 
 Choose the extra requirement for your project:
 

package/docs/production-source.md

@@ -33,6 +33,7 @@ URLs, or raw owner identifiers.
   "targetFingerprint": "<sha256 of the approved PostgreSQL host, port, and database>",
   "administratorEnvironmentVariable": "REHEARSAL_SOURCE_ADMIN_URL",
   "reader": {
+    "mode": "managed",
     "role": "rehearsal_example_reader",
     "ownerRole": "rehearsal_example_owner",
     "credentialFile": ".rehearsal/secrets/source-reader.env",
@@ -61,7 +62,7 @@ URLs, or raw owner identifiers.
       "view": "approved_owner_profile",
       "targetSchema": "app_api",
       "targetTable": "profiles",
-      "columns": ["id", "email"],
+      "columns": ["id", "email", "avatar_path"],
       "orderBy": ["id"],
       "rowScope": {
         "kind": "approved-owner",
@@ -70,10 +71,28 @@ URLs, or raw owner identifiers.
       }
     }
   ],
-  "assets": []
+  "assetReader": {
+    "endpointFingerprint": "<sha256 of the approved Storage endpoint>",
+    "baseUrlEnvironmentVariable": "REHEARSAL_SOURCE_STORAGE_URL",
+    "tokenEnvironmentVariable": "REHEARSAL_SOURCE_STORAGE_TOKEN",
+    "maximumObjects": 1000,
+    "maximumObjectBytes": 52428800,
+    "maximumTotalBytes": 2147483648
+  },
+  "assets": [
+    {
+      "bucket": "avatars",
+      "prefixEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_ID",
+      "rights": "approved-owner",
+      "pathMapping": "owner-storage"
+    }
+  ]
 }
 ```
 
+`managed` is the default for existing policies, but writing it explicitly makes the
+credential boundary easier to review.
+
 Calculate fingerprints with the exported helpers from `@rehearsal-db/core/source-access`
 or a reviewed local script. A fingerprint binds the destination without recording its
 address. Changing the host, port, or database invalidates the plan.
@@ -82,13 +101,72 @@ address. Changing the host, port, or database invalidates the plan.
 use. `approved-owner` requires one explicit owner value from the named environment
 variable. Rehearsal never chooses an owner by finding an administrator.
 
+### Use a provider-managed reader
+
+If a database owner already supplies the restricted export views and reader, use
+`mode: "external"`. Omit `administratorEnvironmentVariable`; Rehearsal will not request
+an administrator credential or change the source:
+
+```json
+{
+  "reader": {
+    "mode": "external",
+    "role": "provided_rehearsal_reader",
+    "connectionEnvironmentVariable": "REHEARSAL_SOURCE_READER_URL",
+    "credentialFile": ".rehearsal/secrets/source-reader.env",
+    "maximumValidForMinutes": 30
+  },
+  "exportSchema": "provided_rehearsal_export",
+  "relations": [
+    {
+      "source": { "schema": "private", "table": "profiles" },
+      "view": "approved_owner_profile",
+      "targetSchema": "app_api",
+      "targetTable": "profiles",
+      "columns": ["id", "email", "avatar_path"],
+      "orderBy": ["id"],
+      "rowScope": {
+        "kind": "approved-owner",
+        "column": "id",
+        "valueEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_ID"
+      },
+      "viewDefinitionSha256": "<sha256 from externalViewDefinitionFingerprint>"
+    }
+  ]
+}
+```
+
+The database owner must create a `security_barrier` view owned by a role other than the
+reader. Record PostgreSQL's exact canonical definition, not handwritten SQL:
+
+```js
+import { externalViewDefinitionFingerprint } from "@rehearsal-db/core/source-access";
+
+console.log(externalViewDefinitionFingerprint(canonicalViewDefinition));
+```
+
+Obtain `canonicalViewDefinition` with
+`select pg_get_viewdef('provided_rehearsal_export.approved_owner_profile'::regclass, false)`.
+Rehearsal verifies that fingerprint before saving any local access receipt.
+The resulting receipt also binds the normalized source-policy fingerprint. Editing the
+view hash, columns, scopes, or reader declaration requires a new verification.
+
+External mode also requires all non-system readable columns to match only the declared
+views and migration-ledger columns. It refuses database, schema, relation, or column
+writes; inherited roles; privileged role attributes; executable non-system
+security-definer functions; a reader-owned view; or a database-enforced expiration
+beyond `maximumValidForMinutes`.
+
 `targetSchema` is optional and defaults to `public`. Set it when the restored relation
 belongs elsewhere, and use the same schema in privacy policy version 2. This is relation
 identity, not a request to search every schema.
 
-For Storage, add an `assetReader` block and approved `assets` entries. The reader URL and
-token come from named environment variables. Objects outside the exact bucket/prefix are
-not listed or downloaded. Size, object-count, path, ETag, and exact-byte checks apply.
+For Storage, the reader URL and token come from named environment variables. A public,
+non-identity prefix may use `prefix`. A private owner prefix uses
+`prefixEnvironmentVariable`, `rights: "approved-owner"`, and a `pathMapping` declared in
+the privacy policy below. Its raw value stays out of tracked files and the review plan
+records only its SHA-256. Objects outside the exact bucket/prefix are not listed or
+downloaded. Size, object-count, path, ETag, and exact-byte checks apply.
 
 ## 3. Use executable privacy policy version 2
 
@@ -98,6 +176,21 @@ Every selected column has one action and, where required, a bounded recipe:
 {
   "policyVersion": 2,
   "migrationCutoff": "20260101000000",
+  "bindings": {
+    "approved-owner": {
+      "environmentVariable": "REHEARSAL_APPROVED_OWNER_ID",
+      "approvedValueSha256": "<sha256 of the exact approved owner ID>"
+    }
+  },
+  "pathMappings": {
+    "owner-storage": {
+      "binding": "approved-owner",
+      "format": "uuid",
+      "namespace": "account-id",
+      "maximumBytes": 512,
+      "maximumSegments": 8
+    }
+  },
   "tables": [
     {
       "schema": "app_api",
@@ -119,6 +212,14 @@ Every selected column has one action and, where required, a bounded recipe:
           "generated": "NEVER",
           "identity": "NO",
           "foreignKey": null
+        },
+        {
+          "name": "avatar_path",
+          "action": "DERIVE",
+          "recipe": { "kind": "path-map", "mapping": "owner-storage" },
+          "generated": "NEVER",
+          "identity": "NO",
+          "foreignKey": null
         }
       ]
     }
@@ -127,9 +228,10 @@ Every selected column has one action and, where required, a bounded recipe:
 ```
 
 Supported recipes are intentionally small: keyed UUID/email/text/integer pseudonyms,
-explicit constants, bounded date shifts, and fully classified JSON objects. Unknown
-tables, columns, JSON keys, formats, and recipes stop the refresh. There is no JavaScript
-or SQL escape hatch.
+explicit constants, bounded or grouped date shifts, identity-aware path mappings, and
+fully classified JSON objects. Unknown tables, columns, JSON keys, formats, and recipes
+stop the refresh. There is no JavaScript or SQL escape hatch. See
+[Sanitization policy](sanitization.md) for complete path and date examples.
 
 ## 4. Preview, apply, refresh, and retire
 
@@ -146,10 +248,12 @@ npx rehearsal source retire
 npx rehearsal source retire --confirm-source-retirement=<full-sha256>
 ```
 
-`source apply` creates new time-limited roles and export views only when every exact name
-is unused. It verifies the reader cannot read raw tables, write, escalate roles, or call
-an exposed security-definer network function. Externally provisioned readers are not yet
-supported; use the managed reader so Rehearsal can prove its scope and retirement.
+In managed mode, `source apply` creates new time-limited roles and export views only when
+every exact name is unused. It verifies the reader cannot read raw tables, write,
+escalate roles, or call an exposed security-definer network function. In external mode,
+the same command performs only the read-only checks above and stores the already supplied
+credential in the ignored owner-only local file. It never creates, grants, alters, or
+drops a source object.
 
 `refresh` previews the complete replacement first. After exact confirmation, its baseline
 step uses one read-only repeatable-read transaction for the schema shape,
@@ -160,13 +264,31 @@ runtime is rolled back to the previous baseline and runtime. The lower-level `ba
 refresh` command remains available when automation should activate a baseline without
 resetting the runtime or pruning old generations.
 
+Rows committed after the repeatable-read transaction begins belong to the next refresh;
+they cannot leak into the current snapshot midway through streaming. A schema or ledger
+change during preparation stops activation. Malformed batches, network loss, interruption,
+limit overruns, and low disk also leave the previous baseline active. Because `baseline
+refresh` never resets the runtime, local runtime edits remain in place whether that
+baseline-only preparation succeeds or fails.
+
+Privacy `identity` metadata describes PostgreSQL `GENERATED ... AS IDENTITY`, not a
+person or account identifier. UUID account keys normally use `identity: "NO"` while
+remaining explicitly pseudonymized. During restore, Rehearsal consults the actual local
+table for a backing sequence before resetting it; UUID columns never receive numeric
+`max` or `setval` operations.
+
 Storage cannot share PostgreSQL's transaction snapshot. Rehearsal instead verifies each
 object's inventory version and byte count during transfer, then records its SHA-256 in
-the immutable baseline.
+the immutable baseline. For an identity-aware path, the database reference and physical
+destination use the same package-owned pseudonym; the source suffix is preserved.
 
-`source retire` inventories the exact recorded views before removal, then removes only
-those views, the two recorded roles, and local credential/receipt files. Unrelated roles,
-grants, objects, baselines, runtimes, and Docker resources are preserved.
+In managed mode, `source retire` inventories the exact recorded views before removal,
+then removes only those views, the two recorded roles, and local credential/receipt
+files. In external mode, it removes only Rehearsal's local credential and receipt; the
+provider-owned role and views remain untouched. The database-enforced expiration still
+limits access, and the provider may revoke it sooner. Rehearsal does not claim that local
+cleanup revoked a provider-owned credential. Unrelated roles, grants, objects, baselines,
+runtimes, and Docker resources are preserved.
 
 ## Limits
 

package/docs/sanitization.md

@@ -40,10 +40,10 @@ Two policy versions exist:
   Rehearsal can sanitize without project callbacks.
 
 Version 2 supports keyed UUID, email, text, and integer pseudonyms; explicit constant
-replacement; bounded date shifting; approved-owner conditionals; exhaustively classified
-JSON objects; and bounded JSON arrays. Unknown tables, columns, nested keys, formats,
-recipes, or missing required fields fail closed. It never evaluates JavaScript or SQL
-from the policy.
+replacement; bounded and grouped date shifting; identity-aware path mapping;
+approved-owner conditionals; exhaustively classified JSON objects; and bounded JSON
+arrays. Unknown tables, columns, nested keys, formats, recipes, or missing required
+fields fail closed. It never evaluates JavaScript or SQL from the policy.
 
 ## Approved-owner values
 
@@ -69,7 +69,7 @@ environment-variable name and SHA-256 receipt:
           "action": "PSEUDONYMIZE",
           "recipe": { "format": "uuid", "namespace": "account-id" },
           "generated": "NEVER",
-          "identity": "YES",
+          "identity": "NO",
           "foreignKey": null
         },
         {
@@ -101,12 +101,78 @@ node -e 'const {createHash}=require("node:crypto"); process.stdout.write(createH
 
 Every conditional table names its owner column. Missing bindings, hash mismatches,
 missing owner columns, null/unsupported owner values, and conditionals without an owner
-binding are refused. The owner column must be marked `identity: "YES"` and use
-`PSEUDONYMIZE`, preventing a conditional policy from retaining raw account IDs. Other
+binding are refused. The owner column must use `PSEUDONYMIZE`, preventing a conditional
+policy from retaining raw account IDs. `identity` describes PostgreSQL's generated SQL
+identity metadata, not whether a value identifies a person: ordinary UUID primary keys
+use `"NO"`, while a genuine `GENERATED ... AS IDENTITY` column uses `"YES"`. Rehearsal
+checks the restored PostgreSQL schema for a real backing sequence before attempting a
+sequence reset, so UUID identity values never receive numeric sequence operations. Other
 owners take the declared `otherwise` path; every other identity-bearing field still
 needs its own pseudonymization declaration. Supply the binding only to the local
 server-side Rehearsal process; do not put it in the policy, baseline, or tracked files.
 
+## Identity-aware Storage paths
+
+Use one named mapping when a database column and a physical Storage object both begin
+with the approved owner's ID. Rehearsal pseudonymizes only that first segment and keeps
+the remaining path unchanged:
+
+```json
+{
+  "pathMappings": {
+    "owner-storage": {
+      "binding": "approved-owner",
+      "format": "uuid",
+      "namespace": "account-id",
+      "maximumBytes": 512,
+      "maximumSegments": 8
+    }
+  },
+  "tables": [
+    {
+      "name": "profiles",
+      "sourceRows": "STREAM AND SANITIZE",
+      "columns": [
+        {
+          "name": "avatar_path",
+          "action": "DERIVE",
+          "recipe": { "kind": "path-map", "mapping": "owner-storage" },
+          "generated": "NEVER",
+          "identity": "NO",
+          "foreignKey": null
+        }
+      ]
+    }
+  ]
+}
+```
+
+The source policy uses the same mapping name and names the binding's environment
+variable as `prefixEnvironmentVariable`; it never contains the raw owner ID. During
+`rehearsal refresh`, the package uses the mapping for both database values and physical
+object destinations. A missing mapping, a different environment variable, a path whose
+first segment is not the exact reviewed owner, traversal, or a size/segment limit breach
+stops the refresh.
+
+## Related dates
+
+Give related timestamps the same `group` and `days` value to shift them by one stable
+offset. This preserves their order and duration:
+
+```json
+{
+  "name": "starts_at",
+  "action": "DERIVE",
+  "recipe": { "kind": "date-shift", "days": 30, "group": "event-window" },
+  "generated": "NEVER",
+  "identity": "NO",
+  "foreignKey": null
+}
+```
+
+Apply the same recipe to `ends_at`. Rehearsal refuses a group that declares conflicting
+`days` values. Leave out `group` when a date should shift independently.
+
 ## Structured JSON
 
 `json-object` fields are required by default. Set `"required": false` on an explicitly

package/docs/security-model.md

@@ -26,6 +26,9 @@ runtime.
 - successful receipts written only after verification.
 - separate exact-digest approval for source setup, source retirement, and identity claim;
 - short-lived source readers limited to reviewed views/columns and deny checks;
+- externally provisioned readers require canonical view-definition receipts,
+  `security_barrier`, independent ownership, an exact non-system readable-column surface,
+  no write or role-escalation paths, and database-enforced expiration;
 - bounded read-only extraction with no raw dump or row-value logging;
 - exhaustive privacy policy version 2 with an owner-only local pseudonym key;
 - application children receive only explicit local mappings and stay in an owned process
@@ -39,6 +42,11 @@ No single environment variable or config edit can redirect runtime commands to
 production. Optional source preparation is a separate boundary and never provides a
 hosted execution mode.
 
+External source mode verifies access but does not own it. Rehearsal makes no source-side
+changes and removes only its local credential and receipt. The provider owns early
+revocation and the database enforces the reviewed short expiration; Rehearsal never
+reports local cleanup as proof that a provider-owned role was deleted.
+
 ## Identity providers
 
 An optional external identity handshake is distinct from database access. Only declared

package/docs/standalone-workflow.md

@@ -8,16 +8,18 @@ The optional preparation workflow is a separate security boundary. It has
 three deliberately separate phases:
 
 1. `source plan` reads declarations and produces a redacted, exact plan.
-2. `source apply` requires the plan digest and source-owner credentials from a
-   named environment variable. It creates only the declared, time-limited
-   reader and export surface.
+2. `source apply` requires the plan digest. Managed mode uses source-owner credentials
+   from a named environment variable and creates only the declared, time-limited reader
+   and export surface. External mode verifies an already restricted reader without an
+   administrator credential or source-side writes.
 3. `refresh` uses that reader in a read-only repeatable-read transaction, builds
    privately, activates only after verification, resets the local runtime, and applies
    reviewed retention. `baseline refresh` is the lower-level baseline-only form.
 
-`source retire` has its own preview and digest. It removes only the exact
-reader and export objects Rehearsal recorded. It never searches for similarly
-named roles or removes unrelated grants.
+`source retire` has its own preview and digest. Managed mode removes only the exact
+reader and export objects Rehearsal recorded. External mode removes only local Rehearsal
+credentials and receipts, preserving provider-owned objects. It never searches for
+similarly named roles or removes unrelated grants.
 
 ## What belongs in declarations
 
@@ -46,9 +48,12 @@ separate. A declaration contains only the name of an environment variable or
 owner-only secret file. Rehearsal never puts credential values in command-line
 arguments, reports, baselines, receipts, or a launched application.
 
-The current workflow creates and verifies its own temporary PostgreSQL reader. An
-externally provisioned reader is not yet accepted because Rehearsal cannot currently
-prove that reader's complete scope and retirement behavior.
+The default managed workflow creates and verifies its own temporary PostgreSQL reader.
+External mode accepts a provider-managed reader only when its complete non-system
+readable-column surface exactly matches the reviewed export views and migration ledger.
+It also verifies canonical view-definition fingerprints, `security_barrier`, ownership,
+write denial, role isolation, security-definer denial, and a short database-enforced
+expiration. Rehearsal never claims ownership or revocation of provider-managed objects.
 
 ## Snapshot and privacy guarantees
 
@@ -57,6 +62,16 @@ read-only repeatable-read PostgreSQL transaction. Rehearsal rechecks the source
 identity and migration evidence before commit. Rows stream in bounded batches;
 record bodies never appear in progress or error output.
 
+The snapshot boundary is deliberate: row commits made after extraction starts are left
+for the next baseline, while concurrent schema or migration-ledger changes block the
+current activation. Invalid estimates, malformed batches, connection loss, interruption,
+and disk or configured-limit failures remove private staging and preserve the previously
+active baseline.
+
+Cleanup recursively makes only Rehearsal's private staging tree removable. A failed
+Storage transfer therefore reports the original safe transfer error, removes incomplete
+files, and does not alter the active generation.
+
 Storage objects do not share the database transaction guarantee. Their inventory records
 size and version metadata; transfer requires that version, verifies the exact byte count,
 and records a SHA-256 in the immutable baseline. Transfer refuses an object that changes,

package/docs/troubleshooting.md

@@ -34,14 +34,15 @@ Choose **Set the stage** and approve the preview. For pnpm and Yarn, use this gu
 automatic root generation is currently tested with npm. An existing supported config is
 kept in place, including `infrastructure/rehearsal/rehearsal.config.mjs`.
 
-## Setup says Node.js 24 is required
+## Setup says this Node.js version is unsupported
 
-Rehearsal intentionally supports one maintained Node.js major in its first beta. Switch
-the current shell before installing or running it. With nvm:
+Rehearsal supports the maintained Node.js 22, 24, and 26 release lines. Node.js 20 and
+odd-numbered releases are end-of-life. Switch the current shell before installing or
+running Rehearsal. The latest LTS is the recommended default:
 
 ```bash
-nvm install 24
-nvm use 24
+nvm install --lts
+nvm use --lts
 node --version
 ```
 
@@ -53,6 +54,12 @@ writes setup files.
 Start Docker Desktop or Colima, confirm `docker info`, then rerun `rehearsal doctor`.
 Restarting the computer is rarely necessary.
 
+When a container stays in `starting` or becomes `unhealthy`, Rehearsal reports a runtime
+dependency failure rather than a migration failure. The safe diagnostic includes Docker
+CPU, memory, and container counts; Colima also includes available VM memory when it can
+be read. Stop unrelated local stacks or increase the engine's resources before retrying.
+Rehearsal never changes engine settings or bypasses service health checks.
+
 ## Docker or Colima is out of disk space
 
 Preview what Rehearsal can safely remove:

package/docs/tutorial.md

@@ -3,7 +3,8 @@
 This tutorial runs a complete PostgreSQL rehearsal in a temporary fictional project. It
 does not use your application, production data, or a hosted database.
 
-Allow about five minutes. You need Node.js 24 and a running Docker-compatible engine.
+Allow about five minutes. You need Node.js 22, 24, or 26 and a running
+Docker-compatible engine. Node.js 24 LTS is recommended.
 
 ## 1. Prepare Rehearsal
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.12",
+  "version": "0.1.0-beta.13",
   "private": false,
   "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
   "repository": {
@@ -18,7 +18,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=24 <25"
+    "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
   },
   "bin": {
     "rehearsal": "src/cli/rehearsal.mjs"