@rehearsal-db/core 0.1.0-beta.1

package/BENCHMARKS.md

@@ -0,0 +1,61 @@
+# Rehearsal benchmark baseline
+
+These measurements are regression signals, not performance guarantees. Compare future
+runs on equivalent hardware and investigate material regressions before release.
+
+Measured 2026-09-12 on macOS arm64, Apple M1, Node.js 24.18.0, Supabase CLI 2.117.0,
+Docker 29.5.2, and local warm container images.
+
+## Large production-shaped baseline
+
+The final pre-extraction corpus contained 1,139,884 sanitized rows across 126 tables and 251
+represented migrations with zero candidates. These historical measurements establish a
+starting regression signal; they are not bundled test data or a supported performance
+guarantee.
+
+| Phase                                      | Time     |
+| ------------------------------------------ | -------- |
+| Baseline checksum verification             | 682 ms   |
+| Migration inventory and candidate planning | 1,012 ms |
+| Database reset, restore, and verification  | 83.70 s  |
+| Public CLI run plus project app proof      | 105.56 s |
+
+The complete run includes local Supabase stop/start overhead, replaying the historical
+schema, streaming the baseline, the project-specific synthetic developer overlay, exact
+row/FK verification, candidate reconciliation, and final migration-ledger verification.
+
+## Independent fixture
+
+Measured again on 2026-09-14 with the same local macOS arm64 toolchain after the final
+documentation and package-contract sweep.
+
+Corpus: one synthetic row, one table, one represented migration, one valid candidate,
+and one deliberately invalid candidate.
+
+| Phase                                         | Time    |
+| --------------------------------------------- | ------- |
+| Baseline creation and plan                    | 81 ms   |
+| Installed-package valid CLI run and app proof | 42.70 s |
+| Reset, stop, restart, and discard lifecycle   | 63.95 s |
+| Installed-package invalid refusal and cleanup | 35.09 s |
+
+Most fixture time is local Supabase container lifecycle overhead. The fixture installs
+the exact packed release candidate before both executions. The failure timing includes
+rebuilding the baseline runtime, applying the valid prefix candidate, refusing the
+invalid SQL candidate, and removing the untrusted runtime.
+
+## Linux portability proof
+
+Measured 2026-09-12 using Node.js 24.21.0 in Ubuntu Bookworm arm64 against the local
+Colima Docker host, Supabase CLI 2.117.0, and the exact installed prospective tarball.
+The valid migration and application proof passed in 40.49 seconds. The invalid migration
+was refused and its exact project-labelled runtime was removed in 39.39 seconds. This
+run exposed and fixed the fresh-runtime cleanup path and proves Linux arm64 behavior;
+the same proof remains required in GitHub Actions before public release.
+
+## Regression policy
+
+Record a new equivalent sample before a beta release or after changing baseline format,
+streaming, restore, migration application, verification, or local-runtime lifecycle.
+Investigate a repeatable increase greater than 25% in a phase. Do not weaken checks to
+recover time; optimize only after identifying the measured bottleneck.

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable Rehearsal package changes will be documented here. The format follows Keep
+a Changelog, and versions will follow Semantic Versioning after the package exists.
+
+## Unreleased
+
+## [0.1.0-beta.1] - 2026-09-14
+
+### Changed
+
+- Moved the unpublished beta package from the unavailable `@rehearsal` organization to
+  the project-owned `@rehearsal-db/core` package name.
+- Limited the one-time first-package credential to `0.1.0-beta.1`; `0.1.0-beta.0`
+  remains an unpublished, superseded GitHub release record.
+
+## [0.1.0-beta.0] - 2026-09-14
+
+### Added
+
+- Versioned strict configuration and safe initializer contract.
+- Doctor, immutable explain/dry-run plan, baseline inspection, and migration inspection.
+- Verified run, start, migrate, reset, status, stop, discard, and runtime verification
+  commands with exact candidate confirmation.
+- Versioned human/machine result model, stable exit categories, and recursive redaction.
+- Independent synthetic Supabase fixture with valid and deliberately invalid migrations.
+- Deny-by-default sanitization coverage validation and generic KEEP, PSEUDONYMIZE,
+  REPLACE, EXCLUDE, and DERIVE operation primitives.
+- Public baseline, migration, schema, diagnostic, process-environment, and local-service
+  library entry points for project-owned tooling.
+- Approachable quick start, tutorial, configuration, security, sanitization, source,
+  baseline, adapter, command, troubleshooting, release, support, and contribution guides.
+- Protected verification CI, dependency updates, issue templates, package auditing, and
+  dormant tokenless trusted-publishing configuration.
+- Two-stage release preparation that hashes and uploads the exact npm tarball before a
+  protected human approval gate, then verifies the same registry bytes and executable.
+- A copyable synthetic onboarding path with matched migration, policy, data, and ledger
+  examples plus explicit expected output and recovery guidance.
+- A direct comparison with backups, staging, seed data, database branches, and
+  migration-only tools, plus explicit beta support, typing, cost, and storage boundaries.
+- Standalone repository language that removes source-project history, activates the
+  security and compatibility policies, and matches the repository's available support
+  channels.
+- GitHub Actions upgraded to their Node.js 24 runtime generations before publication.
+
+### Security
+
+- Version 1 permits loopback targets only and cannot enable hosted access or outbound
+  networking.
+- Child processes use allowlisted environments rather than ambient hosted credentials.
+- Package contents are scanned for runtime artifacts, source data, private application
+  identifiers, credential formats, and hosted connection strings.
+- The one-time first-package credential is limited to the first publishable beta; future
+  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.1...HEAD
+[0.1.0-beta.1]: https://github.com/Ddupasquier/rehearsal-db/releases/tag/v0.1.0-beta.1
+[0.1.0-beta.0]: https://github.com/Ddupasquier/rehearsal-db/releases/tag/v0.1.0-beta.0

