@rehearsal-db/core 0.1.0-beta.7 → 0.1.0-beta.9

package/docs/runtime-policies.md

@@ -0,0 +1,191 @@
+# Runtime and identity policies
+
+These optional JSON files replace common project-owned Rehearsal adapters. They contain
+declarations only: unknown fields, SQL, JavaScript, and unsupported extensions fail.
+
+## Runtime policy
+
+Point `runtimePolicy` in `rehearsal.config.mjs` to a reviewed file:
+
+```json
+{
+  "policyVersion": 1,
+  "prerequisites": {
+    "schemas": ["extensions"],
+    "extensions": [{ "name": "pgcrypto", "schema": "extensions" }]
+  },
+  "triggers": [
+    {
+      "name": "profile_after_auth_insert",
+      "table": { "schema": "auth", "name": "users" },
+      "timing": "after",
+      "events": ["insert"],
+      "function": { "schema": "public", "name": "handle_new_user" }
+    }
+  ],
+  "localRows": [
+    {
+      "table": { "schema": "public", "name": "runtime_settings" },
+      "keyColumns": ["name"],
+      "values": { "name": "scheduler_enabled", "value": false }
+    },
+    {
+      "table": { "schema": "public", "name": "app_role_assignments" },
+      "keyColumns": ["user_id"],
+      "values": {
+        "user_id": "11111111-1111-4111-8111-111111111111",
+        "role": "owner"
+      },
+      "identityAssociation": {
+        "identity": "approved-owner",
+        "column": "user_id"
+      }
+    }
+  ],
+  "expectations": [
+    {
+      "table": { "schema": "public", "name": "profiles" },
+      "rowLevelSecurity": true,
+      "columns": [{ "name": "id", "generated": false, "identity": false }],
+      "foreignKeys": [],
+      "policies": []
+    }
+  ]
+}
+```
+
+Restore order is fixed: Rehearsal creates named schemas and allowlisted extensions
+before dependent schema objects, adds declared triggers after their tables and functions
+exist, then inserts local-only rows after baseline data. Application schema remains in
+immutable migrations or the verified schema snapshot. Verification checks extensions,
+triggers, local-only rows, columns, generated/identity behavior, foreign keys, named RLS
+policies, RLS state, and unvalidated constraints.
+
+Use `identityAssociation` when a local seed is intentionally transferred by a named
+identity policy. Verification accepts the configured placeholder before association and
+the exact recorded local identity afterward. Rehearsal stores that mapping only in its
+local internal schema; it does not duplicate the old role or weaken the row check.
+
+## Identity policy
+
+The identity policy links one verified local Supabase identity to a copied pseudonymous
+graph without an application callback patch:
+
+```json
+{
+  "identityVersion": 1,
+  "identities": [
+    {
+      "name": "approved-owner",
+      "provider": "google",
+      "emailEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_EMAIL",
+      "approvedEmailSha256": "<sha256 of the lowercase approved email>",
+      "placeholderUserId": "11111111-1111-4111-8111-111111111111",
+      "references": [
+        {
+          "schema": "public",
+          "table": "profiles",
+          "column": "user_id",
+          "required": true
+        },
+        {
+          "schema": "public",
+          "table": "app_role_assignments",
+          "column": "user_id",
+          "required": true
+        },
+        {
+          "schema": "public",
+          "table": "food_compatibility_feedback",
+          "column": "reviewed_by",
+          "required": true,
+          "strategy": "preserve-audit"
+        }
+      ],
+      "jsonReferences": [
+        {
+          "schema": "public",
+          "table": "events",
+          "column": "payload",
+          "path": ["actor_id"]
+        }
+      ],
+      "signupDefaults": [
+        {
+          "table": { "schema": "public", "table": "profiles" },
+          "identityColumn": "user_id",
+          "ignoredColumns": ["created_at", "updated_at"],
+          "values": {
+            "display_name": {
+              "kind": "pattern",
+              "pattern": "^User[0-9]{14}$"
+            },
+            "avatar_path": null
+          }
+        }
+      ],
+      "pathReferences": [
+        {
+          "schema": "public",
+          "table": "profiles",
+          "column": "avatar_path",
+          "valueType": "text"
+        }
+      ],
+      "assets": [
+        {
+          "bucket": "avatars",
+          "prefix": "11111111-1111-4111-8111-111111111111/",
+          "rewritePath": true
+        }
+      ],
+      "claims": { "rehearsal_owner": true },
+      "tokenHook": {
+        "function": {
+          "schema": "public",
+          "name": "custom_access_token_hook"
+        },
+        "expectedClaims": { "app_role": "developer" }
+      }
+    }
+  ]
+}
+```
+
+The email stays in an environment variable; only its reviewed hash is committed. After
+ordinary local sign-in creates the account, preview and confirm the association:
+
+```bash
+npx rehearsal identity plan --identity=approved-owner
+npx rehearsal identity claim --identity=approved-owner \
+  --confirm-identity=<full-sha256>
+```
+
+Rehearsal requires exactly one verified matching local provider identity. Every
+`required` reference must exist after transfer. Declare application role tables as
+references; `claims` alone is not a replacement for a database-backed token hook.
+
+References use `"strategy": "transfer"` by default. Use `"preserve-audit"` only for
+immutable historical authorship, such as a completed review. Rehearsal leaves that row
+and its synthetic Auth actor unchanged, but still transfers the active profile, roles,
+and other declared data. Undeclared references still stop the claim.
+
+`signupDefaults` resolves a copied-profile collision only when the local row's complete
+non-ignored shape matches. List every remaining column. Use ignored columns only for
+server-managed values such as timestamps. An edited value, extra column, ambiguous row,
+or unrelated local application data rolls back the entire claim.
+
+`rewritePath` copies approved Storage objects through the local Supabase Storage API,
+verifies the destination bytes, updates the declared database paths, and then removes
+the old objects. A database failure removes the new copies and leaves the originals
+usable. Restored objects may begin with either the placeholder owner or no owner;
+another owner is refused. `pathReferences` updates matching text or JSONB pointers. A configured
+`tokenHook` must return the declared claim subset before commit. The browser must then
+refresh its session or sign in again because Rehearsal cannot rewrite an issued JWT.
+
+The transaction does not import production passwords, sessions, refresh tokens,
+cookies, MFA secrets, or provider credentials. Local MFA and authorization rules remain
+real.
+
+A synthetic test can prove the plumbing and refusal controls. Claim that Google account
+selection or callback behavior works only after directly observing that real flow.

