@rehearsal-db/core 0.1.0-beta.9 → 0.1.0-rc.2

package/docs/standalone-workflow.md

@@ -8,16 +8,18 @@ The optional preparation workflow is a separate security boundary. It has
 three deliberately separate phases:
 
 1. `source plan` reads declarations and produces a redacted, exact plan.
-2. `source apply` requires the plan digest and source-owner credentials from a
-   named environment variable. It creates only the declared, time-limited
-   reader and export surface.
+2. `source apply` requires the plan digest. Managed mode uses source-owner credentials
+   from a named environment variable and creates only the declared, time-limited reader
+   and export surface. External mode verifies an already restricted reader without an
+   administrator credential or source-side writes.
 3. `refresh` uses that reader in a read-only repeatable-read transaction, builds
    privately, activates only after verification, resets the local runtime, and applies
    reviewed retention. `baseline refresh` is the lower-level baseline-only form.
 
-`source retire` has its own preview and digest. It removes only the exact
-reader and export objects Rehearsal recorded. It never searches for similarly
-named roles or removes unrelated grants.
+`source retire` has its own preview and digest. Managed mode removes only the exact
+reader and export objects Rehearsal recorded. External mode removes only local Rehearsal
+credentials and receipts, preserving provider-owned objects. It never searches for
+similarly named roles or removes unrelated grants.
 
 ## What belongs in declarations
 
@@ -28,6 +30,8 @@ name:
 - whether rows are approved public data or belong to one explicitly approved
   owner;
 - privacy actions and bounded transformation recipes;
+- hashed server-side owner bindings and explicit approved/other-owner branches;
+- bounded nested JSON objects and arrays with required/optional fields;
 - licensed or consented Storage buckets and prefixes;
 - schema and extension prerequisites;
 - local identities and reference locations;
@@ -44,9 +48,16 @@ separate. A declaration contains only the name of an environment variable or
 owner-only secret file. Rehearsal never puts credential values in command-line
 arguments, reports, baselines, receipts, or a launched application.
 
-The current workflow creates and verifies its own temporary PostgreSQL reader. An
-externally provisioned reader is not yet accepted because Rehearsal cannot currently
-prove that reader's complete scope and retirement behavior.
+The default managed workflow creates and verifies its own temporary PostgreSQL reader.
+External mode accepts a provider-managed reader only when its complete non-system
+readable-column surface exactly matches the reviewed export views and migration ledger.
+It also verifies canonical view-definition fingerprints, `security_barrier`, ownership,
+write denial, security-definer denial, and a short database-enforced expiration. An
+external login can declare a bounded exact list of provider-owned permission groups;
+each must be non-login, non-privileged, directly inherited, unable to be assumed or
+delegated, and free of nested membership. Undeclared or unsafe role membership fails as
+an actionable source-authorization refusal. Rehearsal never claims ownership or
+revocation of provider-managed objects.
 
 ## Snapshot and privacy guarantees
 
@@ -55,16 +66,28 @@ read-only repeatable-read PostgreSQL transaction. Rehearsal rechecks the source
 identity and migration evidence before commit. Rows stream in bounded batches;
 record bodies never appear in progress or error output.
 
+The snapshot boundary is deliberate: row commits made after extraction starts are left
+for the next baseline, while concurrent schema or migration-ledger changes block the
+current activation. Invalid estimates, malformed batches, connection loss, interruption,
+and disk or configured-limit failures remove private staging and preserve the previously
+active baseline.
+
+Cleanup recursively makes only Rehearsal's private staging tree removable. A failed
+Storage transfer therefore reports the original safe transfer error, removes incomplete
+files, and does not alter the active generation.
+
 Storage objects do not share the database transaction guarantee. Their inventory records
 size and version metadata; transfer requires that version, verifies the exact byte count,
 and records a SHA-256 in the immutable baseline. Transfer refuses an object that changes,
 exceeds its declared limit, or falls outside an approved bucket and prefix.
 
 Privacy policy version 2 is executable without project sanitizer code. It
-supports exact keep, exclusion, keyed pseudonyms, constants, and a small set of
-documented derivations. Policies classify every selected field and supported
-nested JSON key. A new or unknown field blocks refresh until the policy is
-reviewed again.
+supports exact keep, exclusion, keyed and constraint-preserving pseudonyms (including
+safe loopback HTTPS replacements), bounded reviewed-identity substitution inside
+retained text,
+constants, named sanitized-input digests, and a small set of documented
+derivations. Policies classify every selected field and supported nested JSON
+key. A new or unknown field blocks refresh until the policy is reviewed again.
 
 The pseudonym key is an owner-only local secret. It is not stored in the
 baseline or source control. Receipts bind the policy bytes, schema shape,