package/COMPATIBILITY.md

@@ -0,0 +1,22 @@
+# Rehearsal compatibility policy
+
+Rehearsal begins at `0.x`. Minor releases may contain breaking changes, but every
+intentional break must be called out in the changelog with a migration path. Patch
+releases must remain backward compatible within their minor line.
+
+The following are compatibility contracts for published 0.x releases:
+
+- configuration property names, types, defaults, validation, and schema version;
+- baseline format and checksum meaning;
+- ordered migration digest semantics and classifications;
+- CLI command names, flags, state-changing behavior, and exit codes;
+- versioned JSON result and error envelopes;
+- the meaning and ordering of verification gates.
+
+A change to any of those requires either a compatible extension or a deliberate version
+transition. Rehearsal must never silently reinterpret an old config, baseline, digest,
+or successful verification receipt.
+
+The first stable `1.0.0` requires external beta evidence, a support policy, and a settled
+public API. Supporting additional database families, package managers, or operating
+systems is not implied by the 0.x contract.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rehearsal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# Rehearsal
+
+Rehearsal tests pending Supabase migrations against a verified, sanitized,
+production-shaped baseline in a disposable local environment. It is designed for the
+historical edge cases that synthetic seed data rarely represents.
+
+Version 0.1 targets Supabase CLI projects running PostgreSQL locally. It does not yet
+claim support for arbitrary unmanaged PostgreSQL installations.
+
+Public beta releases are distributed through npm as `@rehearsal-db/core`. Publication is
+restricted to reviewed artifacts from protected `main`; source availability alone does
+not enable production access.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [End-to-end tutorial](docs/tutorial.md)
+- [Configuration reference](docs/configuration.md)
+- [CLI commands](docs/commands.md)
+- [Sanitization policy](docs/sanitization.md)
+- [Production source boundary](docs/production-source.md)
+- [Baselines](docs/baselines.md)
+- [Project adapters](docs/adapters.md)
+- [Security model](docs/security-model.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Release process](docs/releasing.md)
+- [Glossary and architecture](docs/glossary.md)
+
+## Why use it?
+
+A migration passing against an empty database proves only that the migration can build
+a new schema. Rehearsal also proves that:
+
+- the baseline is the exact immutable artifact you reviewed;
+- historical migration files still match the baseline's digest-addressed prefix;
+- only the exact suffix is treated as candidate work;
+- production-shaped relationships survive restore and migration;
+- optional bounded Storage objects retain exact checksums through local restore;
+- the resulting local application can pass a project-owned proof;
+- unsafe or ambiguous state stops execution.
+
+## What Rehearsal is—and is not
+
+Rehearsal complements existing database workflows instead of replacing them:
+
+| Tool or environment                             | Primary job                                 | What Rehearsal adds                                                                                                        |
+| ----------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Backups and point-in-time recovery              | Recover lost production data                | A disposable, writable migration test; Rehearsal is not disaster recovery.                                                 |
+| Staging                                         | Exercise an integrated deployed application | A local resettable database shaped by reviewed production history, without giving the runtime a hosted target.             |
+| Synthetic seed data                             | Create small, known test scenarios          | Sanitized production-shaped relationships and historical edge cases, when the project explicitly authorizes them.          |
+| Database branches or preview databases          | Isolate hosted database changes             | A loopback-only runtime with immutable baseline checks, exact candidate confirmation, and project-owned acceptance proofs. |
+| Migration linters and migration-only test tools | Inspect SQL or prove a migration applies    | Restore, migrate, run the real application proof, preserve sandbox edits, and reset to the verified baseline.              |
+
+The package does not extract production data. A project may use Rehearsal entirely with
+synthetic data, or build its own least-privilege extraction and sanitization boundary.
+The current beta runs local Supabase services and therefore does not support an arbitrary
+unmanaged PostgreSQL server.
+
+## Local cost and storage
+
+Rehearsal itself has no hosted-service fee and never creates a cloud database. Normal
+local costs are Docker CPU, memory, and disk space for Supabase images, the immutable
+baseline, optional retained Storage assets, and the disposable runtime. Production-shaped
+artifacts can be large: review their manifest size before activation, keep bounded
+retention, and use `rehearsal discard` when the runtime is no longer needed. Deleting the
+runtime does not delete the immutable baseline; baseline retention remains a project-owned
+privacy and disk-management decision.
+
+The restored runtime is intentionally writable. Exact baseline row counts and foreign
+keys are proved during reset before the runtime is accepted; later verification allows
+row-level divergence from sandbox interaction or candidate data migrations while still
+checking the immutable artifact, migration lineage, runtime boundary, and project-owned
+invariants. Reset restores and reproves the exact starting data.
+
+## Quick start
+
+Install the current beta from npm:
+
+```bash
+npm install --save-dev @rehearsal-db/core
+```
+
+Contributors testing an unreleased change can use `npm link` or install the tarball
+produced by `npm pack` from a local checkout. In a consuming project, the commands are:
+
+```bash
+npx rehearsal init
+npx rehearsal init --write
+npx rehearsal baseline create --records=<safe.ndjson> --ledger=<ledger.json>
+npx rehearsal doctor
+npx rehearsal explain
+npx rehearsal run --dry-run
+npx rehearsal candidates
+npx rehearsal inspect baseline
+npx rehearsal inspect migrations
+npx rehearsal start
+npx rehearsal migrate --confirm-candidates=<sha256>
+npx rehearsal status
+npx rehearsal verify
+npx rehearsal reset
+npx rehearsal stop
+npx rehearsal discard
+```
+
+`init` previews a typed `rehearsal.config.ts`; it writes only with `--write` and never
+overwrites an existing file. Review all detected values. Rehearsal intentionally does
+not detect, copy, or enable a hosted project.
+
+`doctor` must end with `READY` before execution. `explain` and `run --dry-run` use the
+same immutable planner and perform no state-changing operations. If migrations are
+pending, execution requires the exact candidate digest printed by the plan:
+
+```bash
+npx rehearsal run --confirm-candidates=<sha256>
+```
+
+The `rehearsal` executable is the public command contract. Repository availability does
+not itself authorize an npm publication.
+
+To try the entire workflow without configuring a project or touching hosted data, clone
+this repository and run `npm ci --ignore-scripts && npm run test:fixture`. It installs
+the exact packed artifact into a clean synthetic Supabase project and proves both
+success and failure.
+
+## Configuration
+
+Configuration has an explicit schema version. Version 1 rejects unknown versions,
+unknown properties, paths outside the project root, non-loopback targets, duplicate or
+privileged ports, enabled hosted access, and permissive outbound networking.
+
+```ts
+import { defineRehearsalConfig } from "@rehearsal-db/core";
+
+export default defineRehearsalConfig({
+  schemaVersion: 1,
+  project: { name: "my-supabase-app" },
+  supabase: {
+    workdir: ".",
+    migrationDirectory: "supabase/migrations",
+    rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
+    runtimeWorkdir: ".rehearsal/runtime",
+    serviceEnvironmentFile: ".env.rehearsal-service.local",
+    serviceEnvironmentVariables: [
+      "LOCAL_IDENTITY_CLIENT_ID",
+      "LOCAL_IDENTITY_SECRET",
+    ],
+  },
+  baseline: {
+    artifactDirectory: ".rehearsal",
+    sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
+  },
+  application: {
+    startCommand: "npm run dev:rehearsal",
+    proofCommand: "npm run test:rehearsal",
+    environmentFile: ".rehearsal/runtime.env",
+  },
+  runtime: {
+    applicationUrl: "http://localhost:5175",
+    projectId: "my-app-rehearsal",
+    apiPort: 58321,
+    databasePort: 58322,
+    studioPort: 58323,
+  },
+  safety: {
+    allowedHosts: ["127.0.0.1", "::1", "localhost"],
+    blockedEnvironmentVariables: [
+      "SUPABASE_ACCESS_TOKEN",
+      "SUPABASE_DB_PASSWORD",
+      "SUPABASE_PROJECT_ID",
+    ],
+    authenticationProviders: ["example-identity-provider"],
+    hostedAccess: "disabled",
+    outboundNetwork: "deny",
+  },
+  verification: { commands: ["npm run test:rehearsal"] },
+});
+```
+
+| Property                               | Type       | Required | Default                   | Meaning and safety effect                                     |
+| -------------------------------------- | ---------- | -------- | ------------------------- | ------------------------------------------------------------- |
+| `schemaVersion`                        | `1`        | Yes      | None                      | Pins configuration meaning; unknown versions fail.            |
+| `project.name`                         | `string`   | Yes      | None                      | Stable lowercase local identifier.                            |
+| `supabase.workdir`                     | `string`   | Yes      | None                      | Project-owned Supabase workdir; cannot escape the project.    |
+| `supabase.migrationDirectory`          | `string`   | Yes      | None                      | Ordered application migration source.                         |
+| `supabase.rehearsalConfig`             | `string`   | Yes      | None                      | Dedicated unlinked local Supabase configuration.              |
+| `supabase.runtimeWorkdir`              | `string`   | Yes      | None                      | Must be `<artifactDirectory>/runtime`; always disposable.     |
+| `supabase.serviceEnvironmentFile`      | `string`   | No       | None                      | Owner-only ignored credentials for the local service stack.   |
+| `supabase.serviceEnvironmentVariables` | `string[]` | No       | `[]`                      | Exact variables accepted from the service environment file.   |
+| `baseline.artifactDirectory`           | `string`   | No       | `.rehearsal`              | Must be named `.rehearsal`; deletion-safe artifact boundary.  |
+| `baseline.sanitizationPolicy`          | `string`   | Yes      | None                      | Exhaustive project-owned classification policy.               |
+| `application.startCommand`             | `string`   | Yes      | None                      | Starts the app against the verified local runtime.            |
+| `application.proofCommand`             | `string`   | Yes      | None                      | Project-owned proof after migration.                          |
+| `application.environmentFile`          | `string`   | No       | `.rehearsal/runtime.env`  | Owner-only generated local runtime variables.                 |
+| `application.runtimeAdapter`           | `string`   | No       | None                      | Advanced project-owned post-restore adapter path.             |
+| `runtime.applicationUrl`               | URL        | No       | `http://localhost:5175`   | Must use an explicitly allowed loopback host.                 |
+| `runtime.projectId`                    | `string`   | No       | `rehearsal-local`         | Dedicated local Supabase/Docker identity.                     |
+| `runtime.apiPort`                      | TCP port   | Yes      | None                      | Dedicated non-privileged API port.                            |
+| `runtime.databasePort`                 | TCP port   | Yes      | None                      | Dedicated non-privileged PostgreSQL port.                     |
+| `runtime.studioPort`                   | TCP port   | Yes      | None                      | Dedicated non-privileged Studio port.                         |
+| `safety.allowedHosts`                  | `string[]` | No       | loopback hosts            | Version 1 rejects any non-loopback entry.                     |
+| `safety.blockedEnvironmentVariables`   | `string[]` | No       | Supabase hosted variables | Ambient values excluded from child processes.                 |
+| `safety.authenticationProviders`       | `string[]` | No       | `[]`                      | Declared identity-only external exchanges.                    |
+| `safety.hostedAccess`                  | `disabled` | No       | `disabled`                | Cannot be enabled in version 1.                               |
+| `safety.outboundNetwork`               | `deny`     | No       | `deny`                    | Cannot be weakened in version 1.                              |
+| `verification.commands`                | `string[]` | No       | `[]`                      | Additional declared project checks; commands remain explicit. |
+
+Most projects should not use `runtimeAdapter`. It exists for a project that must create
+synthetic local identities or add application-specific variables after a successful
+restore. The adapter is project-owned, receives only the verified local environment and
+baseline plus a local PostgreSQL executor, and is never bundled into the reusable
+package. Its `configureRuntime` export returns a status message and explicit environment
+variables. It must not read hosted credentials or perform network work.
+
+## What each command proves
+
+### `rehearsal doctor`
+
+Doctor checks Node 24, the Supabase CLI, a running Docker-compatible engine, required
+paths, config/runtime port agreement, baseline checksums and permissions, migration
+prefix integrity, application proof command ownership, and the fail-closed safety
+policy. Ambient hosted credential variables are reported only by name and remain
+quarantined from children.
+
+### `rehearsal explain` and `rehearsal run --dry-run`
+
+Both return the same plan data. They may read and hash configuration, migrations,
+policy, and baseline metadata. They never start or stop services, restore rows, apply a
+migration, launch the application, write a receipt, change an artifact, or contact a
+hosted resource.
+
+### `rehearsal inspect baseline`
+
+Inspection prints format and generation identifiers, the migration cutoff, table and
+row counts, and hashes for baseline data and sanitization policy. It never prints source
+rows or baseline values.
+
+### `rehearsal inspect migrations`
+
+Every local migration receives one interpretation:
+
+- `represented_by_baseline`: exact filename and SHA-256 in the baseline prefix;
+- `candidate`: exact suffix after that prefix, not yet proven in the current runtime;
+- `applied_to_current_runtime`: the exact suffix digest has a verified local receipt;
+- `modified`: a prefix filename or digest changed, so planning fails closed;
+- `invalid`: filename, ordering, uniqueness, or source structure is invalid.
+
+`rehearsal candidates` is the concise machine-friendly alias for this same migration
+inspection and exact candidate digest. It does not apply a migration.
+
+## Machine output and exit codes
+
+Commands that report state accept `--json`. The version-1 envelope contains
+`schemaVersion`, `command`, `status`, `startedAt`, `durationMs`, `warnings`, and `data`.
+Failures contain a versioned error with category, stable code, message, expected and
+actual state, context, refused action, suggestions, and a safe diagnostic identifier.
+
+| Exit | Category                       |
+| ---- | ------------------------------ |
+| 0    | Success                        |
+| 1    | Doctor completed but not ready |
+| 2    | Configuration invalid          |
+| 3    | Unsafe environment             |
+| 4    | Baseline invalid               |
+| 5    | Baseline checksum mismatch     |
+| 6    | Migration candidate failure    |
+| 7    | Migration verification failure |
+| 8    | Application proof failure      |
+| 9    | Runtime or dependency failure  |
+| 10   | Unexpected internal failure    |
+
+Human and JSON output are projections of the same model. `normal`, `--verbose`, and
+`--debug` increase explanation only; none may print secrets or baseline row values.
+
+## Guarantees
+
+Rehearsal version 1 intends to guarantee:
+
+- configuration and runtime targets are local-only;
+- hosted application/database credentials are neither required nor inherited by child processes;
+- application, provider-data, email, and hosted-database side effects fail closed;
+- any declared external identity exchange terminates in the local Auth service and its
+  credentials are read from an exact owner-only allowlist;
+- an active baseline verifies before restore;
+- migration identity uses ordered content digests, not timestamps alone;
+- a changed prefix is never silently reinterpreted as a candidate;
+- restore and migration failures cannot leave a runtime marked trusted;
+- reports omit source rows and redact credentials, connection strings, keys, tokens,
+  JWTs, passwords, and sensitive environment values.
+
+Independent barriers include strict loopback config, a dedicated unlinked Supabase
+workdir/project ID, an allowlisted child environment, and application egress denial.
+A project may explicitly declare an external identity provider, but that does not grant
+hosted application/database access. A single ambient connection string is therefore
+insufficient to redirect an operation.
+
+## Non-guarantees and user responsibilities
+
+Rehearsal does not prove that a migration is semantically correct for every application
+workflow, replace backups or disaster recovery, authorize production access, or make a
+sanitization policy correct merely because it is exhaustive. Project owners must review
+the policy, protect baseline artifacts, write meaningful application proofs, review the
+candidate digest, and keep production credentials outside the Rehearsal configuration.
+
+## Baseline lifecycle
+
+The source boundary exposes only reviewed versioned views through a least-privilege
+read-only role. Every included column has an explicit KEEP, PSEUDONYMIZE, REPLACE,
+EXCLUDE, or DERIVE action. Sanitized rows stream into an owner-only build directory.
+Only after exact hashes, counts, migration receipts, and policy metadata exist does an
+atomic pointer activate the generation. Failed builds cannot replace the current
+baseline.
+
+Restore replays the immutable historical migration bundle, streams sanitized rows into
+the disposable local database, restores optional checksummed Storage assets through the
+loopback service, restores normal enforcement, and verifies counts and foreign keys
+before candidate work begins. The package accepts project-owned asset bytes; it does not
+know how to authorize or extract them from a hosted source.
+
+Project policies may attach field-aware JSON rules and project-owned identity adapters.
+A consuming project can use those boundaries to preserve reviewed application data
+while sanitizing unrelated private values, without teaching the package its table
+names, identity relationships, or privacy decisions.
+
+## CI example
+
+The tracked [verification workflow](.github/workflows/verify.yml) is intentionally based
+on the synthetic independent fixture. A real repository should provide its own protected
+sanitized baseline through an approved artifact mechanism; never commit production data
+or credentials just to make CI convenient.
+
+## Run the independent proof
+
+From this repository on Node.js 24 with Docker running:
+
+```bash
+npm run test:fixture
+```
+
+The proof copies the tracked synthetic fixture to a disposable directory, builds its
+one-row and one-asset baseline, runs the public CLI through one valid migration and
+application proof, verifies the exact Storage byte, then introduces invalid PostgreSQL.
+Success means the valid migration preserved its row and asset, the invalid migration
+received the intended stable failure category, and the untrusted runtime was removed.
+It neither needs nor inherits application-specific or hosted credentials.
+
+## Support matrix for the first beta
+
+| Runtime or tool  | Status       | Initial contract                                      |
+| ---------------- | ------------ | ----------------------------------------------------- |
+| Node.js 24       | Supported    | Exact maintained major                                |
+| npm              | Supported    | Lockfile-backed install and CLI                       |
+| macOS            | Supported    | Directly exercised with Docker/Colima                 |
+| Linux            | Supported    | Ubuntu x64 CI and Bookworm arm64 Colima proofs        |
+| WSL              | Experimental | Must be exercised and documented before support claim |
+| Native Windows   | Unsupported  | Path, Docker, signal, and shell behavior unproven     |
+| pnpm             | Unsupported  | Detection is informational until direct proof exists  |
+| Yarn             | Unsupported  | Detection is informational until direct proof exists  |
+| MySQL/Mongo/etc. | Unsupported  | Version 1 is PostgreSQL/Supabase only                 |
+
+## Troubleshooting
+
+- `NOT READY` after Docker: start Docker Desktop or Colima, then rerun doctor.
+- Baseline checksum mismatch: do not repair the hash manually. Rebuild through the
+  reviewed extraction/sanitization workflow.
+- Migration prefix divergence: restore the exact reviewed historical file or create a
+  new baseline; never rename the edited file into the candidate suffix.
+- Candidate confirmation mismatch: rerun explain, review the exact ordered candidates,
+  and use the new digest only if those files are intended.
+- Hosted target refusal: remove the hosted value. Version 1 has no override.
+- Application proof failure: inspect the project-owned proof output; the database must
+  not be treated as verified.
+
+Security reporting, compatibility promises, and regression measurements are defined in
+[SECURITY.md](SECURITY.md), [COMPATIBILITY.md](COMPATIBILITY.md), and
+[BENCHMARKS.md](BENCHMARKS.md).

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Rehearsal security policy
+
+Rehearsal handles sensitive database topology and may process sanitized derivatives of
+production data. Do not include credentials, connection strings, raw data, or a real
+baseline in a public report.
+
+Report suspected vulnerabilities through GitHub's private vulnerability reporting for
+this repository. Do not open a public issue containing an exploit, secret, hosted
+target, or source record.
+
+Supported security updates cover the latest released 0.x minor during beta. A security
+fix may deliberately tighten configuration or refuse a workflow that an earlier beta
+accepted. During beta, reports apply to the latest published release and current `main`.
+
+The threat boundary and explicit non-guarantees live in [README.md](README.md). Every
+release candidate must pass secret-pattern checks, dependency and package-content
+audits, the installed Linux fixture, and private-reporting verification. The current
+platform evidence covers protected Ubuntu x64 CI and a direct Bookworm arm64 Colima run;
+the exact publishable artifact must repeat its required release checks.

