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

package/CHANGELOG.md

@@ -5,6 +5,122 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-beta.14] - 2026-10-05
+
+### Added
+
+- Packed-package onboarding is now a required CI job. It covers fresh Supabase and
+  PostgreSQL installs, beta.7 configuration preservation, missing credentials, occupied
+  ports, malformed configuration, and non-destructive partial-setup recovery.
+- The independent test lab can run the same first-install boundary against an exact
+  candidate tarball before either database lifecycle.
+- Installation and setup now report the exact active Rehearsal configuration path and
+  explain when a supported existing nested config prevents root-file generation.
+- Packed-package onboarding covers fresh, nested, existing-root, and repeated installs
+  while proving reviewed configuration bytes are preserved.
+- Privacy policy version 2 can explicitly treat nullable owners as non-matches and match
+  an approved owner through any of a bounded list of pseudonymized identity columns.
+- Bounded JSON unions classify each permitted root type, while JSON dictionaries require
+  reviewed runtime-key formats, key actions, value recipes, and item/depth/byte limits.
+- JSON dictionaries can restrict runtime keys to canonical signed integers within an
+  explicit safe-integer range, preserving positive, negative, and reviewed zero keys
+  without widening numeric maps to arbitrary text.
+- Date shifting can explicitly preserve numeric epoch-millisecond representation,
+  including inside structured JSON, while sharing a stable grouped offset with related
+  epoch or ISO-string dates.
+- Bounded scalar enums retain only explicitly reviewed structural strings, finite
+  numbers, or booleans inside ordinary fields and nested JSON declarations, rejecting
+  out-of-domain values without echoing them in diagnostics.
+- Validated strings preserve bounded, case-sensitive structural codes from open domains
+  using a package-owned portable alphabet, refusing credential-shaped and malformed
+  text without consumer regexes, callbacks, or static identifier lists.
+- Keyed hexadecimal and GTIN pseudonyms preserve reviewed database constraints, while
+  fixed-width digest recipes derive fingerprints only from explicitly named sanitized
+  columns and reject missing, excluded, duplicate, or cyclic inputs.
+- A single GTIN recipe can declare reviewed `allowedLengths`, preserving each source
+  value's 8-, 12-, 13-, or 14-digit shape and check digit even inside structured JSON.
+- Keyed URL pseudonyms replace private HTTPS URLs with deterministic, bounded HTTPS
+  loopback paths without retaining source hosts, paths, credentials, queries, or tokens.
+- Bounded binding substitution can retain permitted surrounding text while replacing
+  exact occurrences of a reviewed UUID with its corresponding keyed UUID pseudonym.
+- External PostgreSQL readers can declare a bounded exact allowlist of provider-owned
+  permission groups. Rehearsal verifies safe membership options, group attributes,
+  nesting, view ownership, and the complete effective privilege surface.
+
+### Documentation
+
+- First-time users now have a short recovery table for interrupted setup, failed
+  upgrades, port conflicts, missing OAuth credentials, and low Docker capacity.
+- The configuration guide documents a safe manual move to the project root, separating
+  config-file-relative JavaScript imports from project-root-relative Rehearsal paths.
+- The sanitization guide documents nullable and multi-column ownership, heterogeneous
+  JSON values, runtime-keyed dictionaries, keyed HTTPS replacements, bounded identity
+  substitution, and their fail-closed boundaries.
+
+### Fixed
+
+- Source preparation now stores and reads each target's access receipt and owner-only
+  reader credential under its configured baseline artifact directory. Nested and
+  multi-target state roots no longer collide, and retirement refuses a receipt from a
+  different target root.
+- Supabase Storage source preparation now recursively traverses real folder placeholder
+  entries while keeping the approved prefix, path, depth, object-count, per-object, and
+  total-byte boundaries fail closed.
+- Approved-owner selection now rejects non-finite numeric values in every declared
+  owner column before choosing a privacy branch, including when another column already
+  matches the approved owner.
+- Pseudonymized canonical integer dictionary keys now share the same keyed identity
+  mapping as numeric columns and nested numeric values using the same namespace, so
+  runtime maps keep their reviewed cross-representation joins.
+- External-reader membership mismatches now return a redacted, actionable source
+  authorization refusal instead of an internal-failure diagnostic.
+- All external-reader privilege, expiration, readable-surface, and security-definer
+  denials now use the same `SOURCE_AUTHORIZATION_REFUSED` diagnostic and exit code 3.
+- Identity claims now sequence PostgreSQL reads on their single transaction client,
+  avoiding deprecated overlapping queries and remaining compatible with pg 9.
+
+## [0.1.0-beta.13] - 2026-10-05
+
+### 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
@@ -45,7 +45,9 @@ For an ordinary npm application install, Rehearsal safely creates a commented
 `rehearsal.config.mjs` in the project root, adds only its local-artifact entries to
 `.gitignore`, and prepares the isolated local runtime configuration. It detects the
 project name, database target, migration paths, commands, and free ports. Review lines
