@rehearsal-db/core 0.1.0-beta.11 → 0.1.0-beta.13

package/docs/sanitization.md

@@ -40,10 +40,10 @@ Two policy versions exist:
   Rehearsal can sanitize without project callbacks.
 
 Version 2 supports keyed UUID, email, text, and integer pseudonyms; explicit constant
-replacement; bounded date shifting; approved-owner conditionals; exhaustively classified
-JSON objects; and bounded JSON arrays. Unknown tables, columns, nested keys, formats,
-recipes, or missing required fields fail closed. It never evaluates JavaScript or SQL
-from the policy.
+replacement; bounded and grouped date shifting; identity-aware path mapping;
+approved-owner conditionals; exhaustively classified JSON objects; and bounded JSON
+arrays. Unknown tables, columns, nested keys, formats, recipes, or missing required
+fields fail closed. It never evaluates JavaScript or SQL from the policy.
 
 ## Approved-owner values
 
@@ -69,7 +69,7 @@ environment-variable name and SHA-256 receipt:
           "action": "PSEUDONYMIZE",
           "recipe": { "format": "uuid", "namespace": "account-id" },
           "generated": "NEVER",
-          "identity": "YES",
+          "identity": "NO",
           "foreignKey": null
         },
         {
@@ -101,12 +101,78 @@ node -e 'const {createHash}=require("node:crypto"); process.stdout.write(createH
 
 Every conditional table names its owner column. Missing bindings, hash mismatches,
 missing owner columns, null/unsupported owner values, and conditionals without an owner
-binding are refused. The owner column must be marked `identity: "YES"` and use
-`PSEUDONYMIZE`, preventing a conditional policy from retaining raw account IDs. Other
+binding are refused. The owner column must use `PSEUDONYMIZE`, preventing a conditional
+policy from retaining raw account IDs. `identity` describes PostgreSQL's generated SQL
+identity metadata, not whether a value identifies a person: ordinary UUID primary keys
+use `"NO"`, while a genuine `GENERATED ... AS IDENTITY` column uses `"YES"`. Rehearsal
+checks the restored PostgreSQL schema for a real backing sequence before attempting a
+sequence reset, so UUID identity values never receive numeric sequence operations. Other
 owners take the declared `otherwise` path; every other identity-bearing field still
 needs its own pseudonymization declaration. Supply the binding only to the local
 server-side Rehearsal process; do not put it in the policy, baseline, or tracked files.
 
+## Identity-aware Storage paths
+
+Use one named mapping when a database column and a physical Storage object both begin
+with the approved owner's ID. Rehearsal pseudonymizes only that first segment and keeps
+the remaining path unchanged:
+
+```json
+{
+  "pathMappings": {
+    "owner-storage": {
+      "binding": "approved-owner",
+      "format": "uuid",
+      "namespace": "account-id",
+      "maximumBytes": 512,
+      "maximumSegments": 8
+    }
+  },
+  "tables": [
+    {
+      "name": "profiles",
+      "sourceRows": "STREAM AND SANITIZE",
+      "columns": [
+        {
+          "name": "avatar_path",
+          "action": "DERIVE",
+          "recipe": { "kind": "path-map", "mapping": "owner-storage" },
+          "generated": "NEVER",
+          "identity": "NO",
+          "foreignKey": null
+        }
+      ]
+    }
+  ]
+}
+```
+
+The source policy uses the same mapping name and names the binding's environment
+variable as `prefixEnvironmentVariable`; it never contains the raw owner ID. During
+`rehearsal refresh`, the package uses the mapping for both database values and physical
+object destinations. A missing mapping, a different environment variable, a path whose
+first segment is not the exact reviewed owner, traversal, or a size/segment limit breach
+stops the refresh.
+
+## Related dates
+
+Give related timestamps the same `group` and `days` value to shift them by one stable
+offset. This preserves their order and duration:
+
+```json
+{
+  "name": "starts_at",
+  "action": "DERIVE",
+  "recipe": { "kind": "date-shift", "days": 30, "group": "event-window" },
+  "generated": "NEVER",
+  "identity": "NO",
+  "foreignKey": null
+}
+```
+
+Apply the same recipe to `ends_at`. Rehearsal refuses a group that declares conflicting
+`days` values. Leave out `group` when a date should shift independently.
+
 ## Structured JSON
 
 `json-object` fields are required by default. Set `"required": false` on an explicitly

package/docs/security-model.md

@@ -26,6 +26,9 @@ runtime.
 - 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;
+- externally provisioned readers require canonical view-definition receipts,
+  `security_barrier`, independent ownership, an exact non-system readable-column surface,
+  no write or role-escalation paths, and database-enforced expiration;
 - 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
@@ -39,6 +42,11 @@ 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.
 
+External source mode verifies access but does not own it. Rehearsal makes no source-side
+changes and removes only its local credential and receipt. The provider owns early
+revocation and the database enforces the reviewed short expiration; Rehearsal never
+reports local cleanup as proof that a provider-owned role was deleted.
+
 ## Identity providers
 
 An optional external identity handshake is distinct from database access. Only declared

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
 
@@ -46,9 +48,12 @@ 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, role isolation, security-definer denial, and a short database-enforced
+expiration. Rehearsal never claims ownership or revocation of provider-managed objects.
 
 ## Snapshot and privacy guarantees
 
@@ -57,6 +62,16 @@ 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,

package/docs/troubleshooting.md

@@ -34,14 +34,15 @@ Choose **Set the stage** and approve the preview. For pnpm and Yarn, use this gu
 automatic root generation is currently tested with npm. An existing supported config is
 kept in place, including `infrastructure/rehearsal/rehearsal.config.mjs`.
 
-## Setup says Node.js 24 is required
+## Setup says this Node.js version is unsupported
 
-Rehearsal intentionally supports one maintained Node.js major in its first beta. Switch
-the current shell before installing or running it. With nvm:
+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 24
-nvm use 24
+nvm install --lts
+nvm use --lts
 node --version
 ```
 
@@ -53,6 +54,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:
@@ -146,9 +153,20 @@ 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.
 
 If `identity plan` refuses the matcher, read the message literally:
 

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.13",
   "private": false,
   "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
   "repository": {
@@ -10,7 +10,7 @@
   "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",
@@ -18,7 +18,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=24 <25"
+    "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
   },
   "bin": {
     "rehearsal": "src/cli/rehearsal.mjs"
@@ -62,6 +62,7 @@
     "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:onboarding": "node scripts/verification/fixtures/onboarding.mjs",
     "test:fixture:standalone": "node scripts/verification/fixtures/standalone.mjs",
     "test:fixture:privacy": "node scripts/verification/fixtures/privacy.mjs",
     "check": "npm run check:syntax && npm run test && npm run docs:build && npm run format:check && npm run package:audit",

package/src/baseline/artifact.mjs

@@ -372,12 +372,35 @@ export const createAndActivateBaseline = async ({
     }
     return manifest;
   } catch (error) {
+    let cleanupFailure;
     if (dataHandle) await dataHandle.close().catch(() => undefined);
-    await chmod(buildDirectory, 0o700).catch(() => undefined);
-    await rm(buildDirectory, { recursive: true, force: true });
+    await makeArtifactTreeWritable(buildDirectory).catch(() => undefined);
+    await rm(buildDirectory, { recursive: true, force: true }).catch(
+      (cleanupError) => {
+        cleanupFailure = cleanupError;
+      },
+    );
     if (finalCreated) {
-      await chmod(finalDirectory, 0o700).catch(() => undefined);
-      await rm(finalDirectory, { recursive: true, force: true });
+      await makeArtifactTreeWritable(finalDirectory).catch(() => undefined);
+      await rm(finalDirectory, { recursive: true, force: true }).catch(
+        (cleanupError) => {
+          cleanupFailure ??= cleanupError;
+        },
+      );
+    }
+    if (
+      cleanupFailure &&
+      error &&
+      (typeof error === "object" || typeof error === "function")
+    ) {
+      try {
+        Object.defineProperty(error, "cleanupError", {
+          value: cleanupFailure,
+          enumerable: false,
+        });
+      } catch {
+        // Preserve the preparation failure even when its Error is immutable.
+      }
     }
     throw error;
   }