@rehearsal-db/core 0.1.0-beta.7 → 0.1.0-beta.9

package/CHANGELOG.md

@@ -5,6 +5,80 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-beta.9] - 2026-10-02
+
+### Added
+
+- Primary configurations may declare isolated dependent database targets. Rehearsal
+  validates unique ownership boundaries, combines migration approval, orders lifecycle
+  actions, runs project-owned preparation and proofs, and previews cleanup across the
+  complete stack.
+- A packed-package two-target PostgreSQL fixture proves source-to-read-model preparation,
+  positive and negative assertions, reverse shutdown, and exact cleanup without a
+  project-owned container engine.
+- A separately opted-in, exact-digest PostgreSQL source-access lifecycle with scoped
+  temporary roles/views, deny checks, owner-only credentials, and exact retirement.
+- Bounded coherent baseline refresh with executable privacy policy version 2, stable
+  keyed pseudonyms, atomic activation, capacity limits, and drift/interruption safety.
+- Approved Supabase Storage inventory/transfer with bucket-prefix, size, path, version,
+  and exact-byte controls.
+- Declarative runtime prerequisites and structural checks, plus exact local identity
+  association without application callback patches.
+- Package-owned application startup, local environment mapping, readiness, child-process
+  teardown, and meaningful positive/negative HTTP proof orchestration.
+- An exact-preview `refresh` command that builds a verified replacement first, resets the
+  complete local runtime stack, rolls back on runtime failure, and only then prunes the
+  specifically reviewed old baseline generations.
+
+### Changed
+
+- Shipped source, runtime adapters, repository-only verification, and tests now use a
+  domain-based layout with documented placement rules and contract checks.
+- Generated configs include a commented dependent-target example, and the documentation
+  explains that avoiding server errors is not a sufficient positive-path proof.
+- Generated configs explain the optional standalone policy paths, direct local runtime
+  environment mappings, and application readiness contract.
+- Source, privacy, runtime, identity, onboarding, and security documentation now describe
+  the package-owned declarative workflow and its separate authorization boundaries.
+
+### Fixed
+
+- Supabase restores now install declared schemas and extensions before restoring
+  extension-dependent objects, preserve the original `public` schema privilege baseline,
+  and add declared triggers only after their functions exist.
+- Supabase runtime environments now include a validated loopback-only database URL and
+  standard PostgreSQL variables for package-owned commands.
+- Identity claims can safely replace complete signup defaults, require application role
+  references, remap declared text/JSONB and Storage object paths, and verify token-hook
+  claims while refusing edited or independent local account data.
+- Baselines and restore checks now identify relations by schema and table, default old
+  records to `public`, and restore same-named tables in separate schemas independently.
+- Identity claims can preserve immutable audit authorship while transferring the active
+  account, and retain only the synthetic Auth actor required by that history.
+- Storage path transfer now copies through the local Supabase API, verifies exact bytes,
+  rolls back staged copies on database failure, and removes the old physical objects
+  only after the database commit succeeds.
+- Identity Storage scopes now accept restored objects whose owner is unset, refuse
+  conflicting owners, and verify the destination owner before rewriting application
+  paths.
+- Runtime-policy seeds may explicitly follow a named identity association, so later
+  verification checks the transferred key without recreating an obsolete placeholder
+  role.
+- Failed project proofs always report their exit status and bounded output byte counts
+  without echoing arbitrary project logs.
+- State-changing commands now use a project-wide operation lock and detect replacement
+  of the installed Rehearsal package while an operation is running.
+- Identity claims now refuse to rewrite copied Storage paths when referenced physical
+  objects are missing.
+
+## [0.1.0-beta.8] - 2026-10-02
+
+### Fixed
+
+- Lifecycle commands now preserve an explicit `--config=<path>` through runtime
+  selection and execution. A command cannot silently operate on the default config's
+  baseline, runtime identity, ports, or cleanup target instead.
+
 ## [0.1.0-beta.7] - 2026-10-02
 
 ### Added
@@ -194,7 +268,9 @@ 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.7...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.9...HEAD
+[0.1.0-beta.9]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.8...v0.1.0-beta.9
+[0.1.0-beta.8]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.7...v0.1.0-beta.8
 [0.1.0-beta.7]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.6...v0.1.0-beta.7
 [0.1.0-beta.6]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.5...v0.1.0-beta.6
 [0.1.0-beta.5]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.4...v0.1.0-beta.5

package/COMPATIBILITY.md