package/docs/sanitization.md

@@ -1,7 +1,7 @@
 # Sanitization policy
 
-Rehearsal deliberately does not decide what your application may copy. The consuming
-project owns an exhaustive, reviewable policy for its export surface.
+Rehearsal never decides what your application may copy. The project owner reviews an
+exhaustive policy; the package validates and executes the supported recipes.
 
 Every exported field should receive one action:
 
@@ -19,6 +19,10 @@ whether it is an identity column, and its foreign-key target or explicit absence
 draft uses `REVIEW REQUIRED` placeholders and cannot be activated until they are
 replaced and the `draft` marker is removed.
 
+Tables default to the `public` schema. Add `"schema": "app_api"` beside `name`
+for another schema. Schema plus table is the identity, so two schemas may safely contain
+tables with the same name.
+
 In an interactive terminal, the guided **Review the script** action works table by table.
 For larger tables, a human can explicitly apply safe defaults (`REPLACE`, `NEVER`
 generated, `NO` identity, and no foreign key), then review only exceptions. Likely
@@ -28,8 +32,20 @@ labeled as sensitive, every saved field remains classified, and no preset is sil
 applied. The reviewer validates the completed policy and refuses to overwrite a draft
 changed during the session.
 
-The package exports `validateSanitizationCoverage` and
-`applySanitizationAction` as generic primitives:
+Two policy versions exist:
+
+- Version 1 describes data that a project has already made safe. It remains supported
+  for synthetic/local inputs and existing baselines.
+- Version 2 is required by `baseline refresh`. It adds bounded declarative recipes so
+  Rehearsal can sanitize without project callbacks.
+
+Version 2 supports keyed UUID, email, text, and integer pseudonyms; explicit constant
+replacement; bounded date shifting; and exhaustively classified JSON objects. Unknown
+tables, columns, nested keys, formats, recipes, or missing fields fail closed. It never
+evaluates JavaScript or SQL from the policy.
+
+The package still exports `validateSanitizationCoverage` and
+`applySanitizationAction` for existing version 1 preparation tools:
 
 ```ts
 import {
@@ -50,15 +66,15 @@ const safeValue = applySanitizationAction({
 ```
 
 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.
+entries both fail. New standalone preparation should use the version 2 engine described
+in [Production source](production-source.md).
 
 ## 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
+Keep the key under `.rehearsal`, outside source control and the final baseline. The same source ID
 should map consistently within a generation, while the original value cannot be
-recovered from the artifact.
+recovered from the artifact. The manifest records only the key fingerprint.
 
 ## High-risk fields
 

package/docs/security-model.md

