@rehearsal-db/core 0.1.0-beta.1

package/docs/commands.md

@@ -0,0 +1,35 @@
+# 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.

package/docs/configuration.md

@@ -0,0 +1,98 @@
+# Configuration reference
+
+`rehearsal.config.ts` is executable configuration with a strict versioned schema.
+Unknown fields and unknown schema versions are errors, not warnings.
+
+```ts
+import { defineRehearsalConfig } from "@rehearsal-db/core";
+
+export default defineRehearsalConfig({
+  schemaVersion: 1,
+  project: { name: "example-app" },
+  supabase: {
+    workdir: ".",
+    migrationDirectory: "supabase/migrations",
+    rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
+    runtimeWorkdir: ".rehearsal/runtime",
+  },
+  baseline: {
+    artifactDirectory: ".rehearsal",
+    sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
+  },
+  application: {
+    startCommand: "npm run dev:rehearsal",
+    proofCommand: "npm run test:rehearsal",
+  },
+  runtime: {
+    applicationUrl: "http://localhost:5175",
+    projectId: "example-app-rehearsal",
+    apiPort: 58321,
+    databasePort: 58322,
+    studioPort: 58323,
+  },
+  safety: { hostedAccess: "disabled", outboundNetwork: "deny" },
+});
+```
+
+## Paths
+
+All paths resolve inside the consuming project. The artifact directory must be named
+`.rehearsal`; this is an intentional deletion guard. `runtimeWorkdir` must be its
+`runtime` child, and the generated application environment file must remain inside it.
+
+## Supabase service environment
+
+Some local identity providers need a client ID and secret. Configure both fields or
+neither:
+
+```ts
+serviceEnvironmentFile: ".env.rehearsal-service.local",
+serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+```
+
+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.
+
+## Safety fields
+
+Version 1 accepts loopback hosts only. `hostedAccess` can only be `disabled`, and
+`outboundNetwork` can only be `deny`. Ambient hosted Supabase variables are quarantined
+from child processes. There is no force flag to weaken these rules.
+
+## Ports and project identity
+
+Use unique, non-privileged ports that do not overlap. `projectId` accepts lowercase
+letters, numbers, and hyphens. It labels the local Docker resources so cleanup targets
+only this project.
+
+## Application proof
+
+`proofCommand` is mandatory and project-owned. It should test restored relationships,
+authentication shape, critical reads, and candidate-migration behavior. A command that
+only checks whether the home page returns 200 is usually too weak.
+
+## Runtime adapters
+
+Most projects do not need an adapter. Use one only for schema-specific restore setup,
+synthetic local identities, explicit generated environment variables, or post-restore
+invariants. See [adapters](adapters.md).
+
+## Advanced library entry points
+
+The CLI is the primary interface. Baseline builders and project-owned refresh tooling
+may use these explicit subpaths:
+
+- `@rehearsal-db/core/baseline`
+- `@rehearsal-db/core/migrations`
+- `@rehearsal-db/core/schema`
+- `@rehearsal-db/core/diagnostics`
+- `@rehearsal-db/core/process-environment`
+- `@rehearsal-db/core/service-environment`
+
+These advanced entry points are ESM JavaScript APIs in the first beta. The root
+configuration and sanitization API has TypeScript declarations; the advanced subpaths do
+not yet promise a typed surface.
+
+Undocumented files under `scripts/` are package internals and are not compatibility
+contracts.

package/docs/getting-started.md