@@ -22,6 +22,18 @@ public API. Supporting additional database families, package managers, or operat
 systems is not implied by the 0.x contract.
 
 The PostgreSQL target covers timestamped SQL migrations running in a dedicated local
-`postgres` Docker image. It does not imply support for hosted connection strings,
-existing unmanaged servers, ORM-specific nested migration formats, Supabase Storage, or
-Supabase Auth emulation.
+`postgres` Docker image. Runtime commands reject hosted connection strings and existing
+unmanaged servers. The separately opted-in PostgreSQL preparation boundary may use a
+reviewed, short-lived source reader; this does not make a hosted database a runtime
+target. ORM-specific nested migration formats remain unsupported. Supabase Storage and
+Auth behavior apply only to the Supabase runtime.
+
+A primary config may declare flat dependent PostgreSQL or Supabase targets. Each target
+must have its own complete config, immutable baseline, project ID, ports, environment
+file, and artifact directory. Nested dependency graphs and shared runtime ownership are
+not supported.
+
+Executable privacy policy version 2, source-access policy version 1, runtime policy
+version 1, and identity policy version 1 are strict declarative contracts. Unknown
+fields fail closed. They do not imply support for arbitrary transformations, SQL,
+provider administration, consent decisions, or every PostgreSQL extension.

package/README.md

@@ -4,8 +4,14 @@ Rehearsal tests PostgreSQL and Supabase migrations on your computer before you r
 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.
 
-Rehearsal never connects to a hosted database. It is a migration-testing tool, not a
-backup system or a production deployment tool.
+Projects with a separate publication or read-model database can declare it as a
+dependent target. Rehearsal then manages the complete isolated runtime stack.
+
+Normal rehearsal commands never connect to a hosted database. An optional, separately
+approved preparation workflow can create a short-lived read-only export surface, stream
+it through a reviewed privacy policy, and retire the access again. It is never part of
+`run`, `reset`, `migrate`, or application launch. Rehearsal is not a backup system or a
+production deployment tool.
 
 > Rehearsal is in public beta. Use it on a branch and keep a working backup of your
 > project.
@@ -52,7 +58,8 @@ Rehearsal itself never downloads a database image during a rehearsal.
 - **Runtime:** the disposable local database where the rehearsal happens.
 
 The baseline may contain synthetic data or properly sanitized production-shaped data.
-Start with synthetic data. Rehearsal does not copy or sanitize production data for you.
+Start with synthetic data. Real source preparation is opt-in and requires separate
+source-owner approval; see [Standalone workflow](docs/standalone-workflow.md).
 
 ## The normal workflow
 
@@ -63,6 +70,11 @@ Start with synthetic data. Rehearsal does not copy or sanitize production data f
 5. Run the rehearsal and your application proof.
 6. Test the local application, then verify, reset, stop, or discard the runtime.
 
+For an approved production-shaped copy, the optional sequence is `source plan`, `source
+apply`, `refresh`, and `source retire`. `refresh` verifies the replacement before it
+resets the local runtime or removes an old copy. Every source-side or identity change has
+its own exact confirmation digest.
+
 When local disk space gets tight, choose **Clean up disk space** in the guide. Rehearsal
 previews old baseline generations first and keeps runtime or shared-image removal
 explicit.
@@ -85,15 +97,16 @@ loads.
 
 ## Supported today
 
-| Environment                                 | Support                |
-| ------------------------------------------- | ---------------------- |
-| Supabase CLI projects                       | Supported              |
-| Ordinary PostgreSQL in local Docker         | Supported              |
-| macOS and Linux                             | Supported              |
-| WSL                                         | Experimental           |
-| Native Windows                              | Not yet supported      |
-| Hosted database URLs                        | Intentionally rejected |
-| MySQL, MongoDB, and other database families | Not yet supported      |
+| Environment                                      | Support                |
+| ------------------------------------------------ | ---------------------- |
+| Supabase CLI projects                            | Supported              |
+| Ordinary PostgreSQL in local Docker              | Supported              |
+| macOS and Linux                                  | Supported              |
+| WSL                                              | Experimental           |
+| Native Windows                                   | Not yet supported      |
+| Hosted database URLs                             | Intentionally rejected |
+| Optional read-only PostgreSQL source preparation | Explicit opt-in beta   |
+| MySQL, MongoDB, and other database families      | Not yet supported      |
 
 See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact support contract.
 
@@ -101,6 +114,7 @@ See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact support contract.
 
 Start here:
 