@@ -5,10 +5,10 @@ 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.
+The engine trusts reviewed package code, strict declarations, a verified active baseline,
+and exact migration bytes. It does not trust ambient environment variables, hosted
+project state, unknown fields, changed history, incomplete artifacts, or an unverified
+runtime.
 
 ## Independent barriers
 
@@ -24,9 +24,20 @@ changed migration history, incomplete artifacts, or an unverified runtime.
 - plain PostgreSQL receives a fresh random password per disposable runtime, retained
   only in owner-readable ignored runtime files;
 - successful receipts written only after verification.
+- separate exact-digest approval for source setup, source retirement, and identity claim;
+- short-lived source readers limited to reviewed views/columns and deny checks;
+- bounded read-only extraction with no raw dump or row-value logging;
+- exhaustive privacy policy version 2 with an owner-only local pseudonym key;
+- application children receive only explicit local mappings and stay in an owned process
+  group.
+- only one state-changing Rehearsal command may own a project at a time; stale locks are
+  recovered after their process exits;
+- a state-changing command fingerprints its installed Rehearsal package and refuses to
+  continue if that installation changes while the command is running.
 
-No single environment variable or config edit should redirect the tool to production.
-Version 1 provides no hosted execution mode.
+No single environment variable or config edit can redirect runtime commands to
+production. Optional source preparation is a separate boundary and never provides a
+hosted execution mode.
 
 ## Identity providers
 
@@ -35,10 +46,20 @@ credential names are read from an ignored owner-only file, and the callback must
 local Auth. The local account may represent a sanitized production identity, but its
 session and writes remain local.
 
+Account association is one local transaction. Rehearsal removes a signup-created row
+only when its complete declared default shape still matches, refuses unrelated local
+application data, verifies required role references and an optional token hook, and can
+copy, byte-check, and retire only declared placeholder-owned Storage paths. Immutable
+audit references may explicitly retain their synthetic historical actor. Rehearsal also
+refuses to rewrite application paths when copied records refer to files that are absent
+from local Storage. Existing browser JWTs still require an ordinary refresh or new
+sign-in.
+
 ## 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.
+appropriate, a migration has the intended business meaning, or a real provider flow was
+observed. Repository owners must review those decisions and protect artifacts. The
+configuration barriers are not an operating-system firewall.
 
 Report vulnerabilities using the private process in the root security policy.

package/docs/standalone-workflow.md

@@ -0,0 +1,107 @@
+# Standalone workflow contract
+
+Rehearsal's normal commands remain local-only. `run`, `start`, `reset`,
+`migrate`, `verify`, and `cleanup` never receive source credentials and never
+connect to a hosted database.
+
+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.
+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.
+
+## What belongs in declarations
+
+Projects declare application meaning; Rehearsal executes it. Declarations may
+name:
+
+- approved source relations and columns;
+- whether rows are approved public data or belong to one explicitly approved
+  owner;
+- privacy actions and bounded transformation recipes;
+- licensed or consented Storage buckets and prefixes;
+- schema and extension prerequisites;
+- local identities and reference locations;
+- ordinary application commands and observable proof expectations.
+
+Declarations cannot contain JavaScript callbacks, SQL fragments, passwords,
+tokens, production URLs, or automatic consent decisions. Unknown fields,
+tables, columns, recipes, JSON keys, and target identities fail closed.
+
+## Credential separation
+
+Provisioning, extraction, asset, provider, and local-runtime credentials are
+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.
+
+## Snapshot and privacy guarantees
+
+Database schema, migration evidence, and selected rows are read in one
+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.
+
+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.
+
+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,
+source scope, migration evidence, and key fingerprint without storing the key
+or source identifiers.
+
+## Restore, identities, and applications
+
+Restore performs only supported declarative prerequisites. Application schema
+changes remain immutable migration files; configuration is never an arbitrary
+privileged-SQL escape hatch.
+
+Local identities never reuse production sessions, refresh tokens, password
+hashes, provider secrets, or MFA material. An approved provider association is
+performed inside the local runtime and must match the reviewed receipt.
+
+Rehearsal launches ordinary project commands with a minimal environment and
+generated local connection files. It verifies every configured dependency
+before launch, owns only the child process group it starts, and does not claim
+to provide an operating-system firewall.
+
+Proofs require explicit positives and negatives. A process starting, a non-5xx
+response, an empty 200, a 401, or a 404 cannot satisfy a declared positive.
+Reports distinguish engine readiness, dependency readiness, proof completion,
+and provider behavior that was directly observed by a person.
+
+## Failure and upgrade behavior
+
+- Failed, interrupted, changed-policy, low-disk, or drifted refreshes leave the
+  prior active baseline and any edited runtime untouched.
+- Setup and upgrades preview exact file changes and never overwrite a reviewed
+  policy, config, baseline, or local edit silently.
+- Reset, discard, and cleanup operate only on purpose-created Rehearsal
+  resources and retain their existing exact-preview protections.
+- Rehearsal does not make legal, consent, licensing, backup, disaster-recovery,
+  universal-database, or OS-firewall guarantees.
+
+The final acceptance gate uses the exact packed or published artifact in clean
+Supabase and PostgreSQL consumers. Consumer integration code is removed only
+after that replacement is proved and the removal is separately approved.