-marked `CHECK`, then open the guide. Existing files are never overwritten.
+marked `CHECK`, then open the guide. Existing files are never overwritten. If a supported
+root or nested config already exists, Rehearsal reports that active path and does not
+create a competing file; see [Configuration](docs/configuration.md#workspaces-and-custom-paths).
 
 If install scripts are disabled or the workspace root is ambiguous, installation makes
 no guess. Run `npx rehearsal` inside the application and choose **Set the stage** for the
@@ -169,7 +171,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/configuration.md

@@ -130,15 +130,20 @@ All paths resolve inside the consuming project. The artifact directory must be n
 `.rehearsal`; this is an intentional deletion guard. `runtimeWorkdir` must be its
 `runtime` child, and the generated application environment file must remain inside it.
 
-Rehearsal never overwrites this config. To start over, move the existing file somewhere
-safe, run setup again, and compare the two files before deleting either one.
-
+Rehearsal never overwrites this config. Do not move it merely to inspect a newer template.
 After upgrading, run `npx rehearsal init` to print the current release's generated
 template beside the path of your existing config. This comparison is read-only; adding a
 new optional key remains your decision. `npx rehearsal init --write` still refuses to
 replace an existing config. Rehearsal lists important optional settings that are
 available but not enabled before printing the template, so they are easier to find.
 
+If setup was interrupted after creating only some files, rerun
+`npx rehearsal setup --write`. It recreates missing generated files while preserving every
+existing config and local runtime file. When a config itself is invalid, keep it as a
+backup, generate a fresh file, and manually carry over only reviewed settings. See
+[Getting started](getting-started.md#if-setup-or-an-upgrade-is-interrupted) for the short
+recovery table.
+
 ### Workspaces and custom paths
 
 For an npm workspace, automatic creation proceeds only when exactly one application
@@ -151,8 +156,38 @@ checkout never receive project files.
 
 Supported existing config paths—including
 `infrastructure/rehearsal/rehearsal.config.mjs`—are preserved, and a second root config
-is not created. Use `--config=<project-relative-path>` for other explicit paths when
-running commands.
+is not created. The install hook reports the exact active path when npm displays lifecycle
+output, and setup always prints it. `npx rehearsal init --json` is the package-manager-
+independent way to check the `destination`. Rehearsal checks the supported root filenames
+first and then the supported nested filenames; finding any one of them prevents automatic
+creation of another. Use
+`--config=<project-relative-path>` for other explicit paths when running commands.
+
+### Move an existing config to the project root
+
+Relocation is deliberately manual because the config may contain reviewed settings and
+JavaScript imports. Rehearsal will never move it or create a competing root file.
+
+From the directory containing `package.json`:
+
+1. Stop active Rehearsal commands and confirm the current path with
+   `npx rehearsal init --json`.
+2. Make a backup outside every supported discovery path, such as
+   `.rehearsal/config-backups/rehearsal.config.mjs`.
+3. Move—do not copy—the active file to `./rehearsal.config.mjs`. Use `git mv` when it is
+   tracked so review history remains clear.
+4. Update relative JavaScript `import` specifiers inside the moved file. Imports resolve
+   from the config file's own folder, so a nested `../../something.mjs` import usually
+   changes after moving to the root.
+5. Leave config values such as `migrationDirectory`, `sanitizationPolicy`,
+   `runtimePolicy`, `identityPolicy`, and `dependentTargets[].configPath` unchanged unless
+   the referenced project file also moved. Rehearsal resolves those values from the
+   project root, not from the config file's folder.
+6. Run `npx rehearsal init --json`, confirm its `destination` is
+   `rehearsal.config.mjs`, then run `npx rehearsal doctor` and review the Git diff.
+
+If validation fails, restore the backup to its original path. Do not run setup while the
+move is half-finished; setup may correctly conclude that no supported config exists.
 
 `preparation.privacyKey` must stay inside `.rehearsal`; it is ignored and owner-readable
 only. Source, runtime, and identity policy files are declarations that may be reviewed in

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:
 
@@ -47,6 +48,11 @@ especially:
 - the application start and proof commands;
 - the local ports.
 
+If a supported configuration already exists elsewhere—such as
+`infrastructure/rehearsal/rehearsal.config.mjs`—the installer reports that exact active
+path and does not generate a competing root file. Keep using it, or follow the explicit
+[root relocation guide](configuration.md#move-an-existing-config-to-the-project-root).
+
 If lifecycle scripts were disabled, a global/cache install was used, or a workspace has
 more than one possible application, no project files are created automatically. Run
 `npx rehearsal` inside the intended application, choose **Set the stage**, select
@@ -179,6 +185,29 @@ config during an upgrade. After upgrading, run `npx rehearsal init` to see impor
 optional settings you have not enabled and compare your file with the installed
 release's current template.
 
+### If setup or an upgrade is interrupted
+
+Do not delete `.rehearsal/` or your existing config. Start with:
+
+```bash
+npx rehearsal doctor
+npx rehearsal init
+```
+
+Use the reported problem to choose the smallest recovery:
+
+| Problem                             | Safe recovery                                                                                                                                                              |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A generated runtime file is missing | Run `npx rehearsal setup --write`. Existing files stay unchanged; only missing files are created.                                                                          |
+| A port is already in use            | Stop the conflicting local process or choose new dedicated ports, then rerun setup.                                                                                        |
+| The config is malformed             | Move it to a backup name, run `npx rehearsal setup --write`, then copy reviewed choices into the new file.                                                                 |
+| OAuth credentials are missing       | Create the ignored file named by `supabase.authentication.environmentFile`, add only the declared keys, and run `chmod 600` on it. Ambient shell credentials are not used. |
+| An npm upgrade fails                | Keep the existing config, baseline, and lockfile. Restore dependencies with your package manager, then run `npx rehearsal init` before retrying.                           |
+| Docker storage is low               | Run `npx rehearsal cleanup` for an exact preview. Rehearsal never performs a global Docker prune or silently removes volumes.                                              |
+
+`setup --write` and package installation never replace a config. If an existing file is
+invalid, Rehearsal fails closed and leaves it available for comparison.
+
 ## Files Rehearsal creates
 
 - `rehearsal.config.mjs` — reviewed project configuration

package/docs/production-source.md

@@ -23,6 +23,15 @@ The privacy key stays ignored under `.rehearsal`. The policy is safe to review i
 control because it contains hashes and environment-variable names, not credentials,
 URLs, or raw owner identifiers.
 
+`credentialFile` must be inside the selected target's
+`baseline.artifactDirectory`, under its `secrets` folder. With the default artifact
+directory, use `.rehearsal/secrets/source-reader.env`. For a target whose artifact
+directory is `targets/primary/.rehearsal`, use
+`targets/primary/.rehearsal/secrets/source-reader.env` and place `privacyKey` there as
+well. Rehearsal stores that target's access receipt beside its baseline at
+`targets/primary/.rehearsal/source-access-receipt.json`; separate targets never share
+the receipt or credential.
+
 ## 2. Declare the source boundary
 
 `source-access-policy.json` uses this shape:
@@ -33,6 +42,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 +71,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 +80,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 +110,92 @@ 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",
+    "allowedMemberships": ["provided_rehearsal_readers"],
+    "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; privileged role attributes; executable non-system security-definer functions;
+a reader-owned view; or a database-enforced expiration beyond
+`maximumValidForMinutes`.
+
+This audit is intentionally conservative: an object-level table, column, sequence, or
+function grant remains disallowed even when its schema currently lacks `USAGE`. Do not
+use schema visibility to hide stale grants. Revoke the object grant or move the approved
+surface behind the reviewed export views; this also avoids relying on behavior of an
+already-open or prepared database session.
+
+An external login may inherit its narrow permissions from provider-owned group roles.
+List every direct group in `allowedMemberships`; omit the field or use `[]` when the
+login has direct grants only. Rehearsal requires the observed membership set to match
+that list exactly. Every allowed group must be non-login and non-privileged, grant
+inheritance to the login, disable both `SET ROLE` and membership delegation, inherit no
+other role, and own none of the export views. PostgreSQL versions that cannot prove the
+per-membership role-switch setting are refused. Rehearsal still evaluates the login's
+complete effective read, write, sequence, and executable-function surface after those
+checks. Adding, removing, or changing a group changes the reviewed plan digest.
+
 `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.
+Supabase folder entries are traversed recursively beneath that exact prefix. Folder
+entries count toward `maximumObjects`, so the same reviewed limit bounds both the
+directory walk and transferred files. Empty files remain files and are copied normally.
 
 ## 3. Use executable privacy policy version 2
 
@@ -98,6 +205,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 +241,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
         }
       ]
     }
@@ -126,10 +256,13 @@ 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.
+Supported recipes are intentionally small: keyed UUID/email/text/integer/hex/GTIN/URL
+pseudonyms, hexadecimal digests of explicitly named sanitized columns, explicit
+constants, bounded or grouped date shifts, identity-aware path mappings, bounded
+reviewed-identity substitution inside retained text, and fully classified JSON
+structures. Unknown tables, columns, digest inputs, 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 +279,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 +295,36 @@ 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.
+
+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.
 
-`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.
+Apply, refresh, and retire always resolve those local files from the active config's
+`baseline.artifactDirectory`. If you switch configs or target roots, Rehearsal refuses
+to retire a receipt from the other target. It also refuses an existing receipt or
+credential rather than overwriting or adopting it.
 
 ## Limits
 

package/docs/releasing.md

@@ -32,9 +32,11 @@ publication must change and prove the workflow before narrowing that permission.
 1. Start from protected `main` on a dedicated ticketed release branch.
 2. Verify the exact version, changelog, compatibility notes, and packed file list.
 3. Run unit and contract tests, formatting, package-content and secret audits,
-   dependency audit, clean tarball installation, and the installed Docker fixture.
-4. Have a developer unfamiliar with the implementing project follow the clean-project
-   onboarding. Correct and retest the first confusing, missing, or wrong instruction.
+   dependency audit, packed onboarding, clean tarball installation, and the installed
+   Docker fixtures.
+4. When an unfamiliar developer is available, have them follow clean-project onboarding.
+   Correct and retest the first confusing, missing, or wrong instruction. Record when
+   this human observation was unavailable; automated checks must not impersonate it.
 5. Change `private` to `false` only in the reviewed release change.
 6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
    executable, declared runtime dependency inventory, and dependency audit result.

package/docs/roadmap.md

@@ -29,8 +29,9 @@ Track the full breakdown in
   invalid migrations, identities, images, persistence, reset, and cleanup.
 - Run the released package in the real reporting consumer and record positives and
   negatives.
-- Directly observe any claimed Google account-picker/callback and unfamiliar-developer
-  onboarding behavior; automation cannot invent that evidence.
+- Directly observe any claimed Google account-picker/callback. Record
+  unfamiliar-developer onboarding behavior when a tester is available; automation cannot
+  invent either kind of human evidence.
 - Remove consumer integration code only after its replacement passes and that deletion
   is separately approved.