@rehearsal-db/core 0.1.0-beta.1 → 0.1.0-beta.10

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

@@ -1,33 +1,113 @@
 # Baselines
 
-A baseline is an immutable, digest-addressed starting point for a disposable runtime.
-It binds sanitized rows, represented migration bytes, optional Storage assets, schema
-evidence, policy identity, and verification metadata.
+A baseline is the locked starting point for every rehearsal. It combines safe rows with
+the exact historical migrations that created their schema. Resetting the runtime always
+returns to this point.
 
-## Generation lifecycle
+## Required inputs
 
-New content is written to a private building directory. Individual files are checksummed
-and made read-only. A complete manifest is verified before an atomic `current` symlink
-selects the generation. An interrupted build cannot replace the active baseline.
+### Records
 
-## Migration lineage
+Records use NDJSON: one complete JSON object per line. Each object names a table and one
+safe row.
 
-The manifest records the exact ordered historical prefix. A migration with the same
-timestamp but different bytes is modified history, not a candidate. New migrations must
-form an ordered suffix. Candidate confirmation binds the exact filenames and checksums.
+```json
+{ "table": "widgets", "row": { "id": 1, "name": "Synthetic Widget" } }
+```
 
-## Restore lifecycle
+`public` is the default schema. Name another schema explicitly when needed:
 
-`reset` destroys only the explicitly labelled local runtime, replays the represented
-schema, streams sanitized rows, restores checksummed local Storage assets, reapplies
-normal enforcement, and verifies counts and foreign keys. A failure removes trust and
-cannot leave a successful receipt.
+```json
+{
+  "schema": "app_api",
+  "table": "publication_products",
+  "row": { "id": 1 }
+}
+```
 
-## Persistence model
+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.
 
-The baseline never changes during normal use. The restored runtime is writable and its
-changes persist across application restarts while the local containers remain. Run
-`reset` to discard sandbox changes and return to the exact baseline.
+Use synthetic or reviewed sanitized values. A `.json` array is not NDJSON and will be
+rejected.
 
-Treat baseline files as sensitive even after sanitization: owner-only permissions,
-ignored paths, encrypted disks, bounded retention, and explicit deletion are prudent.
+### Migration ledger
+
+The ledger is a JSON array in migration order:
+
+```json
+[
+  {
+    "version": "20260101000000",
+    "name": "create_widgets",
+    "statements": [
+      "create table public.widgets (id bigint primary key, name text not null)"
+    ]
+  }
+]
+```
+
+Each entry must match the version, name, order, and SQL represented by the historical
+migration. Equivalent-looking SQL is not enough. Generate this evidence with reviewed
+project tooling for a real migration history; do not reconstruct a large ledger by hand.
+
+### Sanitization policy
+
+The policy records the approved treatment of every included table and column. The guide
+can create a shape-only draft from the records and walk you through its review. A draft
+with undecided fields cannot become a baseline. See [Sanitization](sanitization.md).
+
+### Storage manifest (optional)
+
+Supabase projects may include a bounded set of approved local Storage files. Plain
+PostgreSQL projects do not support Supabase Storage. Every file is checksum-verified and
+must remain inside the project.
+
+## Create a baseline
+
+The guided action is recommended:
+
+```bash
+npx rehearsal
+```
+
+For automation, use explicit safe local paths:
+
+```bash
+npx rehearsal baseline create \
+  --records=rehearsal/sanitized-data.ndjson \
+  --ledger=rehearsal/migration-ledger.json
+```
+
+Add `--assets=rehearsal/assets.json` only when using approved Supabase Storage files.
+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
+
+The baseline records the exact ordered historical migration files. If a file keeps the
+same timestamp but its bytes change, Rehearsal reports modified history instead of
+treating it as a new candidate. New migrations must form an ordered suffix after the
+baseline cutoff.
+
+## What reset does
+
+`reset` removes only the exactly labeled local runtime, rebuilds the represented schema,
+loads the safe rows, restores approved Storage files when present, and verifies counts and
+relationships. A failed restore cannot produce a successful receipt.
+
+The baseline itself never changes during normal use. Runtime edits persist until you
+reset or discard that runtime.
+
+## Storage and privacy
+
+Baseline files can still be sensitive after sanitization. Rehearsal stores them under the
+ignored `.rehearsal/` directory with checksums and read-only files. Keep them off shared
+drives, use encrypted disks, retain them only as long as needed, and never commit them.