@@ -0,0 +1,247 @@
+# Getting started
+
+This guide creates a safe local Rehearsal project from synthetic data. It does not
+connect to production, request hosted credentials, or require an existing baseline.
+
+## Prerequisites
+
+- Node.js 24
+- npm
+- Supabase CLI 2.117.0 (the version proved by package CI)
+- Docker Desktop, Colima, or another Docker-compatible engine
+- a Supabase project with timestamped SQL migrations
+
+Confirm the tools first:
+
+```bash
+node --version
+npm --version
+supabase --version
+docker info
+```
+
+If you want to see the complete lifecycle before touching your own project, clone the
+Rehearsal repository and run:
+
+```bash
+npm ci --ignore-scripts
+npm run test:fixture
+```
+
+That proof installs the packed package into a disposable fictional project, restores a
+row and Storage object, applies a valid migration, rejects invalid SQL, and removes only
+its labeled local runtime. It does not need a hosted Supabase project or credentials.
+
+## 1. Install and initialize
+
+```bash
+npm install --save-dev @rehearsal-db/core
+npx rehearsal init
+```
+
+`init` is a preview. Read the generated configuration, then explicitly write it:
+
+```bash
+npx rehearsal init --write
+```
+
+Rehearsal never overwrites an existing configuration.
+
+The generated configuration is intentionally incomplete until you review its ports,
+project ID, application commands, and project-owned input paths. Do not run `doctor`
+until the next section's files exist.
+
+## 2. Add the project-owned inputs
+
+Create the paths named by `rehearsal.config.ts`:
+
+- a dedicated local Supabase `config.toml`;
+- a sanitization policy describing every exported field;
+- an active baseline below `.rehearsal/`;
+- an application proof command that exits nonzero when the restored app is wrong.
+
+For the generated default paths:
+
+```bash
+mkdir -p infrastructure/rehearsal/supabase infrastructure/rehearsal rehearsal
+cp supabase/config.toml infrastructure/rehearsal/supabase/config.toml
+```
+
+Edit the copied Supabase config. Give it the same unique `project_id`, API port, database
+port, and Studio port used by `rehearsal.config.ts`. Disable services your proof does
+not need. This must remain an unlinked local config; never run `supabase link` from it.
+
+Also replace the generated `application.startCommand`, `application.proofCommand`, and
+`verification.commands` with real commands from your project. The proof should check a
+restored relationship and the candidate schema—not merely that `/` returns 200.
+
+Start with synthetic rows shaped like your schema. Do not start onboarding with
+production data. The following SQL, policy, row, and ledger form one matched example;
+do not mix them with differently shaped snippets.
+
+Historical migration `supabase/migrations/20260101000000_create_widgets.sql`:
+
+```sql
+create table public.widgets (
+  id bigint generated by default as identity primary key,
+  name text not null,
+  created_at timestamptz not null default now()
+);
+
+insert into storage.buckets (id, name, public)
+values ('fixture-assets', 'fixture-assets', false);
+```
+
+Sanitization policy `infrastructure/rehearsal/sanitization-policy.json`:
+
+```json
+{
+  "policyVersion": 1,
+  "migrationCutoff": "20260101000000",
+  "tables": [
+    {
+      "name": "widgets",
+      "group": "synthetic",
+      "sourceRows": "STREAM AND SANITIZE",
+      "columns": [
+        {
+          "name": "id",
+          "action": "KEEP EXACTLY",
+          "generated": "NEVER",
+          "identity": "YES",
+          "foreignKey": null
+        },
+        {
+          "name": "name",
+          "action": "REPLACE WITH SYNTHETIC",
+          "generated": "NEVER",
+          "identity": "NO",
+          "foreignKey": null
+        },
+        {
+          "name": "created_at",
+          "action": "DERIVE",
+          "generated": "NEVER",
+          "identity": "NO",
+          "foreignKey": null
+        }
+      ]
+    }
+  ]
+}
+```
+
+Safe row `rehearsal/synthetic-data.ndjson` (one JSON object per physical line):
+
+```json
+{
+  "table": "widgets",
+  "row": {
+    "id": 1,
+    "name": "Synthetic Widget",
+    "created_at": "2026-01-01T00:00:00.000Z"
+  }
+}
+```
+
+Migration ledger `rehearsal/migration-ledger.json`:
+
+```json
+[
+  {
+    "version": "20260101000000",
+    "name": "create_widgets",
+    "statements": [
+      "create table public.widgets (\n\tid bigint generated by default as identity primary key,\n\tname text not null,\n\tcreated_at timestamptz not null default now()\n)",
+      "insert into storage.buckets (id, name, public)\nvalues ('fixture-assets', 'fixture-assets', false)"
+    ]
+  }
+]
+```
+
+The ledger is evidence, not a second migration language. Its version, name, order, and
+statements must exactly represent the historical migration bytes in the baseline. SQL
+that is merely equivalent is rejected. For a production-shaped baseline, generate this
+ledger through the project's reviewed source/export tooling; do not reconstruct years of
+history by hand.
+
+Then activate the safe input:
+
+```bash
+npx rehearsal baseline create \
+  --records=rehearsal/synthetic-data.ndjson \
+  --ledger=rehearsal/migration-ledger.json
+```
+
+The independent fixture in this repository is the executable reference example.
+
+Expected result:
+
+```text
+Activated synthetic baseline ...: 1 rows across 1 tables; 1 migrations through 20260101000000.
+```
+
+## 3. Check readiness
+
+```bash
+npx rehearsal doctor
+```
+
+Do not continue until it ends with `READY`. Doctor checks the local-only boundary,
+dependencies, artifact integrity, migration lineage, ports, and project commands.
+
+If it reports `NOT READY`, fix each named prerequisite and rerun it. Do not bypass a
+check or copy a hosted connection string into the generated runtime environment.
+
+## 4. Review pending work
+
+```bash
+npx rehearsal explain
+npx rehearsal candidates
+npx rehearsal inspect baseline
+npx rehearsal inspect migrations
+```
+
+The plan prints an exact candidate digest. It does not start services or change data.
+
+## 5. Run the rehearsal
+
+```bash
+npx rehearsal run --confirm-candidates=<sha256>
+```
+
+Rehearsal restores the immutable baseline, applies only the confirmed migration suffix,
+verifies the runtime, and runs the project-owned application proof. The resulting local
+database is writable, so you can test real application changes without mutating the
+baseline.
+
+## 6. Work, verify, and reset
+
+```bash
+npx rehearsal status
+npx rehearsal start
+npx rehearsal verify
+npx rehearsal reset
+npx rehearsal stop
+```
+
+Changes persist in the disposable runtime until `reset` or runtime removal. `start`
+resumes that runtime without resetting it. `reset` restores the exact baseline. `stop`
+stops only this project's runtime.
+
+## Next steps
+
+- Follow [the full tutorial](tutorial.md).
+- Read [the security model](security-model.md) before designing a production export.
+- Define an exhaustive [sanitization policy](sanitization.md).
+- Learn the [baseline lifecycle](baselines.md).
+
+## Generated files
+
+- `rehearsal.config.ts` is written only by `init --write`.
+- `.rehearsal/generations/<id>/` contains one immutable baseline generation.
+- `.rehearsal/current` selects the active generation atomically.
+- `.rehearsal/runtime/` contains the disposable local Supabase project and receipts.
+- `.rehearsal/runtime.env` contains generated loopback-only application credentials.
+
+Ignore all of `.rehearsal/`. Do not commit it even when its inputs were synthetic.

