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

package/CHANGELOG.md

@@ -5,6 +5,81 @@ 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
+
+- Supabase projects can declaratively configure local Google or GitHub OAuth in
+  `rehearsal.config.mjs`. Rehearsal derives the credential allowlist, injects only the
+  ignored owner-only environment values, and generates the exact loopback callback in
+  the disposable runtime without tracking secrets. Local signup requires an explicit
+  acknowledgment and is enabled only in that generated runtime copy.
+- Branded, responsive documentation is now hosted on GitHub Pages with searchable
+  navigation, light and dark themes, and automatic deployment from `main`.
+- The documentation home page and packaged README show the live monthly npm download
+  count and link directly to the npm package.
+- Packed-package onboarding acceptance now proves both fresh root-config creation and a
+  real beta.11 upgrade that preserves the user's existing configuration byte for byte.
+
+### Changed
+
+- The packaged README now links prominently to the hosted documentation, npm package,
+  and issue tracker. Package homepage metadata also points to the hosted documentation.
+- GitHub Pages publishing uses the current Node.js 24 action generations without legacy
+  runtime warnings.
+- `rehearsal init` now calls out important optional settings that are available but not
+  enabled before showing the current installed-release template.
+
+### Fixed
+
+- Existing Google or GitHub provider sections can transition to declarative ownership
+  without editing the tracked Supabase template. Rehearsal replaces only a compatible
+  section in the disposable runtime copy, while `doctor` refuses ambiguous or
+  safety-weakening provider settings before reset.
+- Multi-target plain-text plans now print each declarative OAuth callback, and `init`
+  advertises the declarative replacement even when a project still uses legacy provider
+  fields.
+
 ## [0.1.0-beta.11] - 2026-10-03
 
 ### Added
@@ -314,7 +389,8 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
   publication uses short-lived trusted OIDC, and every release tag must already exist on
   protected `main`.
 
