@rehearsal-db/core 0.1.0-beta.4 → 0.1.0-beta.6

package/docs/baselines.md

@@ -1,33 +1,92 @@
 # 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
+Use synthetic or reviewed sanitized values. A `.json` array is not NDJSON and will be
+rejected.
 
-`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.
+### Migration ledger
 
-## Persistence model
+The ledger is a JSON array in migration order:
 
-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.
+```json
+[
+  {
+    "version": "20260101000000",
+    "name": "create_widgets",
+    "statements": [
+      "create table public.widgets (id bigint primary key, name text not null)"
+    ]
+  }
+]
+```
 
-Treat baseline files as sensitive even after sanitization: owner-only permissions,
-ignored paths, encrypted disks, bounded retention, and explicit deletion are prudent.
+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. It never extracts data.
+
+## 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,66 +1,78 @@
 # 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` or `rehearsal guide`                             | No by default       | Open the guided, state-aware interactive home screen.     |
-| `rehearsal setup`                                            | No                  | Preview safe config, local runtime, and ignore files.     |
-| `rehearsal setup --write`                                    | Project files       | Create the previewed first-run scaffolding.               |
-| `rehearsal init`                                             | No                  | Preview safe starter configuration.                       |
-| `rehearsal init --write`                                     | Config only         | Create config without overwriting.                        |
-| `rehearsal baseline prepare --records= --ledger=`            | No                  | Preview a fail-closed policy draft from local shape.      |
-| `rehearsal baseline prepare --records= --ledger= --write`    | Policy only         | Write the draft without exposing row values.              |
-| `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. |
-
-In an interactive terminal, `run` and `migrate` display the candidate files and ask for
-confirmation before touching the runtime. In automation, they require the digest from
-the current candidate set. Any added, removed, reordered, or edited migration changes
-the digest and invalidates either form of 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.
-The guided home screen can ask for these paths so they do not need to be supplied as
-flags.
-
-The guide is a persistent session: after setup, policy review, baseline creation, or a
-runtime action it re-reads project state and offers the next relevant action. Generated
-policy drafts can be completed interactively without editing JSON. Each column still
-requires explicit action, generated, identity, and foreign-key decisions; the guide does
-not silently infer them.
-
-`baseline prepare` reads only table and column names from the NDJSON records; row values
-are never included in its result. Its generated policy deliberately marks every column
-decision `REVIEW REQUIRED` and cannot be activated until a human completes the metadata
-and removes the `draft` marker. Rehearsal binds the reviewed policy checksum to the
-baseline and rejects later policy changes during planning and restore.
-
-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.
-When standard input or output is not an interactive terminal, bare `rehearsal` prints
-help instead of prompting. Use `--plain` to disable decorative terminal styling.
-`NO_COLOR` also selects the plain numbered interface. Both interactive modes preserve
-the same safety decisions and cancellation behavior.
-
-`setup` chooses an available local port block and generates a conservative Supabase
-configuration with hosted access and optional networked services disabled. It does not
-overwrite an existing Rehearsal config, dedicated Supabase config, or concurrently
-changed `.gitignore`. After writing, it includes a Doctor readiness summary. `init`
-remains available for config-only/manual onboarding.
+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 commands never extract data or connect to another database.
+
+## 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 database
+
+| Command                                               | What it does                                                        |
+| ----------------------------------------------------- | ------------------------------------------------------------------- |
+| `npx rehearsal run --confirm-candidates=<sha256>`     | Reset, apply the exact candidates, verify, and run the app proof.   |
+| `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.                |
+
+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.
+
+## 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.                                         |
+
+Run `npx rehearsal --help` to print the command list available in your installed version.

package/docs/configuration.md

@@ -1,9 +1,14 @@
 # Configuration reference
 
-`rehearsal.config.mjs` is executable configuration with a strict versioned schema. The
-initializer uses an explicit ESM extension so the same generated file works in CommonJS
-and ESM projects.
-Unknown fields and unknown schema versions are errors, not warnings.
+Most users should let the guide create this file:
+
+```bash
+npx rehearsal
+```
+
+Use this page when reviewing or changing the generated `rehearsal.config.mjs`. The schema
+is strict: misspelled fields, unknown fields, and unsupported versions are errors. The
+`.mjs` extension works in both CommonJS and ESM projects.
 
 ```ts
 import { defineRehearsalConfig } from "@rehearsal-db/core";
@@ -26,6 +31,7 @@ export default defineRehearsalConfig({
     proofCommand: "npm run test:rehearsal",
   },
   runtime: {
+    target: "supabase",
     applicationUrl: "http://localhost:5175",
     projectId: "example-app-rehearsal",
     apiPort: 58321,
@@ -42,6 +48,9 @@ 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.
+
 ## Supabase service environment
 
 Some local identity providers need a client ID and secret. Configure both fields or
@@ -68,6 +77,40 @@ Use unique, non-privileged ports that do not overlap. `projectId` accepts lowerc
 letters, numbers, and hyphens. It labels the local Docker resources so cleanup targets
 only this project.
 
+## Database runtime
+
+`runtime.target` selects the isolated database driver. It is optional in existing
+configurations and currently defaults to `"supabase"`, so upgrading does not change an
+existing project's behavior. Unknown targets are rejected before any runtime action.
+
+For ordinary PostgreSQL, use `postgresql` instead of `supabase`:
+
+```ts
+postgresql: {
+  migrationDirectory: "database/migrations",
+  runtimeWorkdir: ".rehearsal/runtime",
+  image: "postgres:17-alpine",
+  database: "postgres",
+  user: "postgres",
+},
+runtime: {
+  target: "postgresql",
+  applicationUrl: "http://localhost:5175",
+  projectId: "example-app-rehearsal",
+  databasePort: 58322,
+},
+```
+
+The image must be an official versioned Alpine PostgreSQL image and must already exist
+locally. Rehearsal runs it with `--pull=never`, publishes it only on `127.0.0.1`, and
+creates a fresh random runtime password in owner-readable ignored files. It manages only
+the exactly named container and volume carrying the matching project label.
+Plain PostgreSQL does not restore Supabase Storage assets or synthesize Supabase Auth
+users.
+
+Project-owned runtime adapters remain the place for application-specific setup and
+checks; they do not replace the database driver.
+
 ## Application proof
 
 `proofCommand` is mandatory and project-owned. It should test restored relationships,