package/docs/troubleshooting.md

@@ -114,6 +114,14 @@ rerun doctor and candidates, then execute with the new digest.
 Run the project proof directly against the generated local environment. Fix the app,
 adapter, fixture expectation, or migration; do not weaken the proof to obtain a pass.
 
+## The local application loads a hosted value from `.env`
+
+Rehearsal removes undeclared hosted credentials from the child process environment, but
+frameworks such as Vite may independently read project `.env` files after the process
+starts. Give the configured `startCommand` or framework test mode an explicit safe local
+override for the affected value. Do not delete or rewrite a developer's normal `.env`
+file as part of a rehearsal.
+
 ## Local authentication fails
 
 Confirm the provider is enabled in the dedicated local Supabase config, the allowlisted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.9",
   "private": false,
   "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
   "repository": {
@@ -21,27 +21,26 @@
     "node": ">=24 <25"
   },
   "bin": {
-    "rehearsal": "scripts/operations/rehearsal/rehearsal_cli.mjs"
+    "rehearsal": "src/cli/rehearsal.mjs"
   },
   "exports": {
     ".": {
-      "types": "./scripts/lib/rehearsal/configuration.d.mts",
-      "import": "./scripts/lib/rehearsal/configuration.mjs"
+      "types": "./src/project/configuration.d.mts",
+      "import": "./src/project/configuration.mjs"
     },
-    "./baseline": "./scripts/lib/rehearsal/baseline_artifact.mjs",
-    "./baseline-builder": "./scripts/lib/rehearsal/baseline_builder.mjs",
-    "./diagnostics": "./scripts/lib/rehearsal/diagnostics.mjs",
-    "./migrations": "./scripts/lib/rehearsal/migration_history.mjs",
-    "./process-environment": "./scripts/lib/rehearsal/process_environment.mjs",
-    "./schema": "./scripts/lib/rehearsal/schema_snapshot.mjs",
-    "./service-environment": "./scripts/lib/rehearsal/service_environment.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"
   },
   "files": [
-    "scripts/lib/environment/local_supabase.mjs",
-    "scripts/lib/rehearsal",
-    "scripts/lib/runtime",
-    "scripts/operations/database/manage_rehearsal_database.mjs",
-    "scripts/operations/rehearsal/rehearsal_cli.mjs",
+    "src",
+    "scripts/runtime/manage_database.mjs",
     "docs/*.md",
     "README.md",
     "BENCHMARKS.md",
@@ -53,15 +52,18 @@
   ],
   "scripts": {
     "test": "vitest run",
-    "test:unit": "vitest run tests/scripts",
+    "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/operations/rehearsal/prove_independent_fixture.mjs",
-    "test:fixture:postgresql": "node scripts/operations/rehearsal/prove_postgresql_fixture.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 scripts tests -type f -name '*.mjs' -exec node --check {} +",
+    "check:syntax": "find src scripts tests -type f -name '*.mjs' -exec node --check {} +",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "package:audit": "node scripts/operations/rehearsal/audit_package.mjs"
+    "package:audit": "node scripts/verification/audit_package.mjs"
   },
   "keywords": [
     "postgresql",
@@ -72,7 +74,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@clack/prompts": "^1.8.1"
+    "@clack/prompts": "^1.8.1",
+    "pg": "^8.23.1"
   },
   "devDependencies": {
     "@lydell/node-pty": "^1.2.0-beta.15",

package/scripts/runtime/manage_database.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Select the configured database runtime and forward the requested
+ * lifecycle action to its isolated driver.
+ */
+
+import { loadRehearsalConfig } from "../../src/project/configuration.mjs";
+import {
+  parseRuntimeInvocation,
+  runRuntimeTarget,
+} from "../../src/targets/target.mjs";
+
+const invocation = parseRuntimeInvocation();
+const { config } = await loadRehearsalConfig({
+  projectRoot: process.cwd(),
+  configPath: invocation.configPath,
+});
+await runRuntimeTarget(config.runtime.target);

package/src/README.md

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