package/docs/glossary.md

@@ -0,0 +1,33 @@
+# Glossary and architecture
+
+**Baseline** — immutable sanitized starting artifact.
+
+**Candidate migration** — ordered migration suffix not represented by the baseline.
+
+**Candidate digest** — checksum binding the exact candidate filenames and bytes.
+
+**Project-owned** — application-specific policy or code that remains outside the package.
+
+**Represented migration** — historical migration whose exact bytes are bound into the
+baseline.
+
+**Runtime** — disposable, writable local Supabase/PostgreSQL environment.
+
+**Sanitization policy** — exhaustive project decision for every exported field.
+
+**Verified receipt** — local evidence that the exact runtime and candidate suffix passed.
+
+```mermaid
+flowchart LR
+  A[Project-owned approved source] --> B[Project-owned sanitization]
+  B --> C[Immutable baseline]
+  D[Project migrations] --> E[Digest planner]
+  C --> F[Disposable local Supabase]
+  E --> F
+  F --> G[Project application proof]
+  G --> H[Verified local receipt]
+```
+
+The reusable package owns the path from a completed baseline plus migration directory to
+a verified local runtime. The consuming project owns everything that decides which source
+data is allowed, how it is transformed, and what application behavior counts as correct.

package/docs/production-source.md

@@ -0,0 +1,33 @@
+# Designing a production source boundary
+
+The npm package does not connect to production and does not ship an extraction command.
+That separation is a security boundary: each project must authorize, sanitize, and
+audit its own source.
+
+## Recommended flow
+
+1. Define versioned read-only export views containing only approved columns.
+2. Grant a temporary role `SELECT` on those views and nothing else.
+3. Use a short-lived credential outside shell history and source control.
+4. Stream records through the project-owned sanitization policy.
+5. Write into a private building generation below `.rehearsal`.
+6. Verify counts, checksums, policy coverage, migration history, and secret canaries.
+7. Atomically activate the completed generation.
+8. Revoke and verify removal of the temporary credential.
+9. Delete raw intermediate files and retain only the sanitized artifact.
+
+Use server-side cursors or another bounded streaming mechanism. A full in-memory dump
+is not acceptable for large sources. Extraction logs should contain counts and hashes,
+never row bodies.
+
+## What not to do
+
+- Do not point `rehearsal.config.ts` at a hosted URL.
+- Do not put a production connection string in `.rehearsal/runtime.env`.
+- Do not grant table-wide access merely because a view is inconvenient.
+- Do not commit sanitized baselines; sanitized data is still data.
+- Do not let the reusable package infer which fields are safe.
+- Do not leave the export role provisioned after refresh.
+
+The local execution engine remains useful with synthetic or manually approved baselines.
+Production-shaped onboarding is a separate project security exercise.