package/docs/troubleshooting.md

@@ -11,23 +11,42 @@ Doctor names each missing or unsafe item. If you still need help, run
 
 ## `npx rehearsal` cannot find the command
 
-Confirm you are in the project directory and install the beta locally:
+Confirm you are in the project directory and install the current release locally:
 
 ```bash
-npm install --save-dev @rehearsal-db/core@beta
+npm install --save-dev @rehearsal-db/core
 npx rehearsal --help
 ```
 
 Do not use `sudo` or require a global install.
 
-## Setup says Node.js 24 is required
+## Installation did not create `rehearsal.config.mjs`
 
-Rehearsal intentionally supports one maintained Node.js major in its first beta. Switch
-the current shell before installing or running it. With nvm:
+Rehearsal intentionally skips automatic creation when install scripts are disabled, the
+install is global or temporary, or more than one workspace application could own the
+config. From the intended application directory, run:
 
 ```bash
-nvm install 24
-nvm use 24
+npx rehearsal
+```
+
+Choose **Set the stage** and approve the preview. For pnpm and Yarn, use this guided path;
+automatic root generation is currently tested with npm. An existing supported config is
+kept in place, including `infrastructure/rehearsal/rehearsal.config.mjs`. When npm shows
+lifecycle output, the install message names the active path and explains when that
+existing file prevented `rehearsal.config.mjs` from being generated. You can always run
+`npx rehearsal init --json` and read `data.destination`. To relocate it safely, follow
+[Move an existing config to the project root](configuration.md#move-an-existing-config-to-the-project-root).
+
+## Setup says this Node.js version is unsupported
+
+Rehearsal supports the maintained Node.js 22, 24, and 26 release lines. Node.js 20 and
+odd-numbered releases are end-of-life. Switch the current shell before installing or
+running Rehearsal. The latest LTS is the recommended default:
+
+```bash
+nvm install --lts
+nvm use --lts
 node --version
 ```
 
@@ -39,6 +58,12 @@ writes setup files.
 Start Docker Desktop or Colima, confirm `docker info`, then rerun `rehearsal doctor`.
 Restarting the computer is rarely necessary.
 
+When a container stays in `starting` or becomes `unhealthy`, Rehearsal reports a runtime
+dependency failure rather than a migration failure. The safe diagnostic includes Docker
+CPU, memory, and container counts; Colima also includes available VM memory when it can
+be read. Stop unrelated local stacks or increase the engine's resources before retrying.
+Rehearsal never changes engine settings or bypasses service health checks.
+
 ## Docker or Colima is out of disk space
 
 Preview what Rehearsal can safely remove:
@@ -122,11 +147,58 @@ starts. Give the configured `startCommand` or framework test mode an explicit sa
 override for the affected value. Do not delete or rewrite a developer's normal `.env`
 file as part of a rehearsal.
 
+## `rehearsal open` cannot start the app
+
+`open` requires `application.readiness` in `rehearsal.config.mjs`. Confirm that its URL
+uses `localhost`, `127.0.0.1`, or `::1`, matches the app's sandbox port, and returns the
+configured status after startup. Rehearsal leaves the verified database runtime running
+when application startup fails, so retrying does not discard local database or Storage
+changes.
+
 ## Local authentication fails
 
-Confirm the provider is enabled in the dedicated local Supabase config, the allowlisted
-service environment file exists with owner-only permissions, and the provider callback
-is the local Auth callback. Do not paste provider secrets into config or terminal output.
+For Google or GitHub, confirm `supabase.authentication` is declared in
+`rehearsal.config.mjs`, its ignored environment file exists with `chmod 600`, and the
+provider has the printed local Auth callback registered. Rehearsal generates the
+disposable Supabase provider block.
+
+When migrating from the legacy service environment fields, replace those fields together
+with `supabase.authentication` and rerun `rehearsal doctor`. A compatible Google or
+GitHub provider section may remain in the tracked template: Rehearsal supersedes it only
+inside the generated runtime copy. Doctor refuses unknown provider settings, duplicate
+or nested provider sections, and nonce or optional-email settings that do not match the
+new declaration. Keep both options false unless there is a reviewed provider-specific
+need; skipping nonce validation reduces replay protection. Otherwise keep using the
+documented legacy configuration.
+Never paste provider secrets into tracked config or terminal output.
+
+For the shortest supported copied-account flow, run:
+
+```bash
+npx rehearsal identity connect
+```
+
+Leave that terminal open, then sign in through the sandbox application normally. Rehearsal
+waits for one verified match and shows a redacted plan before it changes anything. If it
+keeps waiting, finish the provider callback and confirm the reviewed matcher environment
+value is available in the terminal that started Rehearsal. `Ctrl+C`, `Ctrl+Z`, or choosing
+**Not now** stops only the owned application and leaves the database unchanged.
+
+After a successful connection, sign out and sign in once so the application receives
+fresh role claims. Rehearsal remembers the connection in the current disposable runtime;
+`reset` deliberately removes that receipt, so the next copied-account connection requires
+review again.
+
+If `identity plan` refuses the matcher, read the message literally:
+
+- **Provider or matcher type is unsupported:** use only the combinations documented in
+  [Runtime and identity policies](runtime-policies.md).
+- **No verified identity matches:** complete an ordinary local sign-in, confirm the
+  correct environment value is present, then run the plan again.
+- **More than one identity matches:** narrow the provider allowlist or use a hashed
+  provider-subject matcher. Rehearsal will not guess between accounts.
+- **Provider subject conflicts:** the local Auth identity disagrees with itself; remove
+  and recreate that disposable local sign-in instead of forcing a claim.
 
 ## Runtime changes disappeared
 

package/docs/tutorial.md

@@ -3,7 +3,8 @@
 This tutorial runs a complete PostgreSQL rehearsal in a temporary fictional project. It
 does not use your application, production data, or a hosted database.
 
-Allow about five minutes. You need Node.js 24 and a running Docker-compatible engine.
+Allow about five minutes. You need Node.js 22, 24, or 26 and a running
+Docker-compatible engine. Node.js 24 LTS is recommended.
 
 ## 1. Prepare Rehearsal
 
@@ -105,3 +106,8 @@ npm run test:fixture
 ```
 
 The PostgreSQL equivalent is `npm run test:fixture:postgresql`.
+
+The release workflow also runs `npm run test:fixture:onboarding` from the packed package.
+That check creates fresh Supabase and PostgreSQL consumers, verifies beta configuration
+preservation, and exercises safe refusal and recovery for partial setup, occupied ports,
+malformed configuration, and missing credentials.

package/docs/typescript.md

@@ -0,0 +1,134 @@
+# TypeScript
+
+Rehearsal includes types for its documented public APIs. TypeScript is optional: the CLI and the
+generated `rehearsal.config.mjs` work in JavaScript, TypeScript, CommonJS, and ESM
+applications.
+
+## Type-check the generated config
+
+Keep the generated configuration as `.mjs`. The `// @ts-check` line and
+`defineRehearsalConfig` provide editor feedback without adding a build step or asking
+Node.js to execute a TypeScript config file.
+
+<!-- checked-example: javascript-config -->
+
+```js
+// @ts-check
+import { defineRehearsalConfig } from "@rehearsal-db/core";
+
+export default defineRehearsalConfig({
+  schemaVersion: 1,
+  project: { name: "example-postgresql-app" },
+  postgresql: { migrationDirectory: "migrations" },
+  baseline: {
+    sanitizationPolicy: "rehearsal/sanitization-policy.json",
+  },
+  application: {
+    startCommand: "npm run dev",
+    proofCommand: "npm test",
+  },
+  runtime: {
+    target: "postgresql",
+    databasePort: 55432,
+  },
+});
+```
+
+This catches misspelled keys, missing required values, invalid runtime targets, and wrong
+value types before Rehearsal starts. Runtime validation remains authoritative and still
+fails closed when a configuration is unsafe.
+
+## Import the public types
+
+Application tooling may import types from the package root. Type-only imports disappear
+from compiled JavaScript and do not start Rehearsal.
+
+<!-- checked-example: type-usage -->
+
+```ts
+import type {
+  NormalizedRehearsalConfig,
+  RehearsalConfig,
+  RehearsalConfigVersion,
+} from "@rehearsal-db/core";
+
+export const schemaVersion: RehearsalConfigVersion = 1;
+
+export const application = {
+  startCommand: "npm run dev",
+  proofCommand: "npm test",
+} satisfies RehearsalConfig["application"];
+
+export const localDatabasePort = (config: NormalizedRehearsalConfig): number =>
+  config.runtime.ports.database;
+```
+
+## Exported configuration types
+
+| Export                      | Meaning                                                                   |
+| --------------------------- | ------------------------------------------------------------------------- |
+| `RehearsalConfigVersion`    | The supported configuration format. It is currently the literal type `1`. |
+| `RehearsalConfig`           | The reviewed input shape of `rehearsal.config.mjs`.                       |
+| `NormalizedRehearsalConfig` | The immutable, defaulted configuration returned by Rehearsal's loader.    |
+| `defineRehearsalConfig()`   | Checks a config while preserving its more specific inferred value types.  |
+
+Nested sections are available through indexed access types such as
+`RehearsalConfig["application"]`, `RehearsalConfig["runtime"]`, and
+`RehearsalConfig["safety"]`. The [configuration reference](configuration.md) explains
+what each setting does and remains the source of truth for runtime behavior.
+
+## Type reviewed privacy policies
+
+The advanced privacy entry point exports the normalized policy, table, column, engine,
+foreign-key, and source-record types emitted from the same implementation used for
+runtime validation. Keep policy input as ordinary JSON-compatible data and use the
+validator's typed return value; runtime validation remains the authority for untrusted
+files.
+
+<!-- checked-example: privacy-usage -->
+
+```ts
+import {
+  validateExecutablePrivacyPolicy,
+  type ExecutablePrivacyPolicy,
+  type PrivacyColumn,
+} from "@rehearsal-db/core/privacy";
+
+export const policy: ExecutablePrivacyPolicy = validateExecutablePrivacyPolicy({
+  policyVersion: 2,
+  migrationCutoff: "20260101000000",
+  tables: [
+    {
+      name: "widgets",
+      sourceRows: "STREAM AND SANITIZE",
+      columns: [
+        {
+          name: "id",
+          action: "PSEUDONYMIZE",
+          recipe: { format: "uuid", namespace: "widget-id" },
+          generated: "NEVER",
+          identity: "NO",
+          foreignKey: null,
+        },
+      ],
+    },
+  ],
+});
+
+export const identifierColumn: PrivacyColumn = policy.tables[0]!.columns[0]!;
+```
+
+## Package implementation and declarations
+
+All shipped Rehearsal implementation source is TypeScript. The package build emits
+ordinary ESM JavaScript for Node.js together with declaration files. Consumers do not
+need TypeScript, a transpiler, or a TypeScript runtime.
+
+The package-root import, `@rehearsal-db/core`, uses declarations generated from the
+same TypeScript implementation that runs at runtime; the small `types/` entry point
+only forwards those generated declarations. Advanced subpath imports such as
+`@rehearsal-db/core/baseline` and `@rehearsal-db/core/privacy` also receive generated declarations, but they remain
+advanced APIs: only their documented exports and behavior are compatibility promises.
+
+Rehearsal's own `npm run typecheck` compiles every example on this page. A documentation
+contract also requires the displayed snippets to match those checked files exactly.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.9",
+  "version": "0.1.0-rc.2",
   "private": false,
-  "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
+  "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ddupasquier/rehearsal-db.git"
@@ -10,37 +10,36 @@
   "bugs": {
     "url": "https://github.com/Ddupasquier/rehearsal-db/issues"
   },
-  "homepage": "https://github.com/Ddupasquier/rehearsal-db#readme",
+  "homepage": "https://ddupasquier.github.io/rehearsal-db/",
   "publishConfig": {
     "access": "public",
-    "tag": "beta",
     "provenance": true
   },
   "type": "module",
   "engines": {
-    "node": ">=24 <25"
+    "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
   },
   "bin": {
-    "rehearsal": "src/cli/rehearsal.mjs"
+    "rehearsal": "dist/src/cli/rehearsal.mjs"
   },
   "exports": {
     ".": {
-      "types": "./src/project/configuration.d.mts",
-      "import": "./src/project/configuration.mjs"
+      "types": "./types/configuration.d.mts",
+      "import": "./dist/src/index.mjs"
     },
-    "./baseline": "./src/baseline/artifact.mjs",
-    "./baseline-builder": "./src/baseline/builder.mjs",
-    "./diagnostics": "./src/shared/diagnostics.mjs",
-    "./migrations": "./src/runtime/migration_history.mjs",
-    "./process-environment": "./src/shared/process_environment.mjs",
-    "./privacy": "./src/baseline/privacy_engine.mjs",
-    "./schema": "./src/baseline/schema_snapshot.mjs",
-    "./service-environment": "./src/runtime/service_environment.mjs",
-    "./source-access": "./src/source/access.mjs"
+    "./baseline": "./dist/src/baseline/artifact.mjs",
+    "./baseline-builder": "./dist/src/baseline/builder.mjs",
+    "./diagnostics": "./dist/src/shared/diagnostics.mjs",
+    "./migrations": "./dist/src/runtime/migration_history.mjs",
+    "./process-environment": "./dist/src/shared/process_environment.mjs",
+    "./privacy": "./dist/src/baseline/privacy_engine.mjs",
+    "./schema": "./dist/src/baseline/schema_snapshot.mjs",
+    "./service-environment": "./dist/src/runtime/service_environment.mjs",
+    "./source-access": "./dist/src/source/access.mjs"
   },
   "files": [
-    "src",
-    "scripts/runtime/manage_database.mjs",
+    "dist",
+    "types",
     "docs/*.md",
     "README.md",
     "BENCHMARKS.md",
@@ -51,16 +50,26 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "vitest run",
-    "test:unit": "vitest run tests/unit",
-    "test:integration": "vitest run tests/integration tests/contracts",
-    "test:docs": "vitest run tests/contracts/documentationCommands.test.mjs",
-    "test:fixture": "node scripts/verification/fixtures/supabase.mjs",
-    "test:fixture:postgresql": "node scripts/verification/fixtures/postgresql.mjs",
-    "test:fixture:dependent": "node scripts/verification/fixtures/dependent.mjs",
-    "test:fixture:standalone": "node scripts/verification/fixtures/standalone.mjs",
-    "check": "npm run check:syntax && npm run test && npm run format:check && npm run package:audit",
-    "check:syntax": "find src scripts tests -type f -name '*.mjs' -exec node --check {} +",
+    "postinstall": "node dist/scripts/install/create_root_config.mjs",
+    "prepack": "npm run build",
+    "build": "node scripts/build/clean.mjs && tsc --project tsconfig.build.json",
+    "docs:build": "node scripts/docs/build.mjs",
+    "docs:preview": "node scripts/docs/serve.mjs",
+    "test": "npm run build && vitest run",
+    "test:unit": "npm run build && vitest run tests/unit",
+    "test:integration": "npm run build && vitest run tests/integration tests/contracts",
+    "test:docs": "npm run build && vitest run tests/contracts/documentationCommands.test.mjs",
+    "test:fixture": "npm run build && node scripts/verification/run_scenario.mjs supabase",
+    "test:fixture:postgresql": "npm run build && node scripts/verification/run_scenario.mjs postgresql",
+    "test:fixture:dependent": "npm run build && node scripts/verification/run_scenario.mjs dependent-target",
+    "test:fixture:onboarding": "npm run build && node scripts/verification/run_scenario.mjs onboarding",
+    "test:fixture:typescript": "npm run build && node scripts/verification/run_scenario.mjs typescript",
+    "test:fixture:standalone": "npm run build && node scripts/verification/run_scenario.mjs standalone",
+    "test:fixture:privacy": "npm run build && node scripts/verification/run_scenario.mjs privacy",
+    "release:verify": "node scripts/verification/release_gate.mjs",
+    "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
+    "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
+    "typecheck": "npm run build && tsc --project tsconfig.json",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "package:audit": "node scripts/verification/audit_package.mjs"
@@ -78,8 +87,14 @@
     "pg": "^8.23.1"
   },
   "devDependencies": {
+    "@fontsource-variable/dm-sans": "^5.3.0",
+    "@fontsource-variable/fraunces": "^5.3.0",
     "@lydell/node-pty": "^1.2.0-beta.15",
+    "@types/node": "22.20.5",
+    "@types/pg": "^8.23.1",
+    "marked": "^18.0.14",
     "prettier": "^3.9.6",
+    "typescript": "7.0.2",
     "vitest": "^5.0.2"
   }
 }

package/types/configuration.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Compatibility declaration entry point.
+ * Public types are emitted from the TypeScript implementation in dist/src.
+ */
+export * from "../dist/src/index.mjs";

package/src/README.md

@@ -1,17 +0,0 @@
-# Source layout
-
-Production code is grouped by the responsibility it owns:
-
-- `application/` starts and proves the project application.
-- `baseline/` creates, validates, and stores safe baseline artifacts.
-- `cli/` is the human and automation entry point.
-- `identity/` associates copied data with verified local users.
-- `project/` owns configuration, setup, and support reporting.
-- `runtime/` plans, verifies, resets, migrates, and cleans local runtimes.
-- `shared/` contains small target-neutral infrastructure.
-- `source/` controls approved source access and baseline refresh.
-- `targets/` contains the PostgreSQL and Supabase runtime adapters.
-
-Place a new module in the domain that owns its policy. Keep database-specific behavior
-behind `targets/`, repository-only checks under `scripts/verification/`, and public
-imports behind the export map in `package.json`.