package/SUPPORT.md

@@ -0,0 +1,15 @@
+# Support
+
+Use GitHub Issues for reproducible defects and setup problems that include a synthetic
+reproduction. Include operating system, architecture, Node version, Supabase CLI version,
+Docker engine, the failing command, safe diagnostics, and the smallest reproduction.
+The first beta does not yet maintain a separate public discussion or feature-request
+channel.
+
+Do not include credentials, connection strings, source rows, baseline artifacts, private
+URLs, or proprietary migrations. Report security problems through private vulnerability
+reporting as described in [SECURITY.md](SECURITY.md).
+
+The package is pre-release. The supported matrix is defined in
+[COMPATIBILITY.md](COMPATIBILITY.md); unsupported environments are welcome as clearly
+labelled experiments but cannot be treated as verified behavior.

package/docs/adapters.md

@@ -0,0 +1,23 @@
+# Project runtime adapters
+
+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.
+
+An adapter may export:
+
+- `prepareSchema({ baseline, runSql })` for local schema preparation before data restore;
+- `configureRuntime({ baseline, environment, runSql })` to create synthetic identities
+  or return explicit application environment values;
+- `verifyRuntime({ baseline, environment, runSql })` for project-owned invariants.
+
+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.
+
+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
+every adapter.

package/docs/baselines.md

@@ -0,0 +1,33 @@
+# 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.
+
+## Generation lifecycle
+
+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.
+
+## Migration lineage
+
+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.
+
+## Restore lifecycle
+
+`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.
+
+## Persistence model
+
+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.
+
+Treat baseline files as sensitive even after sanitization: owner-only permissions,
+ignored paths, encrypted disks, bounded retention, and explicit deletion are prudent.