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

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/                  compatibility entry point for generated declarations
 ├── 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`.
@@ -38,15 +43,130 @@ rehearsal-db/
 ## CLI modules
 
 The executable is split by responsibility so no command file becomes a second
-application layer:
+application layer. Scripted commands and the interactive guide resolve through the same
+typed registry and produce the same result contract:
 
-- `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` owns process lifecycle, project locking, guided-loop coordination, and
+  top-level error handling. It does not implement commands.
+- `arguments.mts` owns the command-line contract and mutation classification.
+- `command_contract.mts`, `command_registry.mts`, and `command_output.mts` define command
+  context, handler selection, stable JSON envelopes, human rendering, and exit codes.
+- `*_command_handlers.mts` and `runtime_action_handlers.mts` group handlers by project,
+  source, identity, inspection, application, or runtime responsibility.
+- `cli_commands.mts` composes those focused families in precedence order without
+  implementing their behavior.
+- `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.
+
+Command handlers receive an explicit context containing parsed flags, selected config,
+guided state, and session-local caches. They return a rendered, text, or silent result;
+only the shared output boundary creates JSON envelopes or writes final human output.
+Session caches never appear in the public parsed-flags type.
+
+Repository contracts keep the process entry point at 300 lines or fewer and every
+handler-family module at 350 lines or fewer. A new command belongs in the narrowest
+existing family, or in a new focused family when it represents a genuinely separate
+responsibility.
+
+## Configuration pipeline
+
+The stable `project/configuration.mts` facade keeps existing imports compatible while
+configuration work moves through explicit phases:
+
+1. `configuration_discovery.mts` selects one supported project-owned config path.
+2. `configuration_schema.mts` validates the raw object shape and rejects unknown keys.
+3. `configuration_normalization.mts` applies defaults and semantic safety constraints.
+4. `configuration_resolution.mts` resolves owned paths from the project root and checks
+   destructive-operation boundaries.
+
+The public contract/defaults, primitive validators, project detection, and starter
+rendering have their own focused modules. `NormalizedRehearsalConfig` is inferred from
+the normalizer, while the package's public declarations are emitted from the same
+TypeScript implementation. Repository contracts keep the facade at 50 lines or fewer
+and each configuration phase at 700 lines or fewer.
+
+## Installed-consumer verification
+
+Repository verification installs the package tarball into disposable projects; it must
+not import unpublished product source by accident. One scenario catalog drives both the
+individual fixture commands and `npm run release:verify`.
+
+- `scenarios/artifact.mjs` selects or packs one tarball, reads its package identity, and
+  records its SHA-256 before installation.
+- `scenarios/workspace.mjs` creates and removes only scenario-owned scratch roots.
+- `scenarios/process.mjs` starts commands with inherited credentials removed unless a
+  scenario explicitly supplies a safe value.
+- `scenarios/application_session.mjs` owns persistent application and terminal-session
+  checks.
+- `scenarios/catalog.mjs` is the sole ordered list of installed-consumer scenarios.
+- Fixture files contain only the target setup and assertions unique to that scenario.
+
+Each scenario remains independently runnable through its `test:fixture:*` script. The
+complete release gate runs every catalog entry against the same immutable tarball and
+writes its version, SHA-256, tool environment, commands, timings, and results under
+`test-results/release-gate/`.
+
+## Runtime lifecycle
+
+`runtime/lifecycle_engine.mts` owns the target-neutral lifecycle contract. Both
+PostgreSQL and Supabase use it to dispatch commands, verify active baseline inputs,
+calculate and confirm the exact migration set, write target-bound receipts, validate
+runtime markers, and roll back a failed reset or migration without hiding the original
+failure.
+
+The files in `src/targets/` remain drivers. They prove ownership before deleting local
+resources and implement only the behavior that genuinely differs: Docker PostgreSQL
+containers and SQL setup on one side; Supabase CLI, Auth, Storage, and generated config
+on the other. An ordinary `stop` never enters rollback or discard, so later `start`
+preserves the sandbox database and Storage contents.
+
+Repository contracts keep each target driver at 900 lines or fewer and the shared
+lifecycle engine at 300 lines or fewer. A new database target must use this lifecycle
+boundary rather than copying an existing driver's orchestration.
+
+## Identity claim pipeline
+
+The stable `identity/claim.mts` facade exposes policy validation, deterministic planning,
+and confirmed execution while keeping those responsibilities separate:
+
+1. `claim_contract.mts` defines the normalized policy, plan, database, and receipt types.
+2. `claim_policy.mts` validates and normalizes the reviewed declaration.
+3. `claim_plan.mts` binds the local matcher value to an immutable redacted review and
+   digest without opening a database or Storage connection.
+4. `claim_sql.mts` generates identifier-safe relational, JSON, signup-default, and path
+   SQL without executing it.
+5. `claim_identity_lookup.mts` performs read-only local Auth and reference discovery.
+6. `claim_verification.mts` checks signup defaults and token-hook claim shapes.
+7. `claim_executor.mts` alone owns the database transaction, Storage staging, rollback,
+   commit, old-object cleanup, and final receipt.
+
+Repository contracts keep the facade at 50 lines or fewer and every identity-claim
+stage at 600 lines or fewer. Provider callbacks and consumer application behavior stay
+outside this pipeline.
+
+## Privacy rule pipeline
+
+The stable `baseline/privacy_engine.mts` facade preserves the documented privacy import
+path while policy work is divided into fail-closed typed stages:
+
+1. `privacy_contract.mts` defines normalized policy and execution types.
+2. `privacy_recipe_validation.mts` normalizes only reviewed rule shapes;
+   `privacy_policy.mts` validates complete policy structure.
+3. `privacy_dependency_graph.mts` checks owner bindings, path mappings, sanitized digest
+   inputs, cycles, and shared date groups.
+4. `privacy_transforms.mts` implements deterministic pseudonyms and bounded paths.
+5. `privacy_rule_registry.mts` explicitly registers every action and derivation kind;
+   unknown kinds have no fallback execution path.
+6. `privacy_structured_json.mts` owns bounded object, array, union, and dictionary rules.
+7. `privacy_pipeline.mts` resolves reviewed bindings and executes rows, while
+   `privacy_key.mts` owns the local secret-file boundary.
+
+Repository contracts keep the facade at 50 lines or fewer and every privacy stage at
+700 lines or fewer. Adding a rule requires its normalized type, validator, registered
+handler, focused boundary tests, and documentation—without widening policy version 2.
 
 ## Adding something new
 
@@ -56,3 +176,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";
@@ -466,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/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/releasing.md

@@ -31,9 +31,10 @@ 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, packed onboarding, clean tarball installation, and the installed
-   Docker fixtures.
+3. Run `npm run release:verify`. It performs the package checks and every
+   installed-consumer scenario against one tarball, then records the exact package
+   version, SHA-256, environment, commands, timings, and results in
+   `test-results/release-gate/`. Run the dependency audit separately.
 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.
@@ -53,6 +54,10 @@ publication must change and prove the workflow before narrowing that permission.
 11. Replace consuming projects' temporary Git/archive references only on their own
     protected integration branches and rerun their complete verification.
 
+The independent Rehearsal Test Lab is the primary pre-release consumer environment.
+Real product integrations provide additional compatibility evidence; they do not
+replace the package-owned release gate or Test Lab.
+
 The workflow publishes prereleases under the `beta` dist-tag and refuses a stable
 version. While Rehearsal has no stable release, the workflow also moves `latest` to the
 same reviewed beta. This keeps the npm package page and the ordinary

package/docs/typescript.md

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