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

package/dist/src/targets/supabase_environment.d.mts

@@ -0,0 +1,49 @@
+/**
+ * Purpose: Start and inspect local-only Supabase workdirs without inheriting hosted
+ * credentials. Do not run directly; this module is reusable script infrastructure.
+ */
+import { type ProcessEnvironment } from "../shared/process_environment.mjs";
+export interface LocalSupabaseEnvironment {
+    readonly apiUrl: string;
+    readonly databaseUrl: string;
+    readonly publishableKey: string;
+    readonly serviceRoleKey: string;
+    readonly studioUrl: string | undefined;
+    readonly databaseHost: string;
+    readonly databasePort: string;
+    readonly databaseName: string;
+    readonly databaseUser: string;
+    readonly databasePassword: string;
+}
+interface LocalCommandOptions {
+    readonly capture?: boolean;
+    readonly cwd?: string | undefined;
+    readonly input?: string | Uint8Array;
+    readonly environment?: ProcessEnvironment;
+    readonly maxBuffer?: number;
+}
+interface SupabaseCommandOptions {
+    readonly cwd?: string | undefined;
+    readonly workdir?: string | undefined;
+    readonly environment?: ProcessEnvironment;
+}
+export declare const parseSupabaseStatusEnvironment: (output: string) => Record<string, string>;
+export declare const parseLocalSupabaseEnvironment: (output: string) => LocalSupabaseEnvironment;
+export declare const runLocalCommand: (command: string, args: readonly string[], { capture, cwd, input, environment, maxBuffer, }?: LocalCommandOptions) => string;
+export declare const localCommandSucceeds: (command: string, args: readonly string[], { cwd, environment, }?: Pick<LocalCommandOptions, "cwd" | "environment">) => boolean;
+export declare const ensureLocalContainerRuntime: ({ cwd, autoStartColima, }?: {
+    cwd?: string | undefined;
+    autoStartColima?: boolean;
+}) => void;
+export declare const readLocalSupabaseEnvironment: ({ cwd, workdir, environment, }?: SupabaseCommandOptions) => LocalSupabaseEnvironment;
+export declare const startLocalSupabase: ({ cwd, workdir, exclude, environment, applyMigrations, autoStartColima, }?: SupabaseCommandOptions & {
+    exclude?: readonly string[];
+    applyMigrations?: boolean;
+    autoStartColima?: boolean;
+}) => LocalSupabaseEnvironment;
+export declare const stopLocalSupabase: ({ cwd, workdir, environment, }?: SupabaseCommandOptions) => void;
+export declare const removeLocalSupabaseProjectResources: ({ cwd, projectId, }?: {
+    cwd?: string;
+    projectId?: string;
+}) => void;
+export {};

package/dist/src/targets/supabase_environment.mjs

