@rehearsal-db/core 1.0.0 → 1.0.2

package/dist/src/shared/operation_progress.mjs

@@ -2,6 +2,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { performance } from "node:perf_hooks";
 import { isOperationCancelled } from "./cancellation.mjs";
+import { RehearsalError } from "./diagnostics.mjs";
+import { parseMigrationFailureDiagnostic, } from "../runtime/migration_failure.mjs";
 import { MAX_OPERATION_PROGRESS_EVENTS, MAX_OPERATION_PROGRESS_STAGES, OPERATION_PROGRESS_PHASES, parseOperationProgressSnapshot, } from "./operation_progress_contract.mjs";
 const contexts = new AsyncLocalStorage();
 export const getOwnedOperationProgressId = () => contexts.getStore()?.operation.id ?? null;
@@ -47,9 +49,36 @@ const snapshot = (context) => {
 };
 const publish = async (context) => {
     const value = parseOperationProgressSnapshot(snapshot(context));
-    context.writes = context.writes.then(() => context.operation.writeProgress(value));
+    const migrationFailure = context.migrationFailure;
+    context.writes = context.writes.then(() => context.operation.writeProgress(value, migrationFailure));
     await context.writes;
 };
+/** Cleanup aggregates retain the original error first; never inspect sibling failures. */
+const originalMigrationFailure = (error) => {
+    try {
+        let original = error;
+        for (let depth = 0; depth <= 4; depth += 1) {
+            if (original instanceof AggregateError) {
+                if (depth === 4 || !Array.isArray(original.errors))
+                    return undefined;
+                original = original.errors[0];
+                continue;
+            }
+            if (original instanceof RehearsalError &&
+                !isOperationCancelled(original) &&
+                original.context !== null &&
+                typeof original.context === "object" &&
+                !Array.isArray(original.context) &&
+                "migrationFailure" in original.context)
+                return parseMigrationFailureDiagnostic(original.context.migrationFailure);
+            return undefined;
+        }
+    }
+    catch {
+        /* Invalid error metadata is not evidence and cannot replace the original failure. */
+    }
+    return undefined;
+};
 export const withOperationProgress = async ({ operation, task, now = () => new Date(), }) => {
     if (operation === null)
         return task();
@@ -85,6 +114,11 @@ export const withOperationProgress = async ({ operation, task, now = () => new D
         }
         catch (error) {
             context.state = isOperationCancelled(error) ? "cancelled" : "failed";
+            if (context.state === "failed") {
+                const diagnostic = originalMigrationFailure(error);
+                if (diagnostic !== undefined)
+                    context.migrationFailure = diagnostic;
+            }
             appendEvent(context, context.state === "cancelled"
                 ? "operation.cancelled"
                 : "operation.failed");

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

@@ -1,24 +1,45 @@
+import { type MigrationFailureDiagnostic } from "../runtime/migration_failure.mjs";
 import { type OperationProgressSnapshot, type RecentOperationProgress } from "./operation_progress_contract.mjs";
-export declare const writeOwnedOperationProgress: ({ lockDirectory, token, operationId, progress, }: {
+interface StoredOperationProgress extends RecentOperationProgress {
+    readonly migrationFailure?: MigrationFailureDiagnostic;
+}
+export interface RecentOperationFailure {
+    readonly operationId: string;
+    readonly diagnostic: MigrationFailureDiagnostic;
+}
+interface OwnedOperationProgress {
+    readonly progress: OperationProgressSnapshot;
+    readonly migrationFailure?: MigrationFailureDiagnostic;
+}
+export declare const writeOwnedOperationProgress: ({ lockDirectory, token, operationId, progress, migrationFailure, }: {
     readonly lockDirectory: string;
     readonly token: string;
     readonly operationId: string;
     readonly progress: OperationProgressSnapshot;
+    readonly migrationFailure?: MigrationFailureDiagnostic;
 }) => Promise<void>;
-export declare const readOwnedOperationProgress: ({ lockDirectory, token, operationId, startedAt, }: {
+export declare const readOwnedOperationProgressRecord: ({ lockDirectory, token, operationId, startedAt, }: {
     readonly lockDirectory: string;
     readonly token: string;
     readonly operationId: string;
     readonly startedAt: string;
-}) => Promise<OperationProgressSnapshot | null>;
-export declare const readRecentOperationProgress: ({ projectHash, operationKinds, }: {
+}) => Promise<OwnedOperationProgress | null>;
+export declare const readOwnedOperationProgress: (input: Parameters<typeof readOwnedOperationProgressRecord>[0]) => Promise<OperationProgressSnapshot | null>;
+declare const readStoredOperationProgress: ({ projectHash, operationKinds, }: {
     readonly projectHash: string;
     readonly operationKinds: ReadonlySet<string>;
-}) => Promise<readonly RecentOperationProgress[] | null>;
-export declare const archiveOperationProgress: ({ projectHash, operationKinds, kind, rehearsalVersion, progress, }: {
+}) => Promise<readonly StoredOperationProgress[] | null>;
+export declare const readRecentOperationHistory: (input: Parameters<typeof readStoredOperationProgress>[0]) => Promise<{
+    readonly recent: readonly RecentOperationProgress[] | null;
+    readonly recentFailures: readonly RecentOperationFailure[] | null;
+}>;
+export declare const readRecentOperationProgress: (input: Parameters<typeof readStoredOperationProgress>[0]) => Promise<readonly RecentOperationProgress[] | null>;
+export declare const archiveOperationProgress: ({ projectHash, operationKinds, kind, rehearsalVersion, progress, migrationFailure, }: {
     readonly projectHash: string;
     readonly operationKinds: ReadonlySet<string>;
     readonly kind: string;
     readonly rehearsalVersion: string | null;
     readonly progress: OperationProgressSnapshot;
+    readonly migrationFailure?: MigrationFailureDiagnostic;
 }) => Promise<void>;
+export {};

package/dist/src/shared/operation_progress_storage.mjs

@@ -3,6 +3,7 @@ import { lstat, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { parseMigrationFailureDiagnostic, } from "../runtime/migration_failure.mjs";
 import { MAX_RECENT_OPERATION_PROGRESS, parseOperationProgressSnapshot, } from "./operation_progress_contract.mjs";
 const HISTORY_ROOT = join(tmpdir(), "rehearsal-db-operation-activity");
 const MAX_PROGRESS_BYTES = 32 * 1024;
@@ -47,29 +48,47 @@ const writePrivateJson = async (path, value, maximumBytes) => {
         await rm(temporary, { force: true });
     }
 };
-export const writeOwnedOperationProgress = async ({ lockDirectory, token, operationId, progress, }) => {
+export const writeOwnedOperationProgress = async ({ lockDirectory, token, operationId, progress, migrationFailure, }) => {
     const validated = parseOperationProgressSnapshot(progress);
     if (validated.operationId !== operationId)
         throw new Error("Operation telemetry belongs to another owner.");
-    await writePrivateJson(join(lockDirectory, "progress.json"), { formatVersion: 1, ownerToken: token, progress: validated }, MAX_PROGRESS_BYTES);
+    const failure = migrationFailure === undefined
+        ? {}
+        : { migrationFailure: parseMigrationFailureDiagnostic(migrationFailure) };
+    if (migrationFailure !== undefined && validated.state !== "failed")
+        throw new Error("Migration failure evidence requires a failed operation.");
+    await writePrivateJson(join(lockDirectory, "progress.json"), { formatVersion: 1, ownerToken: token, progress: validated, ...failure }, MAX_PROGRESS_BYTES);
 };
-export const readOwnedOperationProgress = async ({ lockDirectory, token, operationId, startedAt, }) => {
+export const readOwnedOperationProgressRecord = async ({ lockDirectory, token, operationId, startedAt, }) => {
     try {
         const value = (await readPrivateJson(join(lockDirectory, "progress.json"), MAX_PROGRESS_BYTES));
         if (value.formatVersion !== 1 ||
             value.ownerToken !== token ||
-            Object.keys(value).some((key) => !["formatVersion", "ownerToken", "progress"].includes(key)))
+            Object.keys(value).some((key) => ![
+                "formatVersion",
+                "ownerToken",
+                "progress",
+                "migrationFailure",
+            ].includes(key)))
             return null;
         const snapshot = parseOperationProgressSnapshot(value.progress);
+        const failure = value.migrationFailure === undefined
+            ? {}
+            : {
+                migrationFailure: parseMigrationFailureDiagnostic(value.migrationFailure),
+            };
+        if (value.migrationFailure !== undefined && snapshot.state !== "failed")
+            return null;
         return snapshot.operationId === operationId &&
             snapshot.startedAt === startedAt
-            ? snapshot
+            ? { progress: snapshot, ...failure }
             : null;
     }
     catch {
         return null;
     }
 };
+export const readOwnedOperationProgress = async (input) => (await readOwnedOperationProgressRecord(input))?.progress ?? null;
 const assertHistoryRoot = async () => {
     await mkdir(HISTORY_ROOT, { recursive: true, mode: 0o700 });
     const details = await lstat(HISTORY_ROOT);
@@ -79,7 +98,7 @@ const assertHistoryRoot = async () => {
         (typeof process.getuid === "function" && details.uid !== process.getuid()))
         throw new Error("Operation history directory is not private.");
 };
-export const readRecentOperationProgress = async ({ projectHash, operationKinds, }) => {
+const readStoredOperationProgress = async ({ projectHash, operationKinds, }) => {
     requireProjectHash(projectHash);
     try {
         const root = await lstat(HISTORY_ROOT);
@@ -105,15 +124,28 @@ export const readRecentOperationProgress = async ({ projectHash, operationKinds,
                     (typeof record.rehearsalVersion !== "string" ||
                         record.rehearsalVersion.length > 64 ||
                         !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?(?:\+[a-zA-Z0-9.-]+)?$/u.test(record.rehearsalVersion))) ||
-                Object.keys(record).some((key) => !["kind", "rehearsalVersion", "progress"].includes(key)))
+                Object.keys(record).some((key) => ![
+                    "kind",
+                    "rehearsalVersion",
+                    "progress",
+                    "migrationFailure",
+                ].includes(key)))
                 throw new Error("Invalid history metadata.");
             const progress = parseOperationProgressSnapshot(record.progress);
             if (progress.state === "running")
                 throw new Error("An unfinished operation cannot be reported as completed history.");
+            const failure = record.migrationFailure === undefined
+                ? {}
+                : {
+                    migrationFailure: parseMigrationFailureDiagnostic(record.migrationFailure),
+                };
+            if (record.migrationFailure !== undefined && progress.state !== "failed")
+                throw new Error("Migration failure history contradicts its outcome.");
             return Object.freeze({
                 kind: record.kind,
                 rehearsalVersion: record.rehearsalVersion,
                 progress,
+                ...failure,
             });
         });
         if (new Set(recent.map((entry) => entry.progress.operationId)).size !==
@@ -125,12 +157,29 @@ export const readRecentOperationProgress = async ({ projectHash, operationKinds,
         return missing(error) ? Object.freeze([]) : null;
     }
 };
-export const archiveOperationProgress = async ({ projectHash, operationKinds, kind, rehearsalVersion, progress, }) => {
+export const readRecentOperationHistory = async (input) => {
+    const stored = await readStoredOperationProgress(input);
+    if (stored === null)
+        return { recent: null, recentFailures: null };
+    return {
+        recent: Object.freeze(stored.map(({ kind, rehearsalVersion, progress }) => Object.freeze({ kind, rehearsalVersion, progress }))),
+        recentFailures: Object.freeze(stored.flatMap(({ progress, migrationFailure }) => migrationFailure === undefined
+            ? []
+            : [
+                Object.freeze({
+                    operationId: progress.operationId,
+                    diagnostic: migrationFailure,
+                }),
+            ])),
+    };
+};
+export const readRecentOperationProgress = async (input) => (await readRecentOperationHistory(input)).recent;
+export const archiveOperationProgress = async ({ projectHash, operationKinds, kind, rehearsalVersion, progress, migrationFailure, }) => {
     requireProjectHash(projectHash);
     if (progress.state === "running")
         return;
     await assertHistoryRoot();
-    const previous = await readRecentOperationProgress({
+    const previous = await readStoredOperationProgress({
         projectHash,
         operationKinds,
     });
@@ -140,7 +189,14 @@ export const archiveOperationProgress = async ({ projectHash, operationKinds, ki
         kind,
         rehearsalVersion,
         progress: parseOperationProgressSnapshot(progress),
+        ...(migrationFailure === undefined
+            ? {}
+            : {
+                migrationFailure: parseMigrationFailureDiagnostic(migrationFailure),
+            }),
     };
+    if (migrationFailure !== undefined && progress.state !== "failed")
+        throw new Error("Migration failure history requires a failed operation.");
     const recent = [
         ...previous.filter((item) => item.progress.operationId !== progress.operationId),
         entry,

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

@@ -8,8 +8,9 @@ export interface CleanProcessEnvironmentOptions {
     inheritedEnvironment?: ProcessEnvironment;
     overrides?: ProcessEnvironment;
     passthroughKeys?: readonly string[];
+    platform?: NodeJS.Platform;
 }
 export declare const isLoopbackUrl: (value: string) => boolean;
 export declare const assertLoopbackUrl: (label: string, value: string) => void;
 export declare const pickEnvironmentVariables: (source: ProcessEnvironment, keys: readonly string[]) => Record<string, string>;
-export declare const createCleanProcessEnvironment: ({ inheritedEnvironment, overrides, passthroughKeys, }?: CleanProcessEnvironmentOptions) => Record<string, string>;
+export declare const createCleanProcessEnvironment: ({ inheritedEnvironment, overrides, passthroughKeys, platform, }?: CleanProcessEnvironmentOptions) => Record<string, string>;

package/dist/src/shared/process_environment.mjs

@@ -21,6 +21,17 @@ const SAFE_SYSTEM_ENVIRONMENT_KEYS = Object.freeze([
     "TEMP",
     "USER",
 ]);
+// Windows resolves environment names case-insensitively. Keep only infrastructure
+// needed to locate executables and user configuration, never ambient credentials.
+const SAFE_WINDOWS_ENVIRONMENT_KEYS = Object.freeze([
+    "SystemRoot",
+    "WINDIR",
+    "ComSpec",
+    "PATHEXT",
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+]);
 const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "::1", "[::1]", "localhost"]);
 export const isLoopbackUrl = (value) => {
     try {
@@ -41,10 +52,41 @@ export const pickEnvironmentVariables = (source, keys) => Object.fromEntries(key
     const value = source[key];
     return value === undefined ? [] : [[key, value]];
 }));
-export const createCleanProcessEnvironment = ({ inheritedEnvironment = process.env, overrides = {}, passthroughKeys = [], } = {}) => ({
-    ...pickEnvironmentVariables(inheritedEnvironment, [
+const pickWindowsEnvironmentVariables = (source, keys) => {
+    const selected = {};
+    const seen = new Set();
+    for (const key of keys) {
+        const normalized = key.toUpperCase();
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        const sourceKey = source[key] !== undefined
+            ? key
+            : Object.keys(source).find((candidate) => candidate.toUpperCase() === normalized &&
+                source[candidate] !== undefined);
+        if (sourceKey !== undefined)
+            selected[key] = source[sourceKey];
+    }
+    return selected;
+};
+export const createCleanProcessEnvironment = ({ inheritedEnvironment = process.env, overrides = {}, passthroughKeys = [], platform = process.platform, } = {}) => {
+    const keys = [
         ...SAFE_SYSTEM_ENVIRONMENT_KEYS,
+        ...(platform === "win32" ? SAFE_WINDOWS_ENVIRONMENT_KEYS : []),
         ...passthroughKeys,
-    ]),
-    ...pickEnvironmentVariables(overrides, Object.keys(overrides)),
-});
+    ];
+    if (platform !== "win32") {
+        return {
+            ...pickEnvironmentVariables(inheritedEnvironment, keys),
+            ...pickEnvironmentVariables(overrides, Object.keys(overrides)),
+        };
+    }
+    const environment = pickWindowsEnvironmentVariables(inheritedEnvironment, keys);
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined)
+            continue;
+        const existing = Object.keys(environment).find((candidate) => candidate.toUpperCase() === key.toUpperCase());
+        environment[existing ?? key] = value;
+    }
+    return environment;
+};

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

@@ -0,0 +1,15 @@
+import type { SpawnSyncReturns } from "node:child_process";
+export type PortStartupFailure = "port_in_use" | "port_unavailable";
+type StartupCommandResult = Pick<SpawnSyncReturns<string>, "status" | "stdout" | "stderr" | "error">;
+/** Recognized bind evidence, never an assertion about the host's root cause. */
+export declare const classifyPortStartupFailure: (output: string) => PortStartupFailure | null;
+/** All advice is fixed text: provider output, port numbers and names stay private. */
+export declare const portStartupGuidance: (evidence: PortStartupFailure, target: "postgresql" | "supabase") => string;
+/** Preserve startup failure without echoing Docker arguments, credentials or logs. */
+export declare const assertPostgresqlStartupResult: (result: StartupCommandResult) => void;
+/** The injected runner retains cancellation and runtime ownership enforcement. */
+export declare const runPostgresqlStartupCommand: (runCommand: (command: string, args: readonly string[], options: {
+    capture: boolean;
+    allowFailure: boolean;
+}) => StartupCommandResult, args: readonly string[]) => void;
+export {};

package/dist/src/targets/port_start_failure.mjs

@@ -0,0 +1,46 @@
+/** Recognized bind evidence, never an assertion about the host's root cause. */
+export const classifyPortStartupFailure = (output) => {
+    const bounded = `${output.slice(0, 64 * 1024)}\n${output.slice(-64 * 1024)}`.replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, "");
+    if (/address already in use|port is already allocated|only one usage of each socket address/iu.test(bounded))
+        return "port_in_use";
+    if (/ports? (?:are|is) not available|\b(?:bind|listen)\b[^\n]{0,400}(?:forbidden by its access permissions|permission denied|access is denied|cannot assign requested address|WSAEACCES)|\bsocket\b[^\n]{0,400}forbidden by its access permissions/iu.test(bounded))
+        return "port_unavailable";
+    return null;
+};
+/** All advice is fixed text: provider output, port numbers and names stay private. */
+export const portStartupGuidance = (evidence, target) => [
+    evidence === "port_in_use"
+        ? "Port guidance: the provider reported an allocated or occupied local port."
+        : "Port guidance: the provider could not bind a requested local port. This does not prove an existing listener or a Windows port reservation; an exclusion or host access policy is possible.",
+    target === "postgresql"
+        ? "Review runtime.databasePort in the active Rehearsal config and choose a different available local port before retrying."
+        : "Review runtime.apiPort, runtime.databasePort and runtime.studioPort in the active Rehearsal config and the matching ports in the dedicated Supabase config; choose an available local port block before retrying.",
+    ...(evidence === "port_unavailable"
+        ? [
+            "For a Windows/WSL Docker host, inspect exclusions in Windows PowerShell (read-only): netsh interface ipv4 show excludedportrange protocol=tcp",
+        ]
+        : []),
+    "Do not kill unknown listeners or change Windows excluded/reserved port ranges to make these ports fit.",
+].join("\n");
+/** Preserve startup failure without echoing Docker arguments, credentials or logs. */
+export const assertPostgresqlStartupResult = (result) => {
+    if (!result.error && result.status === 0)
+        return;
+    const portFailure = classifyPortStartupFailure(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
+    const processCode = result.error?.code;
+    const processEvidence = processCode === "ENOENT"
+        ? "docker_unavailable"
+        : processCode === "ETIMEDOUT"
+            ? "process_timeout"
+            : processCode === "ENOBUFS"
+                ? "provider_output_limit"
+                : null;
+    throw new Error([
+        `PostgreSQL startup failed (${Number.isInteger(result.status) ? `exit ${result.status}` : "process failure"}).`,
+        `Reported startup evidence: ${portFailure ?? processEvidence ?? "unknown; provider supplied no recognized safe failure detail"}.`,
+        ...(portFailure ? [portStartupGuidance(portFailure, "postgresql")] : []),
+        "Provider logs, command arguments, paths, environment values and connection URLs are omitted. This summary does not establish the underlying cause.",
+    ].join("\n"));
+};
+/** The injected runner retains cancellation and runtime ownership enforcement. */
+export const runPostgresqlStartupCommand = (runCommand, args) => assertPostgresqlStartupResult(runCommand("docker", args, { capture: true, allowFailure: true }));

package/dist/src/targets/postgresql.mjs

@@ -18,10 +18,11 @@ import { inspectPostgresqlRuntimeStatus } from "./postgresql_status.mjs";
 import { ensureConfiguredContainerRuntime } from "./supabase_environment.mjs";
 import { getOperationCancellationSignal, throwIfOperationCancelled, } from "../shared/cancellation.mjs";
 import { bindOwnedProcessCancellation, signalOwnedProcessGroup, } from "../shared/owned_process.mjs";
-import { runOwnedPostgresqlSql, runPostgresqlCommand, } from "./postgresql_process.mjs";
+import { runOwnedPostgresqlMigration, runPostgresqlCommand, } from "./postgresql_process.mjs";
 import { parseRuntimeInvocation } from "./target.mjs";
 import { guardRuntimeManagerAction } from "../runtime/runtime_manager_guards.mjs";
 import { runtimeDockerEnvironment } from "../runtime/local_docker_context.mjs";
+import { runPostgresqlStartupCommand } from "./port_start_failure.mjs";
 import { assertDockerResourceLabels } from "./docker_resource_ownership.mjs";
 import { buildRuntimeFinalizationSql, buildRuntimePostSchemaSql, buildRuntimePrerequisiteSql, buildRuntimeVerificationSql, validateRuntimePolicy, } from "../runtime/policy.mjs";
 const repositoryRoot = process.cwd();
@@ -193,13 +194,13 @@ create table if not exists rehearsal_internal.schema_migrations (
   applied_at timestamptz not null default now()
 );`);
 const applyMigration = async ({ migration, directory, kind, }) => {
-    const source = await readFile(join(directory, migration.filename), "utf8");
-    await runOwnedPostgresqlSql({
+    await runOwnedPostgresqlMigration({
         containerName,
         database,
         databaseUser,
         repositoryRoot,
-        sql: source,
+        migration,
+        directory,
         migrationKind: kind,
     });
     runPsql(`insert into rehearsal_internal.schema_migrations
@@ -415,7 +416,7 @@ const createContainer = async (password) => {
     runCommand("docker", ["volume", "create", "--label", label, volumeName], {
         capture: true,
     });
-    runCommand("docker", [
+    runPostgresqlStartupCommand(runCommand, [
         "run",
         "--detach",
         "--pull=never",
@@ -434,7 +435,7 @@ const createContainer = async (password) => {
         "--volume",
         `${volumeName}:/var/lib/postgresql/data`,
         image,
-    ], { capture: true });
+    ]);
     await waitForDatabase();
 };
 const resetRuntime = async () => {
@@ -518,7 +519,7 @@ const startRuntime = async () => {
     }
     const running = runCommand("docker", ["inspect", "--format", "{{.State.Running}}", containerName], { capture: true }).stdout.trim();
     if (running !== "true") {
-        runCommand("docker", ["start", containerName], { capture: true });
+        runPostgresqlStartupCommand(runCommand, ["start", containerName]);
     }
     await waitForDatabase();
     const environment = databaseEnvironment(marker.databasePassword);

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

@@ -1,4 +1,6 @@
 /** Run one PostgreSQL command in an interruptible process owned by Rehearsal. */
+import type { MigrationFileEntry } from "../runtime/migration_history.mjs";
+import { type MigrationFailureSource } from "../runtime/migration_failure_source.mjs";
 import { runOwnedProcess } from "../shared/owned_process.mjs";
 export declare const runPostgresqlCommand: (command: string, args: readonly string[], { cwd, capture, input, allowFailure, }: {
     readonly cwd: string;
@@ -6,12 +8,17 @@ export declare const runPostgresqlCommand: (command: string, args: readonly stri
     readonly input?: string;
     readonly allowFailure?: boolean;
 }) => import("child_process").SpawnSyncReturns<string>;
-export declare const runOwnedPostgresqlSql: ({ containerName, database, databaseUser, repositoryRoot, sql, migrationKind, runProcessImplementation, }: {
+export declare const runOwnedPostgresqlSql: ({ containerName, database, databaseUser, repositoryRoot, sql, migrationKind, migrationSource, runProcessImplementation, }: {
     containerName: string;
     database: string;
     databaseUser: string;
     repositoryRoot: string;
     sql: string;
     migrationKind: "baseline" | "candidate";
+    migrationSource?: MigrationFailureSource;
     runProcessImplementation?: typeof runOwnedProcess;
 }) => Promise<void>;
+export declare const runOwnedPostgresqlMigration: ({ migration, directory, migrationKind, ...options }: Omit<Parameters<typeof runOwnedPostgresqlSql>[0], "sql" | "migrationSource"> & {
+    migration: MigrationFileEntry;
+    directory: string;
+}) => Promise<void>;

package/dist/src/targets/postgresql_process.mjs

@@ -1,10 +1,15 @@
 /** Run one PostgreSQL command in an interruptible process owned by Rehearsal. */
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { isMigrationWorkspacePath, parseMigrationFailureSource, } from "../runtime/migration_failure_source.mjs";
 import { getOperationCancellationSignal, throwIfOperationCancelled, } from "../shared/cancellation.mjs";
 import { runOwnedProcess } from "../shared/owned_process.mjs";
 import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 import { runtimeDockerEnvironment } from "../runtime/local_docker_context.mjs";
 import { captureRuntimeStartupOwnership } from "../runtime/runtime_startup_ownership.mjs";
+import { diagnoseMigrationFailure, renderMigrationFailureDiagnostic, } from "../runtime/migration_failure.mjs";
 export const runPostgresqlCommand = (command, args, { cwd, capture = false, input, allowFailure = false, }) => {
     if (command === "docker" &&
         (["run", "start"].includes(args[0] ?? "") ||
@@ -33,7 +38,7 @@ export const runPostgresqlCommand = (command, args, { cwd, capture = false, inpu
     }
     return result;
 };
-export const runOwnedPostgresqlSql = async ({ containerName, database, databaseUser, repositoryRoot, sql, migrationKind, runProcessImplementation = runOwnedProcess, }) => {
+export const runOwnedPostgresqlSql = async ({ containerName, database, databaseUser, repositoryRoot, sql, migrationKind, migrationSource, runProcessImplementation = runOwnedProcess, }) => {
     const cancellationSignal = getOperationCancellationSignal();
     const result = await runProcessImplementation({
         command: "docker",
@@ -45,6 +50,8 @@ export const runOwnedPostgresqlSql = async ({ containerName, database, databaseU
             "--quiet",
             "--set",
             "ON_ERROR_STOP=1",
+            "--set",
+            "VERBOSITY=sqlstate",
             "--username",
             databaseUser,
             "--dbname",
@@ -62,6 +69,43 @@ export const runOwnedPostgresqlSql = async ({ containerName, database, databaseU
     if (result.error)
         throw result.error;
     if (result.status !== 0) {
-        throw new Error(`The ${migrationKind === "candidate" ? "confirmed candidate" : "baseline"} PostgreSQL migration failed (exit ${Number.isInteger(result.status) ? result.status : "unknown"}; stderr ${result.stderrByteCount} bytes). SQL and provider output are withheld.`);
+        throw new Error(`The ${migrationKind === "candidate" ? "confirmed candidate" : "baseline"} PostgreSQL migration failed (exit ${Number.isInteger(result.status) ? result.status : "unknown"}; stderr ${result.stderrByteCount} bytes). SQL and provider output are withheld.\n${renderMigrationFailureDiagnostic({ ...diagnoseMigrationFailure({ provider: "postgresql", stderr: result.stderr }), ...(migrationSource === undefined ? {} : { source: parseMigrationFailureSource(migrationSource) }) })}`);
+    }
+};
+export const runOwnedPostgresqlMigration = async ({ migration, directory, migrationKind, ...options }) => {
+    const path = join(directory, migration.filename);
+    const canonicalPath = await realpath(path);
+    const bytes = await readFile(canonicalPath);
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    if (sha256 !== migration.fileSha256)
+        throw new Error("The reviewed migration file changed before execution. Review the new exact plan before retrying; no migration SQL was started.");
+    const sql = bytes.toString("utf8");
+    if (!Buffer.from(sql, "utf8").equals(bytes))
+        throw new Error("The reviewed migration file is not valid UTF-8. Save it as UTF-8 and review the new exact plan before retrying; no migration SQL was started.");
+    const canonicalRoot = await realpath(options.repositoryRoot);
+    const local = relative(canonicalRoot, canonicalPath).split(sep).join("/");
+    let migrationSource;
+    try {
+        migrationSource = parseMigrationFailureSource({
+            schemaVersion: 1,
+            kind: migrationKind,
+            filename: migration.filename,
+            sha256,
+            workspaceRelativePath: migrationKind === "candidate" && isMigrationWorkspacePath(local)
+                ? local
+                : null,
+            line: null,
+            column: null,
+            evidence: "owned_execution_input",
+        });
     }
+    catch {
+        /* Unsupported names omit telemetry, not previously permitted SQL execution. */
+    }
+    await runOwnedPostgresqlSql({
+        ...options,
+        migrationKind,
+        sql,
+        ...(migrationSource === undefined ? {} : { migrationSource }),
+    });
 };

package/dist/src/targets/supabase_process.mjs

@@ -3,6 +3,7 @@ import { getOperationCancellationSignal, throwIfOperationCancelled, } from "../s
 import { runOwnedProcess } from "../shared/owned_process.mjs";
 import { createCleanProcessEnvironment, } from "../shared/process_environment.mjs";
 import { runtimeDockerEnvironment } from "../runtime/local_docker_context.mjs";
+import { diagnoseMigrationFailure, renderMigrationFailureDiagnostic, } from "../runtime/migration_failure.mjs";
 export const runOwnedSupabaseMigration = async ({ environment, repositoryRoot, runtimeWorkdir, runProcessImplementation = runOwnedProcess, }) => {
     const cancellationSignal = getOperationCancellationSignal();
     const result = await runProcessImplementation({
@@ -19,6 +20,6 @@ export const runOwnedSupabaseMigration = async ({ environment, repositoryRoot, r
     if (result.error)
         throw result.error;
     if (result.status !== 0) {
-        throw new Error(`The confirmed candidate Supabase migration failed (exit ${Number.isInteger(result.status) ? result.status : "unknown"}; stderr ${result.stderrByteCount} bytes). SQL and provider output are withheld.`);
+        throw new Error(`The confirmed candidate Supabase migration failed (exit ${Number.isInteger(result.status) ? result.status : "unknown"}; stderr ${result.stderrByteCount} bytes). SQL and provider output are withheld.\n${renderMigrationFailureDiagnostic(diagnoseMigrationFailure({ provider: "supabase", stderr: result.stderr }))}`);
     }
 };

package/dist/src/targets/supabase_start_failure.mjs

@@ -1,4 +1,5 @@
 /** Summarize provider startup evidence without retaining container logs or secrets. */
+import { classifyPortStartupFailure, portStartupGuidance, } from "./port_start_failure.mjs";
 const SERVICE_NAMES = Object.freeze({
     db: "database",
     auth: "auth",
@@ -18,7 +19,6 @@ const SERVICE_NAMES = Object.freeze({
 const REASONS = Object.freeze([
     ["out_of_memory", /out of memory|oom[- ]killed|memory allocation failed/iu],
     ["disk_full", /no space left on device|disk quota exceeded/iu],
-    ["port_in_use", /address already in use|port is already allocated/iu],
     ["image_architecture", /exec format error/iu],
     ["image_pull", /failed to pull|pull access denied|manifest unknown/iu],
     [
@@ -40,6 +40,9 @@ export const summarizeSupabaseStartupFailure = ({ output, status, processErrorCo
         reasons.add("process_timeout");
     if (processErrorCode === "ENOBUFS")
         reasons.add("provider_output_limit");
+    const portFailure = classifyPortStartupFailure(bounded);
+    if (portFailure)
+        reasons.add(portFailure);
     for (const [code, pattern] of REASONS)
         if (pattern.test(bounded))
             reasons.add(code);
@@ -60,6 +63,7 @@ export const summarizeSupabaseStartupFailure = ({ output, status, processErrorCo
         ...(services.size
             ? [`Reported service states: ${[...services].slice(0, 16).join(", ")}.`]
             : []),
+        ...(portFailure ? [portStartupGuidance(portFailure, "supabase")] : []),
         "Provider logs, paths, environment values and connection URLs are omitted. This summary does not establish the underlying cause.",
     ].join("\n");
 };