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

package/dist/src/runtime/restore.mjs

@@ -0,0 +1,276 @@
+/**
+ * Purpose: Build the bounded PostgreSQL restore program for a verified sanitized
+ * Rehearsal baseline. Do not run directly; this module is reusable script infrastructure.
+ */
+import { createHash } from "node:crypto";
+const identifierPattern = /^[a-z][a-z0-9_]{0,62}$/u;
+const constraintFailurePattern = /^ERROR:\s+(?:[A-Z0-9]{5}:\s+)?new row for relation "([a-z][a-z0-9_]*)" violates check constraint "([a-z][a-z0-9_]*)"$/mu;
+const sqlStatePattern = /^ERROR:\s+([A-Z0-9]{5}):/mu;
+const notNullFailurePattern = /^ERROR:\s+(?:23502:\s+)?null value in column "([a-z][a-z0-9_]*)" of relation "([a-z][a-z0-9_]*)" violates not-null constraint$/mu;
+const quoteIdentifier = (value) => {
+    if (!identifierPattern.test(value)) {
+        throw new Error(`Unsafe Rehearsal restore identifier: ${value}`);
+    }
+    return `"${value}"`;
+};
+const quoteLiteral = (value) => `'${value.replaceAll("'", "''")}'`;
+const tableSchema = (table) => table.schema ?? "public";
+const relationKey = (schema, table) => schema === "public" ? table : `${schema}.${table}`;
+const qualifiedRelation = (table) => `${quoteIdentifier(tableSchema(table))}.${quoteIdentifier(table.name)}`;
+const includedPolicies = (manifest) => manifest.tables
+    .filter((table) => table.sourceRows !== "EXCLUDE")
+    .sort((left, right) => left.name.localeCompare(right.name));
+export const summarizeRestoreError = (stderr) => {
+    const match = String(stderr).match(constraintFailurePattern);
+    if (match)
+        return `Sanitized data violated ${match[1]}.${match[2]}.`;
+    const notNull = String(stderr).match(notNullFailurePattern);
+    if (notNull) {
+        return `Sanitized data omitted required column ${notNull[2]}.${notNull[1]}.`;
+    }
+    const sqlState = String(stderr).match(sqlStatePattern)?.[1];
+    return sqlState
+        ? `PostgreSQL rejected the sanitized baseline stream with SQLSTATE ${sqlState}; row details were withheld.`
+        : "PostgreSQL rejected the sanitized baseline stream; row details were withheld.";
+};
+export const encodeBaselineRecordForCopy = (line) => {
+    let record;
+    try {
+        record = JSON.parse(line.trimEnd());
+    }
+    catch (error) {
+        throw new Error("A Rehearsal baseline record is not valid JSON.", {
+            cause: error,
+        });
+    }
+    if ((record?.schema !== undefined && !identifierPattern.test(record.schema)) ||
+        !identifierPattern.test(record?.table ?? "") ||
+        !record.row ||
+        typeof record.row !== "object" ||
+        Array.isArray(record.row)) {
+        throw new Error("A Rehearsal baseline record has an invalid restore shape.");
+    }
+    return `${record.schema ?? "public"}\t${record.table}\t${Buffer.from(JSON.stringify(record.row), "utf8").toString("base64")}`;
+};
+export const buildRestoreSqlPrefix = () => `\\set ON_ERROR_STOP on
+\\set VERBOSITY verbose
+begin;
+set local session_replication_role = replica;
+create temporary table rehearsal_restore_rows (
+	sequence bigint generated always as identity primary key,
+	schema_name text not null,
+	table_name text not null,
+	encoded text not null
+) on commit drop;
+copy rehearsal_restore_rows (schema_name, table_name, encoded) from stdin;
+`;
+const decodedPayloadSql = "convert_from(decode(source.encoded, 'base64'), 'UTF8')::jsonb";
+const authReferenceSelects = (manifest) => includedPolicies(manifest).flatMap((table) => table.columns
+    .filter((column) => column.action !== "EXCLUDE" &&
+    column.foreignKey?.schema === "auth" &&
+    column.foreignKey?.table === "users" &&
+    column.foreignKey?.column === "id")
+    .map((column) => `select nullif(${decodedPayloadSql}->>${quoteLiteral(column.name)}, '')::uuid as id
+	from rehearsal_restore_rows source
+	where source.schema_name = ${quoteLiteral(tableSchema(table))}
+	  and source.table_name = ${quoteLiteral(table.name)}`));
+const buildAuthRestoreSql = (manifest) => {
+    const selects = authReferenceSelects(manifest);
+    if (selects.length === 0)
+        return "";
+    return `with referenced_auth_users as (
+	${selects.join("\n\tunion\n\t")}
+)
+insert into auth.users (
+	instance_id,
+	id,
+	aud,
+	role,
+	email,
+	confirmation_token,
+	recovery_token,
+	email_change_token_new,
+	email_change,
+	email_change_token_current,
+	phone_change,
+	phone_change_token,
+	reauthentication_token,
+	raw_app_meta_data,
+	raw_user_meta_data,
+	is_sso_user,
+	is_anonymous,
+	created_at,
+	updated_at
+)
+select distinct
+	'00000000-0000-0000-0000-000000000000'::uuid,
+	id,
+	'authenticated',
+	'authenticated',
+	'rehearsal-' || replace(id::text, '-', '') || '@rehearsal.invalid',
+	'',
+	'',
+	'',
+	'',
+	'',
+	'',
+	'',
+	'',
+	'{"provider":"email","providers":["email"]}'::jsonb,
+	'{"rehearsal":true}'::jsonb,
+	false,
+	false,
+	now(),
+	now()
+from referenced_auth_users
+where id is not null
+on conflict (id) do nothing;
+`;
+};
+const buildTableRestoreSql = (table) => {
+    const target = qualifiedRelation(table);
+    const columns = table.columns.filter((column) => column.action !== "EXCLUDE" && column.generated !== "ALWAYS");
+    if (columns.length === 0)
+        return "";
+    const columnList = columns
+        .map((column) => quoteIdentifier(column.name))
+        .join(", ");
+    const selectedColumns = columns
+        .map((column) => `restored.${quoteIdentifier(column.name)}`)
+        .join(", ");
+    const overridesIdentity = columns.some((column) => column.identity === "YES")
+        ? " overriding system value"
+        : "";
+    return `insert into ${target} (${columnList})${overridesIdentity}
+select ${selectedColumns}
+from rehearsal_restore_rows source
+cross join lateral jsonb_populate_record(
+	null::${target},
+	${decodedPayloadSql}
+) restored
+where source.schema_name = ${quoteLiteral(tableSchema(table))}
+  and source.table_name = ${quoteLiteral(table.name)}
+order by source.sequence;
+`;
+};
+const buildIdentitySequenceSql = (table) => table.columns
+    .filter((column) => column.action !== "EXCLUDE" &&
+    column.identity === "YES" &&
+    column.generated !== "ALWAYS")
+    .map((column) => {
+    const schema = tableSchema(table);
+    const relation = qualifiedRelation(table);
+    const columnName = quoteIdentifier(column.name);
+    const sequenceValueQuery = `select max(${columnName})::bigint, exists(select 1 from ${relation}) from ${relation}`;
+    return `do $rehearsal_sequence$
+declare
+	sequence_name text := pg_get_serial_sequence(${quoteLiteral(`${schema}.${table.name}`)}, ${quoteLiteral(column.name)});
+	maximum_value bigint;
+	has_rows boolean;
+begin
+	if sequence_name is not null then
+		execute ${quoteLiteral(sequenceValueQuery)} into maximum_value, has_rows;
+		perform setval(sequence_name, coalesce(maximum_value, 1), has_rows);
+	end if;
+end
+$rehearsal_sequence$;`;
+})
+    .join("\n");
+const buildRowCountChecks = (tables, tableCounts) => tables
+    .map((table) => ({
+    table,
+    key: relationKey(tableSchema(table), table.name),
+    expected: tableCounts[relationKey(tableSchema(table), table.name)],
+}))
+    .sort((left, right) => left.key.localeCompare(right.key))
+    .map(({ table, key, expected }) => {
+    if (typeof expected !== "number" ||
+        !Number.isSafeInteger(expected) ||
+        expected < 0) {
+        throw new Error(`Invalid Rehearsal row count for ${key}.`);
+    }
+    return `if (select count(*) from ${qualifiedRelation(table)}) <> ${expected} then
+		raise exception 'Rehearsal row-count mismatch for ${key}';
+	end if;`;
+})
+    .join("\n\t");
+const buildForeignKeyChecks = (manifest) => includedPolicies(manifest)
+    .flatMap((table) => table.columns.flatMap((column) => column.action !== "EXCLUDE" && column.foreignKey
+    ? [{ table, column, target: column.foreignKey }]
+    : []))
+    .map(({ table, column, target }) => {
+    for (const value of [
+        table.name,
+        column.name,
+        tableSchema(table),
+        target.schema,
+        target.table,
+        target.column,
+    ])
+        quoteIdentifier(value);
+    return `if exists (
+		select 1
+		from ${qualifiedRelation(table)} child
+		left join ${quoteIdentifier(target.schema)}.${quoteIdentifier(target.table)} parent
+			on parent.${quoteIdentifier(target.column)} = child.${quoteIdentifier(column.name)}
+		where child.${quoteIdentifier(column.name)} is not null
+			and parent.${quoteIdentifier(target.column)} is null
+	) then
+		raise exception 'Rehearsal foreign-key mismatch for ${relationKey(tableSchema(table), table.name)}.${column.name}';
+	end if;`;
+})
+    .join("\n\t");
+export const buildRestoreSqlSuffix = ({ manifest, tableCounts, restoreSupabaseAuth = true, }) => {
+    if (!Array.isArray(manifest?.tables) || !tableCounts) {
+        throw new Error("A reviewed manifest and exact row counts are required.");
+    }
+    const tables = includedPolicies(manifest);
+    const expectedNames = tables
+        .map((table) => relationKey(tableSchema(table), table.name))
+        .sort();
+    if (expectedNames.join("\0") !== Object.keys(tableCounts).sort().join("\0")) {
+        throw new Error("Rehearsal restore table counts do not match the policy.");
+    }
+    return `\\.
+create index rehearsal_restore_rows_table_name_idx
+on rehearsal_restore_rows (schema_name, table_name, sequence);
+truncate table ${manifest.tables.map(qualifiedRelation).join(", ")}
+restart identity cascade;
+${restoreSupabaseAuth ? buildAuthRestoreSql(manifest) : ""}
+${tables.map(buildTableRestoreSql).join("\n")}
+${tables.map(buildIdentitySequenceSql).filter(Boolean).join("\n")}
+set local session_replication_role = origin;
+do $rehearsal_checks$
+begin
+	${buildRowCountChecks(tables, tableCounts)}
+	${buildForeignKeyChecks(manifest)}
+end
+$rehearsal_checks$;
+commit;
+`;
+};
+export const createCandidateMigrationReceipt = ({ baselineManifest, currentFiles, }) => {
+    const baselineEntries = Object.entries(baselineManifest?.migrations ?? {}).sort(([left], [right]) => left.localeCompare(right));
+    if (baselineEntries.length === 0) {
+        throw new Error("The active Rehearsal baseline has no migration bundle.");
+    }
+    if (baselineEntries.length > currentFiles.length) {
+        throw new Error("The active Rehearsal history is absent from local source.");
+    }
+    for (let index = 0; index < baselineEntries.length; index += 1) {
+        const [filename, receipt] = baselineEntries[index];
+        const current = currentFiles[index];
+        if (current.filename !== filename ||
+            current.fileSha256 !== receipt.sha256) {
+            throw new Error(`Local migration history diverges from the active baseline at ${filename}.`);
+        }
+    }
+    const candidates = currentFiles.slice(baselineEntries.length);
+    const candidateSha256 = createHash("sha256")
+        .update(`${JSON.stringify(candidates.map(({ filename, fileSha256 }) => ({
+        filename,
+        fileSha256,
+    })), null, "\t")}\n`)
+        .digest("hex");
+    return { candidates, candidateSha256 };
+};

