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

package/CHANGELOG.md

@@ -5,6 +5,82 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-beta.14] - 2026-10-05
+
+### Added
+
+- Packed-package onboarding is now a required CI job. It covers fresh Supabase and
+  PostgreSQL installs, beta.7 configuration preservation, missing credentials, occupied
+  ports, malformed configuration, and non-destructive partial-setup recovery.
+- The independent test lab can run the same first-install boundary against an exact
+  candidate tarball before either database lifecycle.
+- Installation and setup now report the exact active Rehearsal configuration path and
+  explain when a supported existing nested config prevents root-file generation.
+- Packed-package onboarding covers fresh, nested, existing-root, and repeated installs
+  while proving reviewed configuration bytes are preserved.
+- Privacy policy version 2 can explicitly treat nullable owners as non-matches and match
+  an approved owner through any of a bounded list of pseudonymized identity columns.
+- Bounded JSON unions classify each permitted root type, while JSON dictionaries require
+  reviewed runtime-key formats, key actions, value recipes, and item/depth/byte limits.
+- JSON dictionaries can restrict runtime keys to canonical signed integers within an
+  explicit safe-integer range, preserving positive, negative, and reviewed zero keys
+  without widening numeric maps to arbitrary text.
+- Date shifting can explicitly preserve numeric epoch-millisecond representation,
+  including inside structured JSON, while sharing a stable grouped offset with related
+  epoch or ISO-string dates.
+- Bounded scalar enums retain only explicitly reviewed structural strings, finite
+  numbers, or booleans inside ordinary fields and nested JSON declarations, rejecting
+  out-of-domain values without echoing them in diagnostics.
+- Validated strings preserve bounded, case-sensitive structural codes from open domains
+  using a package-owned portable alphabet, refusing credential-shaped and malformed
+  text without consumer regexes, callbacks, or static identifier lists.
+- Keyed hexadecimal and GTIN pseudonyms preserve reviewed database constraints, while
+  fixed-width digest recipes derive fingerprints only from explicitly named sanitized
+  columns and reject missing, excluded, duplicate, or cyclic inputs.
+- A single GTIN recipe can declare reviewed `allowedLengths`, preserving each source
+  value's 8-, 12-, 13-, or 14-digit shape and check digit even inside structured JSON.
+- Keyed URL pseudonyms replace private HTTPS URLs with deterministic, bounded HTTPS
+  loopback paths without retaining source hosts, paths, credentials, queries, or tokens.
+- Bounded binding substitution can retain permitted surrounding text while replacing
+  exact occurrences of a reviewed UUID with its corresponding keyed UUID pseudonym.
+- External PostgreSQL readers can declare a bounded exact allowlist of provider-owned
+  permission groups. Rehearsal verifies safe membership options, group attributes,
+  nesting, view ownership, and the complete effective privilege surface.
+
+### Documentation
+
+- First-time users now have a short recovery table for interrupted setup, failed
+  upgrades, port conflicts, missing OAuth credentials, and low Docker capacity.
+- The configuration guide documents a safe manual move to the project root, separating
+  config-file-relative JavaScript imports from project-root-relative Rehearsal paths.
+- The sanitization guide documents nullable and multi-column ownership, heterogeneous
+  JSON values, runtime-keyed dictionaries, keyed HTTPS replacements, bounded identity
+  substitution, and their fail-closed boundaries.
+
+### Fixed
+
+- Source preparation now stores and reads each target's access receipt and owner-only
+  reader credential under its configured baseline artifact directory. Nested and
+  multi-target state roots no longer collide, and retirement refuses a receipt from a
+  different target root.
+- Supabase Storage source preparation now recursively traverses real folder placeholder
+  entries while keeping the approved prefix, path, depth, object-count, per-object, and
+  total-byte boundaries fail closed.
+- Approved-owner selection now rejects non-finite numeric values in every declared
+  owner column before choosing a privacy branch, including when another column already
+  matches the approved owner.
+- Pseudonymized canonical integer dictionary keys now share the same keyed identity
+  mapping as numeric columns and nested numeric values using the same namespace, so
+  runtime maps keep their reviewed cross-representation joins.
+- External-reader membership mismatches now return a redacted, actionable source
+  authorization refusal instead of an internal-failure diagnostic.
+- All external-reader privilege, expiration, readable-surface, and security-definer
+  denials now use the same `SOURCE_AUTHORIZATION_REFUSED` diagnostic and exit code 3.
+- Identity claims now sequence PostgreSQL reads on their single transaction client,
+  avoiding deprecated overlapping queries and remaining compatible with pg 9.
+
+## [0.1.0-beta.13] - 2026-10-05
+
 ### Added
 
 - Runtime and CI compatibility now cover maintained Node.js 22, 24, and 26 releases;