package/docs/releasing.md

@@ -0,0 +1,79 @@
+# Release process
+
+Rehearsal publishes from a reviewed GitHub release through the protected `npm`
+environment. The workflow builds and hashes the candidate before the environment
+approval gate, then publishes those exact bytes with npm provenance. A local working
+tree is never the release source.
+
+The initial publishable `0.1.0-beta.1` release branch is the first change allowed to set
+`"private": false`. Publication still requires the exact protected-main tag, prerelease
+flag, artifact checks, and protected `npm` environment gate described below.
+
+`0.1.0-beta.0` was prepared under the unavailable `@rehearsal` npm scope and was never
+published. `0.1.0-beta.1` supersedes that candidate under `@rehearsal-db/core` without
+rewriting the earlier Git tag or GitHub prerelease.
+
+## One-time first-package bootstrap
+
+npm trusted publishing and staged publishing are package-level settings, so they cannot
+be configured until `@rehearsal-db/core` exists in the registry. The first public version has
+a deliberately narrower bootstrap path:
+
+1. The npm owner enables 2FA and creates or confirms the public `@rehearsal-db` organization
+   scope. Do not send a password, OTP, recovery code, or access token to another person.
+2. After the reviewed release change reaches protected `main`, the owner creates the
+   exact `v0.1.0-beta.1` GitHub release and marks it as a prerelease. The prepare job runs without npm credentials,
+   packs the tag, and uploads its versioned tarball plus SHA-1 and SHA-256 metadata. The
+   publish job waits at the protected environment and cannot run yet.
+3. The owner downloads or inspects that prepared artifact, confirms its version and
+   checksum, and explicitly authorizes those exact bytes.
+4. Only then, the owner creates a short-lived granular npm token with read/write access
+   limited to the `@rehearsal-db` scope and **Bypass 2FA** enabled. npm requires that bypass
+   for a non-interactive first publish; the environment approval remains the human
+   release gate. Store the token only as the `NPM_TOKEN` secret in the protected GitHub
+   `npm` environment.
+5. The owner approves the waiting `npm` deployment. GitHub Actions publishes the exact
+   uploaded tarball with provenance. The workflow
+   refuses to use the bootstrap secret for any version other than `0.1.0-beta.1`.
+6. Immediately after the registry verification passes, the owner deletes the GitHub
+   environment secret and revokes the temporary npm token.
+7. From the new package's npm settings, configure the trusted GitHub Actions publisher
+   for repository `Ddupasquier/rehearsal-db`, workflow `publish.yml`, and environment
+   `npm`. Allow direct `npm publish` for this workflow because the protected GitHub
+   environment supplies the human gate. A later switch to npm staged publication must
+   change and prove the workflow before narrowing the trusted publisher permission.
+8. Set package publishing access to require 2FA and disallow traditional tokens.
+
+This bootstrap token is a one-release compromise imposed by npm's package-creation
+boundary. It is never committed, printed, copied into a ticket, or retained for later
+versions.
+
+## Every release candidate
+
+1. Start from protected `main` on a dedicated ticketed release branch.
+2. Verify the exact version, changelog, compatibility notes, and packed file list.
+3. Run unit and contract tests, formatting, package-content and secret audits,
+   dependency audit, clean tarball installation, and the installed Docker fixture.
+4. Have a developer unfamiliar with the implementing project follow the clean-project
+   onboarding. Correct and retest the first confusing, missing, or wrong instruction.
+5. Change `private` to `false` only in the reviewed release change.
+6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
+   executable, and zero-runtime-dependency result.
+7. Obtain explicit publication authorization for that exact version and artifact.
+8. Merge the approved release commit through protected `main` and create the exact
+   `v<package-version>` tag and GitHub release.
+9. Review and approve the protected `npm` deployment only after its prepare job matches
+   the approved version and checksum.
+10. Verify public visibility, ownership, provenance, registry SHA-1, README rendering,
+    exact-version clean installation, CLI execution, signatures, and the unrelated
+    installed Docker fixture.
+11. Replace consuming projects' temporary Git/archive references only on their own
+    protected integration branches and rerun their complete verification.
+
+The workflow publishes prereleases under the `beta` dist-tag and refuses a stable
+version. A stable tag requires a later contract, compatibility, and release decision.
+
+Creating the repository, passing CI, extracting the engine, merging a release branch,
+or creating a tag does not authorize npm publication. Publication requires explicit
+authorization for the exact packed artifact, and the protected GitHub environment
+supplies the final human gate.