+- [Documentation map](docs/README.md) — find the right guide quickly
 - [Getting started](docs/getting-started.md) — set up your own project
 - [Safe hands-on tutorial](docs/tutorial.md) — try the full flow in a disposable project
 - [Troubleshooting](docs/troubleshooting.md) — fix common setup problems
@@ -115,7 +129,10 @@ Reference:
 - [Security model](docs/security-model.md)
 - [Project adapters](docs/adapters.md)
 - [Production data boundary](docs/production-source.md)
-- [Glossary and architecture](docs/glossary.md)
+- [Standalone workflow and security gates](docs/standalone-workflow.md)
+- [Runtime and local identity policies](docs/runtime-policies.md)
+- [Glossary](docs/glossary.md)
+- [Repository architecture](docs/architecture.md)
 - [Release process](docs/releasing.md)
 
 ## Getting support
@@ -137,6 +154,7 @@ Use Node.js 24, run `npm ci`, then run:
 
 ```bash
 npm run check
+npm run test:fixture:standalone
 npm run test:fixture:postgresql
 npm run test:fixture
 ```

package/docs/README.md

@@ -0,0 +1,29 @@
+# Documentation map
+
+## Start here
+
+- [Getting started](getting-started.md)
+- [Hands-on tutorial](tutorial.md)
+- [Troubleshooting](troubleshooting.md)
+
+## Understand the safety model
+
+- [Baselines](baselines.md)
+- [Sanitization](sanitization.md)
+- [Production source boundary](production-source.md)
+- [Security model](security-model.md)
+
+## Configure Rehearsal
+
+- [Configuration](configuration.md)
+- [Commands](commands.md)
+- [Runtime policies](runtime-policies.md)
+- [Database adapters](adapters.md)
+- [Standalone PostgreSQL workflow](standalone-workflow.md)
+
+## Maintain the project
+
+- [Repository architecture](architecture.md)
+- [Release process](releasing.md)
+- [Roadmap](roadmap.md)
+- [Glossary](glossary.md)

package/docs/adapters.md

@@ -5,8 +5,17 @@ database driver starts and manages a kind of local database, such as Supabase or
 PostgreSQL. A project
 runtime adapter adds narrowly scoped application behavior after that database is ready.
 