-[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.11...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.12...HEAD
+[0.1.0-beta.12]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.11...v0.1.0-beta.12
 [0.1.0-beta.11]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.10...v0.1.0-beta.11
 [0.1.0-beta.10]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.9...v0.1.0-beta.10
 [0.1.0-beta.9]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.8...v0.1.0-beta.9

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

@@ -1,5 +1,9 @@
 # Rehearsal
 
+[![Monthly npm downloads](https://img.shields.io/npm/dm/%40rehearsal-db%2Fcore?style=flat-square&logo=npm&logoColor=white&label=npm%20downloads&labelColor=1c2a34&color=287b5c)](https://www.npmjs.com/package/@rehearsal-db/core)
+
+[Read the documentation](https://ddupasquier.github.io/rehearsal-db/) · [View on npm](https://www.npmjs.com/package/@rehearsal-db/core) · [Report a problem](https://github.com/Ddupasquier/rehearsal-db/issues)
+
 Rehearsal tests PostgreSQL and Supabase migrations on your computer before you run them
 anywhere important. It restores safe test data into a disposable local database, applies
 only the migrations you approve, and runs your project's own test command.
@@ -18,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
@@ -55,6 +59,11 @@ docker pull postgres:17-alpine
 
 Rehearsal itself never downloads a database image during a rehearsal.
 
+For local Google or GitHub sign-in, the generated config includes a commented
+`supabase.authentication` example. It names an ignored owner-only credential file;
+Rehearsal generates the provider block and local callback inside the disposable runtime.
+See [Supabase authentication](docs/configuration.md#supabase-authentication).
+
 ## Three terms you will see
 
 - **Baseline:** a locked, safe starting copy of your schema and test data.
@@ -160,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

@@ -34,25 +34,26 @@ Storage files. `baseline create` and `baseline prepare` are local-only.
 
 `setup --write` is idempotent: supported existing config files and completed runtime
 files remain unchanged, while missing safe ignore entries may be appended. On upgrades,
-`init` prints the installed release's template for comparison; `init --write` never
-replaces an existing config.
+`init` first lists important optional settings that are available but not enabled, then
+prints the installed release's template for comparison. `init --write` never replaces an
+existing config.
 
 ## Optional source preparation
 
 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
@@ -175,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. |
@@ -192,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

@@ -42,9 +42,21 @@ export default defineRehearsalConfig({
     rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
     runtimeWorkdir: ".rehearsal/runtime",
 
-    // Optional; configure both keys together.
-    // serviceEnvironmentFile: ".env.rehearsal-service.local",
-    // serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+    // Optional local OAuth connection. Secrets stay in the ignored owner-only file.
+    // Register http://127.0.0.1:58321/auth/v1/callback with the provider.
+    // authentication: {
+    //   enableLocalSignup: true,
+    //   environmentFile: ".env.rehearsal-service.local",
+    //   providers: [
+    //     {
+    //       name: "google",
+    //       clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+    //       clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+    //       skipNonceCheck: false,
+    //       emailOptional: false,
+    //     },
+    //   ],
+    // },
   },
   baseline: {
     artifactDirectory: ".rehearsal",
@@ -124,7 +136,8 @@ safe, run setup again, and compare the two files before deleting either one.
 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.
+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.
 
 ### Workspaces and custom paths
 
@@ -247,19 +260,72 @@ negative controls, such as unauthorized, malformed, withheld, or missing records
 response that merely avoids a server error does not prove that eligible data was
 published or can be found.
 
-## Supabase service environment
+## Supabase authentication
 
-Some local identity providers need a client ID and secret. Configure both fields or
-neither:
+Rehearsal can configure a Google or GitHub OAuth connection in its disposable local
+Supabase runtime. Declare the provider and the names of its credential variables:
 
 ```ts
-serviceEnvironmentFile: ".env.rehearsal-service.local",
-serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+authentication: {
+  enableLocalSignup: true,
+  environmentFile: ".env.rehearsal-service.local",
+  providers: [
+    {
+      name: "google",
+      clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+      clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+      skipNonceCheck: false,
+      emailOptional: false,
+    },
+  ],
+},
+```
+
+Create the ignored file, add the values, then restrict it to your account:
+
+```dotenv
+REHEARSAL_GOOGLE_CLIENT_ID=your-local-oauth-client-id
+REHEARSAL_GOOGLE_CLIENT_SECRET=your-local-oauth-client-secret
+```
+
+```bash
+chmod 600 .env.rehearsal-service.local
 ```
 
-The file must be ignored, owner-readable only, and contain only the exact allowlisted
-names. These credentials may authorize an identity handshake, but the callback must
-terminate at local Auth. They do not grant hosted database access.
+Register `http://127.0.0.1:<apiPort>/auth/v1/callback` with the provider, using the
+`runtime.apiPort` value from this config. `rehearsal explain` also prints the exact URL.
+Rehearsal writes that callback and `env(...)` references into the disposable runtime; it
+never copies credential values into tracked configuration. Use `name: "github"` and
+distinct GitHub variable names for GitHub. Duplicate providers, reused variable names,
+unsupported providers, extra keys, and a template that already owns the same provider
+are refused. This follows Supabase's documented
+[`env()` configuration pattern](https://supabase.com/docs/guides/local-development/managing-config).
+
+`enableLocalSignup: true` explicitly acknowledges that disposable local Auth may create
+the temporary user returned by OAuth. Rehearsal changes the generated runtime copy only;
+the tracked Supabase template and every hosted project remain unchanged.
+
+The older `serviceEnvironmentFile`, `serviceEnvironmentVariables`, and
+`safety.authenticationProviders` fields remain compatible for projects that manually
+own their Supabase provider TOML. Do not combine those fields with the declarative
+`authentication` block.
+
+To migrate a manual Google or GitHub setup, replace those three legacy config fields
+with the `authentication` block together. The tracked Supabase template may keep its
+existing provider section: Rehearsal replaces a compatible legacy section only in the
+generated disposable runtime copy. The section may contain `enabled`, `client_id`,
+`secret`, `redirect_uri`, `skip_nonce_check`, and `email_optional`. The latter two must
+match the explicit `skipNonceCheck` and `emailOptional` declarations, which default to
+`false`. Keep them false unless the provider integration has a reviewed need; Supabase
+warns in its [CLI configuration reference](https://supabase.com/docs/guides/local-development/cli/config#auth.external.provider.skip_nonce_check)
+that skipping nonce validation reduces replay protection. Unknown settings,
+duplicate sections, nested provider tables, or mismatched options fail
+`rehearsal doctor` before reset. Rehearsal never edits the tracked template during this
+transition.
+
+Provider connection and copied-account association are separate. This block lets the
+ordinary application sign-in reach local Auth. An optional `identityPolicy` decides
+whether that verified local identity may claim a reviewed copied account.
 
 ## Safety fields
 

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:
 
@@ -55,6 +56,13 @@ Supabase or PostgreSQL, and approve the same safe setup preview.
 The proof command should check behavior changed by the migration. A test that only checks
 whether the home page loads is usually too weak.
 
+If the sandbox needs Google or GitHub sign-in, uncomment
+`supabase.authentication` in `rehearsal.config.mjs`. Add the named credentials to
+`.env.rehearsal-service.local`, run `chmod 600 .env.rehearsal-service.local`, and
+register the local callback printed in the config. See
+[Supabase authentication](configuration.md#supabase-authentication). Rehearsal keeps the
+values out of tracked files and generates the disposable provider configuration for you.
+
 ## 3. Prepare safe baseline inputs
 
 A **baseline** is the locked starting point restored before each rehearsal. Start with a
@@ -168,7 +176,9 @@ complete reference and [Troubleshooting](troubleshooting.md) when a check fails.
 
 Running setup again is safe: existing configuration and runtime files are reported as
 unchanged. Rehearsal only adds missing ignore entries. It never refreshes an existing
-config during an upgrade.
+config during an upgrade. After upgrading, run `npx rehearsal init` to see important
+optional settings you have not enabled and compare your file with the installed
+release's current template.
 
 ## Files Rehearsal creates
 

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/runtime-policies.md

@@ -157,8 +157,10 @@ graph without an application callback patch:
 
 Authentication has three separate parts:
 
-1. The local Supabase configuration enables Google, GitHub, or email sign-in and reads
-   any provider credentials from the environment.
+1. `config.supabase.authentication` can enable a Google or GitHub connection in local
+   Supabase and reads its credentials from the ignored owner-only environment file.
+   Existing projects may still own that local provider TOML manually. Email sign-in does
+   not use an OAuth credential declaration.
 2. The application completes the ordinary sign-in and receives a normal Supabase
    session. Rehearsal does not intercept the callback.
 3. The identity policy matches that verified local identity and transfers only the