package/docs/sanitization.md

@@ -0,0 +1,69 @@
+# Sanitization policy
+
+Rehearsal deliberately does not decide what your application may copy. The consuming
+project owns an exhaustive, reviewable policy for its export surface.
+
+Every exported field should receive one action:
+
+- `KEEP`: retain an explicitly non-sensitive value needed for realistic behavior;
+- `PSEUDONYMIZE`: replace identity while preserving stable joins;
+- `REPLACE`: substitute a safe value of compatible shape;
+- `EXCLUDE`: omit data that the rehearsal does not need;
+- `DERIVE`: create a bounded safe value from approved inputs.
+
+Fail if a new column is unclassified. Do not default unknown fields to `KEEP`.
+
+The package exports `validateSanitizationCoverage` and
+`applySanitizationAction` as generic primitives:
+
+```ts
+import {
+  applySanitizationAction,
+  validateSanitizationCoverage,
+} from "@rehearsal-db/core";
+
+validateSanitizationCoverage({ policy, schemaTables });
+
+const safeValue = applySanitizationAction({
+  action: column.action,
+  value: sourceValue,
+  pseudonymize: projectPseudonymizer,
+  replace: projectReplacement,
+  derive: projectDerivation,
+  context: { table: table.name, column: column.name },
+});
+```
+
+Coverage validation requires a one-to-one table and column match: missing and unknown
+entries both fail. The package supplies the operation contract; the project supplies
+the schema inventory, keys, replacements, and derivation logic.
+
+## Stable identity
+
+Use keyed, deterministic pseudonyms when relationships must survive across tables.
+Keep the key outside source control and outside the final baseline. The same source ID
+should map consistently within a generation, while the original value cannot be
+recovered from the artifact.
+
+## High-risk fields
+
+Exclude or replace secrets, password material, refresh tokens, session tokens, payment
+data, private messages, precise location, raw uploads, provider credentials, and
+unbounded free text unless a reviewed test requirement proves they are necessary.
+
+Images and Storage objects need the same classification as database columns. A public
+product image may be retained under its license; a private upload generally may not.
+
+## Validation
+
+Before activation, verify:
+
+1. every exported column is classified;
+2. prohibited values and secret canaries are absent;
+3. referential relationships required by the app remain valid;
+4. row counts match the approved export manifest;
+5. the policy digest is recorded in the baseline manifest;
+6. raw staging files and temporary credentials are removed.
+
+Completeness is not correctness. Human review of the policy and export boundary remains
+mandatory before any real source is introduced.

package/docs/security-model.md

@@ -0,0 +1,40 @@
+# Security model
+
+Rehearsal assumes a mistake is more likely than an attacker. Its design makes ordinary
+misconfiguration fail closed before a state-changing operation.
+
+## Trust boundaries
+
+The engine trusts the reviewed package code, strict project configuration, a verified
+active baseline, exact migration bytes, and explicitly project-owned proof code. It does
+not trust ambient environment variables, hosted project state, unknown config fields,
+changed migration history, incomplete artifacts, or an unverified runtime.
+
+## Independent barriers
+
+- loopback-only application and service URLs;
+- a dedicated unlinked Supabase workdir and project ID;
+- exact non-overlapping local ports;
+- a clean child-process environment that omits hosted credentials;
+- immutable baseline files and checksums;
+- exact migration-prefix and candidate digests;
+- local runtime labels used for bounded stop/removal;
+- successful receipts written only after verification.
+
+No single environment variable or config edit should redirect the tool to production.
+Version 1 provides no hosted execution mode.
+
+## Identity providers
+
+An optional external identity handshake is distinct from database access. Only declared
+credential names are read from an ignored owner-only file, and the callback must target
+local Auth. The local account may represent a sanitized production identity, but its
+session and writes remain local.
+
+## Remaining responsibilities
+
+Rehearsal cannot prove that retained data is lawful, a sanitization rule is ethically
+appropriate, a migration has the intended business meaning, or a project adapter is
+safe. Repository owners must review those decisions and protect artifacts.
+
+Report vulnerabilities using the private process in the root security policy.