@@ -0,0 +1,162 @@
+/**
+ * Purpose: Start and inspect local-only Supabase workdirs without inheriting hosted
+ * credentials. Do not run directly; this module is reusable script infrastructure.
+ */
+import { spawnSync } from "node:child_process";
+import { createCleanProcessEnvironment, } from "../shared/process_environment.mjs";
+export const parseSupabaseStatusEnvironment = (output) => {
+    const values = {};
+    for (const line of output.split("\n")) {
+        const match = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/u);
+        if (!match)
+            continue;
+        const key = match[1];
+        const rawValue = match[2];
+        if (key === undefined || rawValue === undefined)
+            continue;
+        let value = rawValue.trim();
+        if (value.startsWith('"') && value.endsWith('"')) {
+            const parsed = JSON.parse(value);
+            if (typeof parsed !== "string")
+                continue;
+            value = parsed;
+        }
+        values[key] = value;
+    }
+    return values;
+};
+export const parseLocalSupabaseEnvironment = (output) => {
+    const values = parseSupabaseStatusEnvironment(output);
+    const required = (label, value) => {
+        if (!value)
+            throw new Error(`Local Supabase status omitted its ${label}.`);
+        return value;
+    };
+    const apiUrl = required("API URL", values.API_URL);
+    const databaseUrl = required("database URL", values.DB_URL);
+    const publishableKey = required("publishable key", values.PUBLISHABLE_KEY ?? values.ANON_KEY);
+    const serviceRoleKey = required("service-role key", values.SERVICE_ROLE_KEY ?? values.SECRET_KEY);
+    const api = new URL(apiUrl);
+    const database = new URL(databaseUrl);
+    const loopbackHosts = ["127.0.0.1", "::1", "localhost"];
+    if (!loopbackHosts.includes(api.hostname) ||
+        !loopbackHosts.includes(database.hostname) ||
+        !["postgres:", "postgresql:"].includes(database.protocol)) {
+        throw new Error("Refusing to use a non-local Supabase status target.");
+    }
+    const databaseName = decodeURIComponent(database.pathname.replace(/^\//u, ""));
+    if (!database.port ||
+        !databaseName ||
+        !database.username ||
+        !database.password) {
+        throw new Error("Local Supabase status returned an incomplete database URL.");
+    }
+    return {
+        apiUrl,
+        databaseUrl,
+        publishableKey,
+        serviceRoleKey,
+        studioUrl: values.STUDIO_URL,
+        databaseHost: database.hostname,
+        databasePort: database.port,
+        databaseName,
+        databaseUser: decodeURIComponent(database.username),
+        databasePassword: decodeURIComponent(database.password),
+    };
+};
+export const runLocalCommand = (command, args, { capture = false, cwd = process.cwd(), input, environment = {}, maxBuffer = 16 * 1024 * 1024, } = {}) => {
+    const shouldPipe = capture || input !== undefined;
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: "utf8",
+        env: createCleanProcessEnvironment({ overrides: environment }),
+        input,
+        maxBuffer,
+        stdio: shouldPipe ? ["pipe", "pipe", "pipe"] : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        const detail = [result.stdout, result.stderr]
+            .filter(Boolean)
+            .join("\n")
+            .trim();
+        throw new Error(`${command} ${args.join(" ")} failed${detail ? `:\n${detail}` : "."}`);
+    }
+    return result.stdout ?? "";
+};
+export const localCommandSucceeds = (command, args, { cwd = process.cwd(), environment = {}, } = {}) => spawnSync(command, args, {
+    cwd,
+    env: createCleanProcessEnvironment({ overrides: environment }),
+    stdio: "ignore",
+}).status === 0;
+export const ensureLocalContainerRuntime = ({ cwd = process.cwd(), autoStartColima = true, } = {}) => {
+    if (localCommandSucceeds("docker", ["info"], { cwd }))
+        return;
+    if (autoStartColima && localCommandSucceeds("colima", ["version"], { cwd })) {
+        runLocalCommand("colima", ["start"], { cwd });
+    }
+    if (!localCommandSucceeds("docker", ["info"], { cwd })) {
+        throw new Error("A local Docker-compatible runtime is required. Install Docker or Colima, then rerun the command.");
+    }
+};
+const withWorkdir = (args, workdir) => (workdir ? [...args, "--workdir", workdir] : [...args]);
+export const readLocalSupabaseEnvironment = ({ cwd, workdir, environment = {}, } = {}) => {
+    const output = runLocalCommand("supabase", withWorkdir(["status", "-o", "env"], workdir), { capture: true, cwd, environment });
+    return parseLocalSupabaseEnvironment(output);
+};
+export const startLocalSupabase = ({ cwd, workdir, exclude = [], environment = {}, applyMigrations = true, autoStartColima = true, } = {}) => {
+    ensureLocalContainerRuntime({ cwd, autoStartColima });
+    const startArguments = withWorkdir(["start", ...(exclude.length ? ["--exclude", exclude.join(",")] : [])], workdir);
+    runLocalCommand("supabase", startArguments, {
+        capture: true,
+        cwd,
+        environment,
+    });
+    if (applyMigrations) {
+        runLocalCommand("supabase", withWorkdir(["migration", "up", "--local"], workdir), { capture: true, cwd, environment });
+    }
+    return readLocalSupabaseEnvironment({ cwd, workdir, environment });
+};
+export const stopLocalSupabase = ({ cwd, workdir, environment = {}, } = {}) => {
+    if (!localCommandSucceeds("docker", ["info"], { cwd }))
+        return;
+    runLocalCommand("supabase", withWorkdir(["stop"], workdir), {
+        cwd,
+        environment,
+    });
+};
+export const removeLocalSupabaseProjectResources = ({ cwd = process.cwd(), projectId, } = {}) => {
+    if (!/^[a-z0-9][a-z0-9-]{1,62}$/u.test(projectId ?? "")) {
+        throw new Error("Refusing to remove local Supabase resources without an exact safe project id.");
+    }
+    const label = `com.supabase.cli.project=${projectId}`;
+    const list = (resource, format) => runLocalCommand("docker", [resource, "ls", "--filter", `label=${label}`, "--format", format], { capture: true, cwd })
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const containers = runLocalCommand("docker", ["ps", "--all", "--filter", `label=${label}`, "--format", "{{.ID}}"], { capture: true, cwd })
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (containers.length) {
+        runLocalCommand("docker", ["rm", "--force", ...containers], {
+            capture: true,
+            cwd,
+        });
+    }
+    const volumes = list("volume", "{{.Name}}");
+    if (volumes.length) {
+        runLocalCommand("docker", ["volume", "rm", "--force", ...volumes], {
+            capture: true,
+            cwd,
+        });
+    }
+    const networks = list("network", "{{.ID}}");
+    if (networks.length) {
+        runLocalCommand("docker", ["network", "rm", ...networks], {
+            capture: true,
+            cwd,
+        });
+    }
+};

package/dist/src/targets/target.d.mts

@@ -0,0 +1,33 @@
+/**
+ * Purpose: Define the small, closed set of database runtimes Rehearsal can select.
+ * Runtime implementations stay behind this boundary so the shared CLI does not
+ * need target-specific branches.
+ */
+declare const TARGETS: Readonly<{
+    supabase: Readonly<{
+        id: "supabase";
+        label: "Supabase";
+    }>;
+    postgresql: Readonly<{
+        id: "postgresql";
+        label: "PostgreSQL";
+    }>;
+}>;
+export type RehearsalRuntimeTargetId = keyof typeof TARGETS;
+export type RehearsalRuntimeTarget = (typeof TARGETS)[RehearsalRuntimeTargetId];
+export interface RuntimeInvocation {
+    readonly action: string;
+    readonly configPath: string | undefined;
+    readonly confirmation: string | undefined;
+}
+export interface RuntimeManagerArguments {
+    managerPath: string;
+    action: string;
+    configPath?: string;
+    confirmation?: string;
+}
+export declare const REHEARSAL_RUNTIME_TARGETS: readonly ("postgresql" | "supabase")[];
+export declare const parseRuntimeInvocation: (arguments_?: readonly string[]) => RuntimeInvocation;
+export declare const buildRuntimeManagerArguments: ({ managerPath, action, configPath, confirmation, }: RuntimeManagerArguments) => string[];
+export declare const resolveRuntimeTarget: (value?: unknown) => RehearsalRuntimeTarget;
+export {};

package/dist/src/targets/target.mjs

@@ -0,0 +1,39 @@
+/**
+ * Purpose: Define the small, closed set of database runtimes Rehearsal can select.
+ * Runtime implementations stay behind this boundary so the shared CLI does not
+ * need target-specific branches.
+ */
+const TARGETS = Object.freeze({
+    supabase: Object.freeze({
+        id: "supabase",
+        label: "Supabase",
+    }),
+    postgresql: Object.freeze({
+        id: "postgresql",
+        label: "PostgreSQL",
+    }),
+});
+export const REHEARSAL_RUNTIME_TARGETS = Object.freeze(Object.keys(TARGETS));
+export const parseRuntimeInvocation = (arguments_ = process.argv.slice(2)) => {
+    const action = arguments_.find((argument) => !argument.startsWith("--"));
+    const valueAfter = (prefix) => arguments_
+        .find((argument) => argument.startsWith(prefix))
+        ?.slice(prefix.length);
+    return Object.freeze({
+        action: action ?? "status",
+        configPath: valueAfter("--config="),
+        confirmation: valueAfter("--confirm-candidates="),
+    });
+};
+export const buildRuntimeManagerArguments = ({ managerPath, action, configPath, confirmation, }) => [
+    managerPath,
+    action,
+    ...(configPath ? [`--config=${configPath}`] : []),
+    ...(confirmation ? [`--confirm-candidates=${confirmation}`] : []),
+];
+export const resolveRuntimeTarget = (value = "supabase") => {
+    if (typeof value !== "string" || !Object.hasOwn(TARGETS, value)) {
+        throw new Error(`Unsupported Rehearsal runtime target: ${String(value)}. Supported targets: ${REHEARSAL_RUNTIME_TARGETS.join(", ")}.`);
+    }
+    return TARGETS[value];
+};

package/docs/README.md

@@ -24,6 +24,7 @@ want to accomplish and follow that path.
 
 - [CLI commands](commands.md)
 - [Configuration](configuration.md)
+- [TypeScript](typescript.md)
 - [Runtime and identity policies](runtime-policies.md)
 - [Database adapters](adapters.md)
 - [Glossary](glossary.md)

package/docs/architecture.md

@@ -5,7 +5,7 @@ documentation so each file has one obvious home.
 
 ```text
 rehearsal-db/
-├── src/                    shipped package code
+├── src/                    TypeScript product source
 │   ├── application/       application lifecycle and HTTP proofs
 │   ├── baseline/          sanitized baseline creation and validation
 │   ├── cli/               the `rehearsal` executable
@@ -16,8 +16,12 @@ rehearsal-db/
 │   ├── source/            approved source access and refresh
 │   └── targets/           PostgreSQL and Supabase adapters
 ├── scripts/
-│   ├── runtime/           shipped internal runtime launcher
+│   ├── build/             clean TypeScript compilation helpers
+│   ├── install/           TypeScript install-hook source
+│   ├── runtime/           TypeScript runtime-launcher source
 │   └── verification/      repository-only package and fixture proofs
+├── dist/                   generated ESM and declaration output; never edit directly
+├── types/                  reviewed public root declaration contract
 ├── tests/
 │   ├── unit/              mirrors the `src/` domains
 │   ├── integration/       multi-module and terminal behavior
@@ -29,6 +33,7 @@ rehearsal-db/
 ## Boundaries
 
 - `src/` must never import from tests or repository-only verification scripts.
+- `dist/` is rebuilt from TypeScript before tests and packaging; never hand-edit it.
 - Database-specific lifecycle behavior belongs in `src/targets/`.
 - `scripts/verification/` is never included in the npm package.
 - Public consumers use only the paths declared in `package.json#exports`.
@@ -40,13 +45,13 @@ rehearsal-db/
 The executable is split by responsibility so no command file becomes a second
 application layer:
 
-- `rehearsal.mjs` starts the process and dispatches commands.
-- `arguments.mjs` owns the command-line contract and mutation classification.
-- `guided.mjs` owns the interactive home screen and first-run questions.
-- `runtime_commands.mjs` coordinates local runtimes and project proofs.
-- `source_commands.mjs` coordinates approved source access and refresh.
-- `renderers.mjs` formats human-readable results without changing state.
-- `terminal.mjs` owns prompts, colors, and terminal exit behavior.
+- `rehearsal.mts` starts the process and dispatches commands.
+- `arguments.mts` owns the command-line contract and mutation classification.
+- `guided.mts` owns the interactive home screen and first-run questions.
+- `runtime_commands.mts` coordinates local runtimes and project proofs.
+- `source_commands.mts` coordinates approved source access and refresh.
+- `renderers.mts` formats human-readable results without changing state.
+- `terminal.mts` owns prompts, colors, and terminal exit behavior.
 
 ## Adding something new
 
@@ -56,3 +61,6 @@ application layer:
 4. Add an integration or contract test only when behavior crosses domains or becomes a
    public promise.
 5. Update the documentation map when adding a new guide.
+
+Run `npm run build` after changing TypeScript source. Tests import the generated package
+code so the same JavaScript boundary consumers install is exercised locally.

package/docs/configuration.md

@@ -25,6 +25,11 @@ Use this page when changing the generated file. The schema is strict: misspelled
 unknown fields, and unsupported versions are errors. The `.mjs` extension works in both
 CommonJS and ESM projects.
 
+The generated file also receives editor and compiler checking through the package's
+public TypeScript declarations. See [TypeScript](typescript.md) for the supported type
+surface and checked examples. Keep the runnable configuration as `.mjs`; a project does
+not need to rename it to `.ts`.
+
 ```ts
 // @ts-check
 import { defineRehearsalConfig } from "@rehearsal-db/core";
@@ -130,15 +135,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 +161,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
@@ -431,9 +471,10 @@ may use these explicit subpaths:
 - `@rehearsal-db/core/service-environment`
 - `@rehearsal-db/core/source-access`
 
-These advanced entry points are ESM JavaScript APIs in the first beta. The root
-configuration and sanitization API has TypeScript declarations; the advanced subpaths do
-not yet promise a typed surface.
+These advanced entry points ship as ordinary ESM JavaScript with generated TypeScript
+declarations. The root configuration and sanitization contract remains the explicitly
+reviewed public type surface. The exact current boundary is documented in
+[TypeScript](typescript.md).
 
 Undocumented files under `scripts/` are package internals and are not compatibility
 contracts.

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/index.md

@@ -11,6 +11,7 @@ you want, then follow the links when a term or safety check is new.
 | Try Rehearsal without touching my app | [Hands-on tutorial](tutorial.md)                                  |
 | Understand what makes a copy safe     | [Baselines](baselines.md) and [Sanitization](sanitization.md)     |
 | Look up a command or setting          | [CLI commands](commands.md) and [Configuration](configuration.md) |
+| Add editor and compiler type checks   | [TypeScript](typescript.md)                                       |
 | Fix something that did not work       | [Troubleshooting](troubleshooting.md)                             |
 
 ## The short version

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.