package/docs/commands.md

@@ -1,35 +1,198 @@
 # CLI commands
 
-All commands run from the consuming project root. State-reporting commands accept
-`--json`; `--verbose` and `--debug` increase safe diagnostics without revealing row
-values or credentials.
-
-| Command                                                      | Mutates local state | Purpose                                                   |
-| ------------------------------------------------------------ | ------------------- | --------------------------------------------------------- |
-| `rehearsal init`                                             | No                  | Preview safe starter configuration.                       |
-| `rehearsal init --write`                                     | Config only         | Create config without overwriting.                        |
-| `rehearsal baseline create --records=<path> --ledger=<path>` | Artifact only       | Activate a baseline from explicit safe local inputs.      |
-| `rehearsal doctor`                                           | No                  | Check dependencies, inputs, and safety barriers.          |
-| `rehearsal explain`                                          | No                  | Print the immutable execution plan.                       |
-| `rehearsal run --dry-run`                                    | No                  | Alias the same plan used by `explain`.                    |
-| `rehearsal candidates`                                       | No                  | Print pending migrations and their exact digest.          |
-| `rehearsal inspect baseline`                                 | No                  | Print data-free artifact provenance.                      |
-| `rehearsal inspect migrations`                               | No                  | Classify each migration.                                  |
-| `rehearsal run --confirm-candidates=<sha256>`                | Yes, local only     | Reset, apply exact candidates, verify, and run app proof. |
-| `rehearsal start`                                            | Runtime only        | Start a verified runtime without resetting its data.      |
-| `rehearsal migrate --confirm-candidates=<sha256>`            | Yes, local only     | Apply the exact suffix without resetting current data.    |
-| `rehearsal verify`                                           | No data mutation    | Verify the current local runtime and receipt.             |
-| `rehearsal status`                                           | No                  | Report runtime, baseline, and candidate state.            |
-| `rehearsal reset`                                            | Yes, local only     | Replace runtime data with the immutable baseline.         |
-| `rehearsal stop`                                             | Runtime only        | Stop this project's local services.                       |
-| `rehearsal discard`                                          | Yes, local only     | Remove only this project's disposable runtime and volume. |
-
-`run` requires the digest from the current candidate set. Any added, removed, reordered,
-or edited migration changes the digest and invalidates the confirmation.
-
-`baseline create` never extracts data. The NDJSON and migration-ledger files must already
-exist inside the project and be safe to retain. Add `--assets=<manifest.json>` to include
-bounded local Storage bytes; every manifest `file` must also remain inside the project.
-
-Automation should use `--json` and inspect both exit status and the versioned envelope.
-Exit-code meanings are documented in the root README. Scripts must not parse human text.
+Run commands from the project directory containing `rehearsal.config.mjs`. The examples
+use `npx`, so a global install is not required.
+
+## Guided mode
+
+```bash
+npx rehearsal
+```
+
+The guide reads the current project state and recommends the next useful action. It stays
+open after each action. Press `Ctrl+Z` at a prompt to exit the entire session.
+
+Use `npx rehearsal guide` for the same screen or add `--plain` to use numbered menus
+without decorative terminal styling. When input or output is not an interactive terminal,
+bare `npx rehearsal` prints help instead of waiting for input.
+
+## Setup and baseline
+
+| Command                                                           | What it does                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------ |
+| `npx rehearsal setup --target=supabase`                           | Preview Supabase setup files.                          |
+| `npx rehearsal setup --target=postgresql`                         | Preview PostgreSQL setup files.                        |
+| Add `--write` to either setup command                             | Create the previewed files without overwriting.        |
+| `npx rehearsal init`                                              | Preview only `rehearsal.config.mjs`.                   |
+| `npx rehearsal init --write`                                      | Create only `rehearsal.config.mjs`.                    |
+| `npx rehearsal baseline prepare --records=<path> --ledger=<path>` | Preview a sanitization-policy draft.                   |
+| Add `--write` to `baseline prepare`                               | Write the draft for human review.                      |
+| `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 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
+
+For a reviewed Google identity, use this sequence:
+
+1. Run a successful rehearsal, then start the persistent app:
+
+   ```bash
+   npx rehearsal open
+   ```
+
+2. Open the printed local URL and complete the normal Google sign-in. Press `Ctrl+C`
+   after the callback returns. This closes only the app; the databases and Storage stay
+   running with their current data.
+
+3. Preview and confirm the reviewed association:
+
+```bash
+npx rehearsal identity plan --identity=approved-owner
+npx rehearsal identity claim --identity=approved-owner \
+  --confirm-identity=<sha256>
+```
+
+4. Run `npx rehearsal open` again. Sign out and sign in again so the browser receives a
+   fresh session, then check the copied account. Rehearsal does not bypass application
+   role checks, account blocks, RLS, or MFA.
+
+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
+
+| Command                            | What it does                                          |
+| ---------------------------------- | ----------------------------------------------------- |
+| `npx rehearsal doctor`             | Check dependencies, inputs, and safety rules.         |
+| `npx rehearsal support`            | Print a privacy-safe report for a support request.    |
+| `npx rehearsal explain`            | Show the exact plan without changing anything.        |
+| `npx rehearsal run --dry-run`      | Show the same non-mutating plan.                      |
+| `npx rehearsal candidates`         | List pending migrations and their approval digest.    |
+| `npx rehearsal inspect baseline`   | Show baseline metadata without row values.            |
+| `npx rehearsal inspect migrations` | Classify every historical and candidate migration.    |
+| `npx rehearsal status`             | Report baseline, candidates, and local runtime state. |
+
+State-reporting commands accept `--json` for scripts. Scripts should use the JSON fields
+and process exit code, not parse human-facing text.
+
+## Run and manage the local sandbox
+
+| Command                                               | What it does                                                        |
+| ----------------------------------------------------- | ------------------------------------------------------------------- |
+| `npx rehearsal run --confirm-candidates=<sha256>`     | Reset, apply exact candidates, launch the app, and run its proofs.  |
+| `npx rehearsal open`                                  | Start, verify, and keep the configured application open.            |
+| `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.                             |
+| `npx rehearsal reset`                                 | Discard runtime edits and restore the baseline.                     |
+| `npx rehearsal stop`                                  | Stop the runtime but keep its local state.                          |
+| `npx rehearsal discard`                               | Remove this project's disposable runtime and volume.                |
+| `npx rehearsal cleanup`                               | Preview conservative cleanup without removing anything.             |
+
+In a terminal, the guide displays candidate filenames and asks for confirmation. In a
+script, copy the digest from `candidates` into `--confirm-candidates`. Adding, removing,
+reordering, or editing a migration changes that digest.
+
+`open` does not reset the runtime or apply migrations. It starts and verifies every
+configured database target, runs dependent preparation commands, and launches
+`application.startCommand` with the declared local environment mappings. It waits for
+`application.readiness`, then stays attached until `Ctrl+C` or `Ctrl+Z`. On exit it stops
+only the application process group it launched. Use `stop` separately when you also want
+to stop the databases; a later `open` preserves their database and Storage changes.
+
+## Clean up disk space
+
+Start with a preview:
+
+```bash
+npx rehearsal cleanup
+```
+
+By default, cleanup selects only old baseline generations beyond the retention setting
+in `rehearsal.config.mjs`. Add options to broaden the preview:
+
+| Command option      | Additional resources considered                                        |
+| ------------------- | ---------------------------------------------------------------------- |
+| `--include-runtime` | This project's disposable runtime and its database volumes.            |
+| `--include-images`  | Older unused Supabase images; the newest image for each service stays. |
+| `--write`           | Apply the exact freshly verified preview.                              |
+| `--confirm-cleanup` | Full cleanup digest printed by the preview; required with `--write`.   |
+
+Image cleanup never removes an image used by any running or stopped container and never
+runs a global Docker prune. Images may be shared by projects and can be downloaded again,
+so they remain excluded unless you explicitly add `--include-images`. Database volumes
+belonging to other projects are never included. This follows
+[Docker's conservative pruning guidance](https://docs.docker.com/engine/manage-resources/pruning/).
+
+## 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 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.