-Adapters are an advanced escape hatch for project-specific restore behavior. They live
-in the consuming repository and are loaded only from the path declared in config.
+Adapters are a backward-compatible advanced escape hatch for project-specific restore
+behavior. New projects should first use `runtimePolicy`, `identityPolicy`, application
+environment mappings, HTTP proofs, and dependent targets. Those package-owned paths are
+portable and reject executable declarations.
+
+If the application needs another database, use
+[`dependentTargets`](configuration.md#dependent-databases) instead of opening a second
+connection or managing another container from a runtime adapter. Rehearsal owns that
+database's identity, ports, lifecycle, verification order, and cleanup preview; the
+project declares its baseline and proof. `prepareCommand` remains available for legacy
+schema-specific transformations.
 
 An adapter may export:
 
@@ -18,10 +27,10 @@ An adapter may export:
 Each hook must return the documented status shape expected by the engine. It receives a
 local SQL executor; it should not open another connection or perform network access.
 
-Good adapter responsibilities include mapping sanitized application identities to local
-Auth users and verifying a domain-specific relationship after restore. Bad responsibilities
-include extracting production data, embedding credentials, contacting hosted services,
-or weakening the engine's local-only checks.
+Use an adapter only when the documented declarative formats clearly reject a required
+local behavior. Extracting production data, embedding credentials, contacting hosted
+services, weakening local-only checks, or reimplementing container lifecycle is never an
+adapter responsibility.
 
 Keep adapters small, deterministic, tested, and visibly project-owned. If a behavior is
 generic across unrelated projects, propose it for the engine instead of copying it into

package/docs/architecture.md

@@ -0,0 +1,58 @@
+# Repository architecture
+
+Rehearsal separates shipped product code, repository automation, tests, fixtures, and
+documentation so each file has one obvious home.
+
+```text
+rehearsal-db/
+├── src/                    shipped package code
+│   ├── application/       application lifecycle and HTTP proofs
+│   ├── baseline/          sanitized baseline creation and validation
+│   ├── cli/               the `rehearsal` executable
+│   ├── identity/          local account and Storage association
+│   ├── project/           configuration, setup, and support
+│   ├── runtime/           plans and disposable-runtime lifecycle
+│   ├── shared/            small target-neutral utilities
+│   ├── source/            approved source access and refresh
+│   └── targets/           PostgreSQL and Supabase adapters
+├── scripts/
+│   ├── runtime/           shipped internal runtime launcher
+│   └── verification/      repository-only package and fixture proofs
+├── tests/
+│   ├── unit/              mirrors the `src/` domains
+│   ├── integration/       multi-module and terminal behavior
+│   ├── contracts/         public documentation and package promises
+│   └── fixtures/          disposable example projects
+└── docs/                  user and maintainer documentation
+```
+
+## Boundaries
+
+- `src/` must never import from tests or repository-only verification scripts.
+- Database-specific lifecycle behavior belongs in `src/targets/`.
+- `scripts/verification/` is never included in the npm package.
+- Public consumers use only the paths declared in `package.json#exports`.
+- Unit tests mirror their source domain. Cross-domain workflows belong in
+  `tests/integration/`; durable public promises belong in `tests/contracts/`.
+
+## CLI modules
+
+The executable is split by responsibility so no command file becomes a second
+application layer:
+
+- `rehearsal.mjs` starts the process and dispatches commands.
+- `arguments.mjs` owns the command-line contract and mutation classification.
+- `guided.mjs` owns the interactive home screen and first-run questions.
+- `runtime_commands.mjs` coordinates local runtimes and project proofs.
+- `source_commands.mjs` coordinates approved source access and refresh.
+- `renderers.mjs` formats human-readable results without changing state.
+- `terminal.mjs` owns prompts, colors, and terminal exit behavior.
+
+## Adding something new
+
+1. Put policy and reusable behavior in the domain that owns it.
+2. Put target-specific implementation behind the target boundary.
+3. Add its focused test under the matching `tests/unit/` domain.
+4. Add an integration or contract test only when behavior crosses domains or becomes a
+   public promise.
+5. Update the documentation map when adding a new guide.

package/docs/baselines.md

@@ -15,6 +15,20 @@ safe row.
 { "table": "widgets", "row": { "id": 1, "name": "Synthetic Widget" } }
 ```
 
+`public` is the default schema. Name another schema explicitly when needed:
+
+```json
+{
+  "schema": "app_api",
+  "table": "publication_products",
+  "row": { "id": 1 }
+}
+```
+
+Use the same optional `schema` on that table in the sanitization policy. Rehearsal keeps
+same-named tables in different schemas separate. An undeclared schema or table is
+rejected.
+
 Use synthetic or reviewed sanitized values. A `.json` array is not NDJSON and will be
 rejected.
 
@@ -67,7 +81,14 @@ npx rehearsal baseline create \
 ```
 
 Add `--assets=rehearsal/assets.json` only when using approved Supabase Storage files.
-Rehearsal validates everything and shows counts before activation. It never extracts data.
+Rehearsal validates everything and shows counts before activation. These commands read
+project-local files only.
+
+The separately enabled `baseline refresh` command can stream a reviewed source through
+privacy policy version 2. It stages a private generation, verifies capacity, counts,
+checksums, source schema, migration evidence, privacy coverage, and drift, then switches
+the active symlink atomically. Failure or interruption removes the staged generation and
+preserves the prior active baseline and edited runtime.
 
 ## Why historical migrations are locked
 

package/docs/commands.md

@@ -30,7 +30,59 @@ bare `npx rehearsal` prints help instead of waiting for input.
 | `npx rehearsal baseline create --records=<path> --ledger=<path>`  | Create and activate a baseline from safe local inputs. |
 
 Add `--assets=<manifest.json>` to `baseline create` only for approved local Supabase
-Storage files. Baseline commands never extract data or connect to another database.
+Storage files. `baseline create` and `baseline prepare` are local-only.
+
+## 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.    |
+
+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
+previous active baseline and edited runtime untouched when it fails. It does not reset
+the runtime.
+
+Use `refresh` for the normal end-to-end job. It first previews the exact source receipt,
+configuration receipts, runtime targets, retention rule, and old generations that may be
+removed. After exact confirmation, it builds and verifies a replacement beside the
+current baseline, resets the complete local runtime stack, then removes only the listed
+old generations. If replacement or runtime verification fails, Rehearsal reactivates the
+previous baseline and restores the previous runtime. Source-access retirement remains a
+separate approval.
+
+In short: `refresh` gets a new source copy; `reset` restores the copy you already have;
+`run` tests pending migrations against that copy.
+
+## Local identity association
+
+After an ordinary local Google or email sign-in creates a verified local Auth identity:
+
+```bash
+npx rehearsal identity plan --identity=approved-owner
+npx rehearsal identity claim --identity=approved-owner \
+  --confirm-identity=<sha256>
+```
+
+The first command shows only hashes and declared reference counts. The second updates
+only the reviewed local relational, JSON, Storage-owner, and claim locations in one
+transaction. It rejects hosted database URLs, wrong or unverified people, ambiguity, and
+stale confirmation digests.
+
+If a runtime-policy seed moves with that identity, declare its `identityAssociation` in
+the runtime policy. Later `verify` calls then require the transferred row instead of the
+obsolete placeholder key.
 
 ## Check and inspect
 
@@ -52,7 +104,7 @@ and process exit code, not parse human-facing text.
 
 | Command                                               | What it does                                                        |
 | ----------------------------------------------------- | ------------------------------------------------------------------- |
-| `npx rehearsal run --confirm-candidates=<sha256>`     | Reset, apply the exact candidates, verify, and run the app proof.   |
+| `npx rehearsal run --confirm-candidates=<sha256>`     | Reset, apply exact candidates, launch the app, and run its proofs.  |
 | `npx rehearsal migrate --confirm-candidates=<sha256>` | Apply the exact candidates without resetting existing runtime data. |
 | `npx rehearsal start`                                 | Start an existing verified runtime.                                 |
 | `npx rehearsal verify`                                | Verify the current runtime and receipt.                             |
@@ -91,17 +143,32 @@ belonging to other projects are never included. This follows
 
 ## Common options
 
-| Option                          | Meaning                                                          |
-| ------------------------------- | ---------------------------------------------------------------- |
-| `--json`                        | Return the versioned machine-readable result.                    |
-| `--verbose`                     | Show more safe detail.                                           |
-| `--debug`                       | Show the most diagnostic detail; still review it before sharing. |
-| `--plain`                       | Disable decorative interactive prompts.                          |
-| `--config=<path>`               | Use a specific config file inside the project.                   |
-| `--target=supabase\|postgresql` | Choose the setup target.                                         |
-| `--include-runtime`             | Include this project's runtime in a cleanup preview.             |
-| `--include-images`              | Include older unused Supabase images in a cleanup preview.       |
-| `--confirm-cleanup=<digest>`    | Confirm the exact cleanup set printed by the preview.            |
-| `--write`                       | Apply a setup, policy, or cleanup preview.                       |
+| Option                                 | Meaning                                                          |
+| -------------------------------------- | ---------------------------------------------------------------- |
+| `--json`                               | Return the versioned machine-readable result.                    |
+| `--verbose`                            | Show more safe detail.                                           |
+| `--debug`                              | Show the most diagnostic detail; still review it before sharing. |
+| `--plain`                              | Disable decorative interactive prompts.                          |
+| `--config=<path>`                      | Use only this config for planning and every runtime action.      |
+| `--target=supabase\|postgresql`        | Choose the setup target.                                         |
+| `--include-runtime`                    | Include this project's runtime in a cleanup preview.             |
+| `--include-images`                     | Include older unused Supabase images in a cleanup preview.       |
+| `--confirm-cleanup=<digest>`           | Confirm the exact cleanup set printed by the preview.            |
+| `--confirm-source-access=<digest>`     | Confirm one exact temporary source-access plan.                  |
+| `--confirm-source-retirement=<digest>` | Confirm exact source-access retirement.                          |
+| `--confirm-refresh=<digest>`           | Confirm an exact refresh, runtime reset, and old-copy removal.   |
+| `--identity=<name>`                    | Choose one declared local identity association.                  |
+| `--confirm-identity=<digest>`          | Confirm that exact local identity plan.                          |
+| `--write`                              | Apply a setup, policy, or cleanup preview.                       |
 
 Run `npx rehearsal --help` to print the command list available in your installed version.
+
+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,
+start, migrate, verify, stop, discard, and cleanup; it will not fall back to
+`rehearsal.config.mjs` during a runtime action.
+
+When the selected config declares `dependentTargets`, the ordinary `doctor`, `explain`,
+`candidates`, `run`, `start`, `migrate`, `reset`, `status`, `verify`, `stop`, `discard`,
+and `cleanup` commands cover the complete runtime stack. Candidate and cleanup changes
+use one combined digest, so automation approves the exact cross-target set.