package/dist/src/runtime/service_environment.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Purpose: Load an exact, project-owned allowlist of local service credentials
+ * without exposing values or inheriting ambient hosted credentials.
+ * Do not run directly; this module is reusable Rehearsal infrastructure.
+ */
+export interface RehearsalServiceEnvironmentOptions {
+    path?: string | null;
+    keys?: readonly string[];
+    blockedKeys?: readonly string[];
+}
+export declare const readRehearsalServiceEnvironment: ({ path, keys, blockedKeys, }: RehearsalServiceEnvironmentOptions) => Promise<Record<string, string>>;

package/dist/src/runtime/service_environment.mjs

@@ -0,0 +1,58 @@
+/**
+ * Purpose: Load an exact, project-owned allowlist of local service credentials
+ * without exposing values or inheriting ambient hosted credentials.
+ * Do not run directly; this module is reusable Rehearsal infrastructure.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { parseEnv } from "node:util";
+const ENVIRONMENT_KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/u;
+const hasErrorCode = (error, code) => typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === code;
+export const readRehearsalServiceEnvironment = async ({ path, keys = [], blockedKeys = [], }) => {
+    if (!path) {
+        if (keys.length) {
+            throw new Error("Rehearsal service environment keys require an owned environment file.");
+        }
+        return {};
+    }
+    if (!keys.length) {
+        throw new Error("A Rehearsal service environment file requires an exact variable allowlist.");
+    }
+    for (const key of keys) {
+        if (!ENVIRONMENT_KEY_PATTERN.test(key)) {
+            throw new Error(`Invalid Rehearsal service environment key: ${key}.`);
+        }
+        if (blockedKeys.includes(key)) {
+            throw new Error(`Rehearsal service environment key ${key} is blocked by the safety policy.`);
+        }
+    }
+    let source;
+    let details;
+    try {
+        [details, source] = await Promise.all([stat(path), readFile(path, "utf8")]);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            throw new Error(`Rehearsal service environment file is missing: ${path}.`, { cause: error });
+        }
+        throw error;
+    }
+    if (!details.isFile()) {
+        throw new Error(`Rehearsal service environment path is not a file: ${path}.`);
+    }
+    if ((details.mode & 0o077) !== 0) {
+        throw new Error("Rehearsal service environment credentials must be owner-only (chmod 600).");
+    }
+    const parsed = parseEnv(source);
+    const unexpectedKeys = Object.keys(parsed).filter((key) => !keys.includes(key));
+    if (unexpectedKeys.length) {
+        throw new Error(`Rehearsal service environment contains variables outside its allowlist: ${unexpectedKeys.join(", ")}.`);
+    }
+    const missingKeys = keys.filter((key) => !parsed[key]?.trim());
+    if (missingKeys.length) {
+        throw new Error(`Rehearsal service environment is missing required variables: ${missingKeys.join(", ")}.`);
+    }
+    return Object.fromEntries(keys.map((key) => [key, parsed[key]]));
+};

package/dist/src/runtime/topology.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Purpose: Resolve and validate a primary Rehearsal runtime plus any explicitly
+ * declared dependent runtimes. Every target remains a complete, independently
+ * safe Rehearsal configuration.
+ */
+import { loadRehearsalConfig } from "../project/configuration.mjs";
+import { inspectRehearsalMigrations } from "./plan.mjs";
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+export type LoadedRehearsalConfig = Awaited<ReturnType<typeof loadRehearsalConfig>>;
+export type DependentDeclaration = LoadedRehearsalConfig["config"]["dependentTargets"][number];
+export interface RuntimeTopologyTarget {
+    readonly name: string;
+    readonly primary: boolean;
+    readonly declaration: DependentDeclaration | null;
+    readonly configPath: string;
+    readonly config: LoadedRehearsalConfig["config"];
+    readonly paths: LoadedRehearsalConfig["paths"];
+}
+export declare const loadRuntimeTopology: (options?: RehearsalConfigPathOptions) => Promise<Readonly<{
+    projectRoot: string;
+    primary: RuntimeTopologyTarget;
+    dependents: readonly RuntimeTopologyTarget[];
+    targets: readonly RuntimeTopologyTarget[];
+}>>;
+type MigrationInspection = Awaited<ReturnType<typeof inspectRehearsalMigrations>>;
+declare const candidateSummary: (inspection: MigrationInspection) => Readonly<{
+    baselineGenerationId: string;
+    candidateSha256: string;
+    candidateCount: number;
+    candidates: readonly {
+        version: string;
+        name: string;
+        filename: string;
+        sha256: string;
+        status: string;
+    }[];
+}>;
+export declare const inspectRuntimeTopologyCandidates: (options?: RehearsalConfigPathOptions) => Promise<Readonly<{
+    topology: Readonly<{
+        projectRoot: string;
+        primary: RuntimeTopologyTarget;
+        dependents: readonly RuntimeTopologyTarget[];
+        targets: readonly RuntimeTopologyTarget[];
+    }>;
+    targets: readonly (RuntimeTopologyTarget & {
+        summary: ReturnType<typeof candidateSummary>;
+    })[];
+    candidateSha256: string;
+    candidateCount: number;
+}>>;
+export {};