package/README.md

@@ -45,7 +45,9 @@ For an ordinary npm application install, Rehearsal safely creates a commented
 `rehearsal.config.mjs` in the project root, adds only its local-artifact entries to
 `.gitignore`, and prepares the isolated local runtime configuration. It detects the
 project name, database target, migration paths, commands, and free ports. Review lines
-marked `CHECK`, then open the guide. Existing files are never overwritten.
+marked `CHECK`, then open the guide. Existing files are never overwritten. If a supported
+root or nested config already exists, Rehearsal reports that active path and does not
+create a competing file; see [Configuration](docs/configuration.md#workspaces-and-custom-paths).
 
 If install scripts are disabled or the workspace root is ambiguous, installation makes
 no guess. Run `npx rehearsal` inside the application and choose **Set the stage** for the

package/docs/configuration.md

@@ -130,15 +130,20 @@ All paths resolve inside the consuming project. The artifact directory must be n
 `.rehearsal`; this is an intentional deletion guard. `runtimeWorkdir` must be its
 `runtime` child, and the generated application environment file must remain inside it.
 
-Rehearsal never overwrites this config. To start over, move the existing file somewhere
-safe, run setup again, and compare the two files before deleting either one.
-
+Rehearsal never overwrites this config. Do not move it merely to inspect a newer template.
 After upgrading, run `npx rehearsal init` to print the current release's generated
 template beside the path of your existing config. This comparison is read-only; adding a
 new optional key remains your decision. `npx rehearsal init --write` still refuses to
 replace an existing config. Rehearsal lists important optional settings that are
 available but not enabled before printing the template, so they are easier to find.
 
+If setup was interrupted after creating only some files, rerun
+`npx rehearsal setup --write`. It recreates missing generated files while preserving every
+existing config and local runtime file. When a config itself is invalid, keep it as a
+backup, generate a fresh file, and manually carry over only reviewed settings. See
+[Getting started](getting-started.md#if-setup-or-an-upgrade-is-interrupted) for the short
+recovery table.
+
 ### Workspaces and custom paths
 
 For an npm workspace, automatic creation proceeds only when exactly one application
@@ -151,8 +156,38 @@ checkout never receive project files.
 
 Supported existing config paths—including
 `infrastructure/rehearsal/rehearsal.config.mjs`—are preserved, and a second root config
-is not created. Use `--config=<project-relative-path>` for other explicit paths when
-running commands.
+is not created. The install hook reports the exact active path when npm displays lifecycle
+output, and setup always prints it. `npx rehearsal init --json` is the package-manager-
+independent way to check the `destination`. Rehearsal checks the supported root filenames
+first and then the supported nested filenames; finding any one of them prevents automatic
+creation of another. Use
+`--config=<project-relative-path>` for other explicit paths when running commands.
+
+### Move an existing config to the project root
+
+Relocation is deliberately manual because the config may contain reviewed settings and
+JavaScript imports. Rehearsal will never move it or create a competing root file.
+
+From the directory containing `package.json`:
+
+1. Stop active Rehearsal commands and confirm the current path with
+   `npx rehearsal init --json`.
+2. Make a backup outside every supported discovery path, such as
+   `.rehearsal/config-backups/rehearsal.config.mjs`.
+3. Move—do not copy—the active file to `./rehearsal.config.mjs`. Use `git mv` when it is
+   tracked so review history remains clear.
+4. Update relative JavaScript `import` specifiers inside the moved file. Imports resolve
+   from the config file's own folder, so a nested `../../something.mjs` import usually
+   changes after moving to the root.
+5. Leave config values such as `migrationDirectory`, `sanitizationPolicy`,
+   `runtimePolicy`, `identityPolicy`, and `dependentTargets[].configPath` unchanged unless
+   the referenced project file also moved. Rehearsal resolves those values from the
+   project root, not from the config file's folder.
+6. Run `npx rehearsal init --json`, confirm its `destination` is
+   `rehearsal.config.mjs`, then run `npx rehearsal doctor` and review the Git diff.
+
+If validation fails, restore the backup to its original path. Do not run setup while the
+move is half-finished; setup may correctly conclude that no supported config exists.
 
 `preparation.privacyKey` must stay inside `.rehearsal`; it is ignored and owner-readable
 only. Source, runtime, and identity policy files are declarations that may be reviewed in

package/docs/getting-started.md

@@ -48,6 +48,11 @@ especially:
 - the application start and proof commands;
 - the local ports.
 
+If a supported configuration already exists elsewhere—such as
+`infrastructure/rehearsal/rehearsal.config.mjs`—the installer reports that exact active
+path and does not generate a competing root file. Keep using it, or follow the explicit
+[root relocation guide](configuration.md#move-an-existing-config-to-the-project-root).
+
 If lifecycle scripts were disabled, a global/cache install was used, or a workspace has
 more than one possible application, no project files are created automatically. Run
 `npx rehearsal` inside the intended application, choose **Set the stage**, select
@@ -180,6 +185,29 @@ config during an upgrade. After upgrading, run `npx rehearsal init` to see impor
 optional settings you have not enabled and compare your file with the installed
 release's current template.
 
+### If setup or an upgrade is interrupted
+
+Do not delete `.rehearsal/` or your existing config. Start with:
+
+```bash
+npx rehearsal doctor
+npx rehearsal init
+```
+
+Use the reported problem to choose the smallest recovery:
+
+| Problem                             | Safe recovery                                                                                                                                                              |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A generated runtime file is missing | Run `npx rehearsal setup --write`. Existing files stay unchanged; only missing files are created.                                                                          |
+| A port is already in use            | Stop the conflicting local process or choose new dedicated ports, then rerun setup.                                                                                        |
+| The config is malformed             | Move it to a backup name, run `npx rehearsal setup --write`, then copy reviewed choices into the new file.                                                                 |
+| OAuth credentials are missing       | Create the ignored file named by `supabase.authentication.environmentFile`, add only the declared keys, and run `chmod 600` on it. Ambient shell credentials are not used. |
+| An npm upgrade fails                | Keep the existing config, baseline, and lockfile. Restore dependencies with your package manager, then run `npx rehearsal init` before retrying.                           |
+| Docker storage is low               | Run `npx rehearsal cleanup` for an exact preview. Rehearsal never performs a global Docker prune or silently removes volumes.                                              |
+
+`setup --write` and package installation never replace a config. If an existing file is
+invalid, Rehearsal fails closed and leaves it available for comparison.
+
 ## Files Rehearsal creates
 
 - `rehearsal.config.mjs` — reviewed project configuration

package/docs/production-source.md

@@ -23,6 +23,15 @@ The privacy key stays ignored under `.rehearsal`. The policy is safe to review i
 control because it contains hashes and environment-variable names, not credentials,
 URLs, or raw owner identifiers.
 
+`credentialFile` must be inside the selected target's
+`baseline.artifactDirectory`, under its `secrets` folder. With the default artifact
+directory, use `.rehearsal/secrets/source-reader.env`. For a target whose artifact
+directory is `targets/primary/.rehearsal`, use
+`targets/primary/.rehearsal/secrets/source-reader.env` and place `privacyKey` there as
+well. Rehearsal stores that target's access receipt beside its baseline at
+`targets/primary/.rehearsal/source-access-receipt.json`; separate targets never share
+the receipt or credential.
+
 ## 2. Declare the source boundary
 
 `source-access-policy.json` uses this shape:
@@ -112,6 +121,7 @@ an administrator credential or change the source:
   "reader": {
     "mode": "external",
     "role": "provided_rehearsal_reader",
+    "allowedMemberships": ["provided_rehearsal_readers"],
     "connectionEnvironmentVariable": "REHEARSAL_SOURCE_READER_URL",
     "credentialFile": ".rehearsal/secrets/source-reader.env",
     "maximumValidForMinutes": 30
@@ -153,9 +163,25 @@ view hash, columns, scopes, or reader declaration requires a new verification.
 
 External mode also requires all non-system readable columns to match only the declared
 views and migration-ledger columns. It refuses database, schema, relation, or column
-writes; inherited roles; privileged role attributes; executable non-system
-security-definer functions; a reader-owned view; or a database-enforced expiration
-beyond `maximumValidForMinutes`.
+writes; privileged role attributes; executable non-system security-definer functions;
+a reader-owned view; or a database-enforced expiration beyond
+`maximumValidForMinutes`.
+
+This audit is intentionally conservative: an object-level table, column, sequence, or
+function grant remains disallowed even when its schema currently lacks `USAGE`. Do not
+use schema visibility to hide stale grants. Revoke the object grant or move the approved
+surface behind the reviewed export views; this also avoids relying on behavior of an
+already-open or prepared database session.
+
+An external login may inherit its narrow permissions from provider-owned group roles.
+List every direct group in `allowedMemberships`; omit the field or use `[]` when the
+login has direct grants only. Rehearsal requires the observed membership set to match
+that list exactly. Every allowed group must be non-login and non-privileged, grant
+inheritance to the login, disable both `SET ROLE` and membership delegation, inherit no
+other role, and own none of the export views. PostgreSQL versions that cannot prove the
+per-membership role-switch setting are refused. Rehearsal still evaluates the login's
+complete effective read, write, sequence, and executable-function surface after those
+checks. Adding, removing, or changing a group changes the reviewed plan digest.
 
 `targetSchema` is optional and defaults to `public`. Set it when the restored relation
 belongs elsewhere, and use the same schema in privacy policy version 2. This is relation
@@ -167,6 +193,9 @@ non-identity prefix may use `prefix`. A private owner prefix uses
 the privacy policy below. Its raw value stays out of tracked files and the review plan
 records only its SHA-256. Objects outside the exact bucket/prefix are not listed or
 downloaded. Size, object-count, path, ETag, and exact-byte checks apply.
+Supabase folder entries are traversed recursively beneath that exact prefix. Folder
+entries count toward `maximumObjects`, so the same reviewed limit bounds both the
+directory walk and transferred files. Empty files remain files and are copied normally.
 
 ## 3. Use executable privacy policy version 2
 
@@ -227,10 +256,12 @@ Every selected column has one action and, where required, a bounded recipe:
 }
 ```
 
-Supported recipes are intentionally small: keyed UUID/email/text/integer pseudonyms,
-explicit constants, bounded or grouped date shifts, identity-aware path mappings, and
-fully classified JSON objects. Unknown tables, columns, JSON keys, formats, and recipes
-stop the refresh. There is no JavaScript or SQL escape hatch. See
+Supported recipes are intentionally small: keyed UUID/email/text/integer/hex/GTIN/URL
+pseudonyms, hexadecimal digests of explicitly named sanitized columns, explicit
+constants, bounded or grouped date shifts, identity-aware path mappings, bounded
+reviewed-identity substitution inside retained text, and fully classified JSON
+structures. Unknown tables, columns, digest inputs, JSON keys, formats, and recipes stop
+the refresh. There is no JavaScript or SQL escape hatch. See
 [Sanitization policy](sanitization.md) for complete path and date examples.
 
 ## 4. Preview, apply, refresh, and retire
@@ -290,6 +321,11 @@ limits access, and the provider may revoke it sooner. Rehearsal does not claim t
 cleanup revoked a provider-owned credential. Unrelated roles, grants, objects, baselines,
 runtimes, and Docker resources are preserved.
 
+Apply, refresh, and retire always resolve those local files from the active config's
+`baseline.artifactDirectory`. If you switch configs or target roots, Rehearsal refuses
+to retire a receipt from the other target. It also refuses an existing receipt or
+credential rather than overwriting or adopting it.
+
 ## Limits
 
 Rehearsal does not decide consent, licensing, retention rights, privileged-role meaning,

package/docs/releasing.md

@@ -32,9 +32,11 @@ publication must change and prove the workflow before narrowing that permission.
 1. Start from protected `main` on a dedicated ticketed release branch.
 2. Verify the exact version, changelog, compatibility notes, and packed file list.
 3. Run unit and contract tests, formatting, package-content and secret audits,
-   dependency audit, clean tarball installation, and the installed Docker fixture.
-4. Have a developer unfamiliar with the implementing project follow the clean-project
-   onboarding. Correct and retest the first confusing, missing, or wrong instruction.
+   dependency audit, packed onboarding, clean tarball installation, and the installed
+   Docker fixtures.
+4. When an unfamiliar developer is available, have them follow clean-project onboarding.
+   Correct and retest the first confusing, missing, or wrong instruction. Record when
+   this human observation was unavailable; automated checks must not impersonate it.
 5. Change `private` to `false` only in the reviewed release change.
 6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
    executable, declared runtime dependency inventory, and dependency audit result.

package/docs/roadmap.md

@@ -29,8 +29,9 @@ Track the full breakdown in
   invalid migrations, identities, images, persistence, reset, and cleanup.
 - Run the released package in the real reporting consumer and record positives and
   negatives.
-- Directly observe any claimed Google account-picker/callback and unfamiliar-developer
-  onboarding behavior; automation cannot invent that evidence.
+- Directly observe any claimed Google account-picker/callback. Record
+  unfamiliar-developer onboarding behavior when a tester is available; automation cannot
+  invent either kind of human evidence.
 - Remove consumer integration code only after its replacement passes and that deletion
   is separately approved.