package/dist/src/runtime/topology.mjs

@@ -0,0 +1,128 @@
+/**
+ * Purpose: Resolve and validate a primary Rehearsal runtime plus any explicitly
+ * declared dependent runtimes. Every target remains a complete, independently
+ * safe Rehearsal configuration.
+ */
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, resolve } from "node:path";
+import { loadRehearsalConfig } from "../project/configuration.mjs";
+import { inspectRehearsalMigrations } from "./plan.mjs";
+const isInside = (parent, candidate) => {
+    const path = relative(parent, candidate);
+    return !path || (!path.startsWith("..") && !isAbsolute(path));
+};
+const assertUnique = (entries, valueFor, label) => {
+    const seen = new Map();
+    for (const entry of entries) {
+        const value = valueFor(entry);
+        if (seen.has(value)) {
+            throw new Error(`Dependent runtime ${String(entry.name)} conflicts with ${seen.get(value)}: ${label} ${String(value)} must be unique.`);
+        }
+        seen.set(value, String(entry.name));
+    }
+};
+const targetFrom = ({ name, declaration, loaded, primary, }) => Object.freeze({
+    name,
+    primary,
+    declaration,
+    configPath: loaded.configPath,
+    config: loaded.config,
+    paths: loaded.paths,
+});
+export const loadRuntimeTopology = async (options = {}) => {
+    const primaryLoaded = await loadRehearsalConfig(options);
+    const primary = targetFrom({
+        name: "primary",
+        declaration: null,
+        loaded: primaryLoaded,
+        primary: true,
+    });
+    const dependents = [];
+    for (const declaration of primary.config.dependentTargets) {
+        const loaded = await loadRehearsalConfig({
+            projectRoot: primaryLoaded.projectRoot,
+            configPath: declaration.configPath,
+        });
+        if (loaded.config.dependentTargets.length > 0) {
+            throw new Error(`Dependent runtime ${declaration.name} cannot declare its own dependentTargets. Nesting is intentionally unsupported.`);
+        }
+        dependents.push(targetFrom({
+            name: declaration.name,
+            declaration,
+            loaded,
+            primary: false,
+        }));
+    }
+    const targets = [primary, ...dependents];
+    assertUnique(targets, (target) => target.name, "target name");
+    assertUnique(targets, (target) => target.configPath, "config path");
+    assertUnique(targets, (target) => target.config.runtime.projectId, "runtime project ID");
+    assertUnique(targets.flatMap((target) => Object.entries(target.config.runtime.ports).map(([kind, port]) => ({
+        name: `${target.name} (${kind})`,
+        port,
+    }))), (entry) => entry.port, "runtime port");
+    assertUnique(targets, (target) => target.paths.applicationEnvironment, "application environment file");
+    assertUnique(targets.filter((target) => target.paths.rehearsalConfig), (target) => target.paths.rehearsalConfig, "Supabase runtime config");
+    for (let index = 0; index < targets.length; index += 1) {
+        for (let otherIndex = index + 1; otherIndex < targets.length; otherIndex += 1) {
+            const left = targets[index];
+            const right = targets[otherIndex];
+            if (isInside(left.paths.artifactDirectory, right.paths.artifactDirectory) ||
+                isInside(right.paths.artifactDirectory, left.paths.artifactDirectory)) {
+                throw new Error(`Dependent runtimes ${left.name} and ${right.name} must use separate, non-nested .rehearsal artifact directories.`);
+            }
+        }
+    }
+    return Object.freeze({
+        projectRoot: primaryLoaded.projectRoot,
+        primary,
+        dependents: Object.freeze(dependents),
+        targets: Object.freeze(targets),
+    });
+};
+const candidateSummary = (inspection) => {
+    const candidates = inspection.migrations.filter((migration) => migration.status === "candidate");
+    return Object.freeze({
+        baselineGenerationId: inspection.baselineGenerationId,
+        candidateSha256: inspection.candidateSha256,
+        candidateCount: candidates.length,
+        candidates: Object.freeze(candidates),
+    });
+};
+export const inspectRuntimeTopologyCandidates = async (options = {}) => {
+    const topology = await loadRuntimeTopology(options);
+    const targets = [];
+    for (const target of topology.targets) {
+        targets.push(Object.freeze({
+            ...target,
+            summary: candidateSummary(await inspectRehearsalMigrations({
+                projectRoot: topology.projectRoot,
+                configPath: target.configPath,
+            })),
+        }));
+    }
+    if (targets.length === 1) {
+        return Object.freeze({
+            topology,
+            targets: Object.freeze(targets),
+            candidateSha256: targets[0].summary.candidateSha256,
+            candidateCount: targets[0].summary.candidateCount,
+        });
+    }
+    const digestInput = targets.map((target) => ({
+        name: target.name,
+        candidateSha256: target.summary.candidateSha256,
+        candidates: target.summary.candidates.map((candidate) => ({
+            filename: candidate.filename,
+            sha256: candidate.sha256,
+        })),
+    }));
+    return Object.freeze({
+        topology,
+        targets: Object.freeze(targets),
+        candidateSha256: createHash("sha256")
+            .update(JSON.stringify(digestInput))
+            .digest("hex"),
+        candidateCount: targets.reduce((total, target) => total + target.summary.candidateCount, 0),
+    });
+};

package/dist/src/shared/diagnostics.d.mts

@@ -0,0 +1,97 @@
+/**
+ * Purpose: Provide stable Rehearsal result, failure, redaction, and rendering
+ * contracts for humans and automation. Do not run directly; this module is reusable
+ * script infrastructure.
+ */
+export declare const REHEARSAL_RESULT_VERSION = 1;
+export declare const REHEARSAL_VERSION: string;
+export declare const REHEARSAL_EXIT_CODES: Readonly<{
+    success: 0;
+    configuration_invalid: 2;
+    unsafe_environment: 3;
+    baseline_invalid: 4;
+    baseline_checksum_mismatch: 5;
+    migration_candidate_failure: 6;
+    migration_verification_failure: 7;
+    application_proof_failure: 8;
+    runtime_dependency_failure: 9;
+    internal_failure: 10;
+}>;
+export type RehearsalErrorCategory = keyof typeof REHEARSAL_EXIT_CODES;
+export type RehearsalStatus = "success" | "not_ready" | "error";
+export interface RehearsalErrorOptions {
+    category: RehearsalErrorCategory;
+    code: string;
+    message: string;
+    expected?: unknown;
+    actual?: unknown;
+    context?: unknown;
+    refused?: string;
+    suggestions?: readonly string[];
+    cause?: unknown;
+}
+export interface RehearsalErrorOverrides {
+    category?: RehearsalErrorCategory;
+    code?: string;
+    expected?: unknown;
+    actual?: unknown;
+    context?: unknown;
+    refused?: string;
+    suggestions?: readonly string[];
+}
+export interface RehearsalResultOptions<Data = unknown> {
+    command: string;
+    status: RehearsalStatus;
+    data: Data;
+    warnings?: readonly string[];
+    startedAt?: Date;
+    durationMs?: number;
+}
+export interface RehearsalResult<Data = unknown> {
+    schemaVersion: number;
+    rehearsalVersion: string;
+    command: string;
+    status: RehearsalStatus;
+    startedAt: string;
+    durationMs: number;
+    warnings: readonly string[];
+    data: Data;
+}
+export interface SerializedRehearsalError {
+    schemaVersion: number;
+    rehearsalVersion: string;
+    status: "error";
+    error: {
+        category: RehearsalErrorCategory;
+        code: string;
+        message: string;
+        expected: unknown;
+        actual: unknown;
+        context: unknown;
+        refused: string | undefined;
+        suggestions: readonly string[];
+        diagnosticId: string;
+        cause?: string;
+    };
+}
+export declare const redactDiagnosticValue: (value: unknown, key?: string) => unknown;
+export declare class RehearsalError extends Error {
+    readonly category: RehearsalErrorCategory;
+    readonly code: string;
+    readonly expected: unknown;
+    readonly actual: unknown;
+    readonly context: unknown;
+    readonly refused: string | undefined;
+    readonly suggestions: readonly string[];
+    readonly diagnosticId: string;
+    readonly exitCode: number;
+    constructor({ category, code, message, expected, actual, context, refused, suggestions, cause, }: RehearsalErrorOptions);
+}
+export declare const normalizeRehearsalError: (error: unknown, overrides?: RehearsalErrorOverrides) => RehearsalError;
+export declare const createRehearsalResult: ({ command, status, data, warnings, startedAt, durationMs, }: RehearsalResultOptions) => RehearsalResult;
+export declare const serializeRehearsalError: (error: unknown, { debug }?: {
+    debug?: boolean;
+}) => SerializedRehearsalError;
+export declare const renderHumanError: (error: unknown, { debug }?: {
+    debug?: boolean;
+}) => string;