@rehearsal-db/core 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -5,6 +5,37 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-10-20
+
+### Fixed
+
+- Explain recognized PostgreSQL/Supabase migration failures with bounded native
+  SQLSTATE evidence and safe syntax, schema, constraint, permission, connectivity
+  and timeout guidance. Unsupported or ambiguous evidence remains unknown; raw
+  SQL, provider details, credentials and private rows are not exposed.
+- Preserve the original diagnosis across cleanup and bounded operation history so
+  the CLI and editor can show the same failure after refresh. Failed operations
+  never claim verification or unconditional rollback success.
+- Optionally identify the exact approved PostgreSQL input file by hash, without
+  inventing a failing SQL origin, line or column. Reject invalid UTF-8 before
+  execution rather than submitting replacement-decoded bytes.
+- Point recognized bind failures at the configured local ports, including safe
+  Windows/WSL exclusion-inspection guidance. Do not infer a reservation from every
+  denial or suggest terminating unknown listeners.
+- Keep database-only command guidance separate from optional application launch.
+
+### Documentation and distribution
+
+- Add a main-tutorial existing-row constraint failure, reviewed backfill/fix and
+  verification sequence, plus a same-project VS Code handoff and safe local-copy
+  recovery for unsupported external npm links.
+- Pair with Starter 0.1.22 for actionable persistent failures, safe exact-byte
+  source opening, distinct command/database states and truthful recorded proof.
+- Refresh the separate macOS, Linux and Windows/WSL 2 setup bundles to exact core
+  1.0.2. Native Windows database execution remains unsupported.
+
+## [1.0.1] - 2026-10-19
+
 ### Platform compatibility
 
 - Keep macOS Intel/Apple Silicon and Linux execution distinct from Windows desktop
@@ -784,7 +815,9 @@ not unattended cleanup, and container age is not proof of user inactivity.
   publication uses short-lived trusted OIDC, and every release tag must already exist on
   protected `main`.
 
-[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.10...v1.0.0
 [0.1.0-rc.10]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.9...v0.1.0-rc.10
 [0.1.0-rc.9]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.8...v0.1.0-rc.9

package/README.md

@@ -47,7 +47,7 @@ it through a reviewed privacy policy, and retire the access again. It is never p
 production deployment tool.
 
 The CLI is free and MIT-licensed, with stable releases on
-[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.0.1**;
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.0.2**;
 install only a version actually published there. Prefer a visual workflow?
 [Install the free VS Code Starter preview](docs/vscode.md). Its included features are
 free indefinitely for personal or commercial development—no account, card, or trial.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {

package/dist/src/cli/failure_output.d.mts

@@ -0,0 +1,3 @@
+/** Preserve fixed original migration guidance without masking aggregate cleanup failure. */
+import { RehearsalError, type RehearsalErrorOverrides } from "../shared/diagnostics.mjs";
+export declare const normalizeCliFailure: (error: unknown, overrides?: RehearsalErrorOverrides) => RehearsalError;

package/dist/src/cli/failure_output.mjs

@@ -0,0 +1,48 @@
+/** Preserve fixed original migration guidance without masking aggregate cleanup failure. */
+import { RehearsalError, normalizeRehearsalError, } from "../shared/diagnostics.mjs";
+import { parseMigrationFailureDiagnostic, } from "../runtime/migration_failure.mjs";
+const aggregateMigrationFailure = (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 &&
+                original.category !== "operation_cancelled" &&
+                original.context !== null &&
+                typeof original.context === "object" &&
+                !Array.isArray(original.context) &&
+                "migrationFailure" in original.context)
+                return parseMigrationFailureDiagnostic(original.context.migrationFailure);
+            return undefined;
+        }
+    }
+    catch {
+        /* Untrusted metadata is not evidence; retain the aggregate's existing failure. */
+    }
+    return undefined;
+};
+export const normalizeCliFailure = (error, overrides = {}) => {
+    const failure = normalizeRehearsalError(error, overrides);
+    if (!(error instanceof AggregateError))
+        return failure;
+    const migrationFailure = aggregateMigrationFailure(error);
+    if (migrationFailure === undefined)
+        return failure;
+    // Keep outer category/exit and cleanup warning. Project no original/sibling text.
+    return new RehearsalError({
+        category: failure.category,
+        code: failure.code,
+        message: failure.message,
+        expected: failure.expected,
+        actual: failure.actual,
+        context: { migrationFailure },
+        ...(failure.refused === undefined ? {} : { refused: failure.refused }),
+        suggestions: [...migrationFailure.suggestions, ...failure.suggestions],
+        cause: failure.cause,
+    });
+};

package/dist/src/cli/rehearsal.mjs

@@ -8,13 +8,14 @@ import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import * as prompts from "@clack/prompts";
-import { RehearsalError, normalizeRehearsalError, renderHumanError, serializeRehearsalError, } from "../shared/diagnostics.mjs";
+import { RehearsalError, renderHumanError, serializeRehearsalError, } from "../shared/diagnostics.mjs";
 import { acquireProjectOperation, assertInstalledPackageFingerprint, createInstalledPackageFingerprint, } from "../shared/operation_guard.mjs";
 import { commandMutatesProject, parseArguments, resetGuidedFlags, } from "./arguments.mjs";
 import { usage } from "./basic_command_handlers.mjs";
 import { createCliCommandRegistry } from "./cli_commands.mjs";
 import { createCliSessionState, resetCommandSessionState, } from "./command_contract.mjs";
 import { createCommandEmitter } from "./command_output.mjs";
+import { normalizeCliFailure } from "./failure_output.mjs";
 import { createGuidedHome } from "./guided.mjs";
 import { createProjectCommands } from "./project_commands.mjs";
 import { buildRuntimeStackPlan, createRuntimeCommands, runRuntimeStackDoctor, topologyCandidateSummary, topologyCommandEnvironment, } from "./runtime_commands.mjs";
@@ -217,7 +218,7 @@ try {
     await main();
 }
 catch (error) {
-    const failure = normalizeRehearsalError(error, {
+    const failure = normalizeCliFailure(error, {
         expected: "a safe, versioned, local-only Rehearsal operation",
         actual: errorMessage(error),
         refused: "No further Rehearsal action was performed.",

package/dist/src/cli/runtime_action_handlers.mjs

@@ -168,13 +168,20 @@ export const createRuntimeActionHandlers = ({ prepareCandidateConfirmation, prep
                         : undefined;
                     const renderedHttpProofResults = "httpProofResults" in value ? value.httpProofResults : [];
                     const renderedLifecycle = "lifecycle" in value ? value.lifecycle : undefined;
+                    const hasApplicationLaunch = topology.primary.config.application.readiness !== null;
                     const nextAction = {
                         run: renderedLifecycle?.runtimeState === "stopped"
-                            ? "The runtime was stopped with its database and Storage changes preserved. Run rehearsal start or rehearsal open to resume."
-                            : "Next: run rehearsal open for hands-on testing, then rehearsal verify.",
-                        start: "Next: run rehearsal open for hands-on testing or rehearsal status.",
+                            ? `The runtime was stopped with its database and Storage changes preserved. Run rehearsal start${hasApplicationLaunch ? " or rehearsal open" : ""} to resume.`
+                            : hasApplicationLaunch
+                                ? "Next: run rehearsal open for hands-on testing, then rehearsal verify."
+                                : "The rehearsal command is complete; the database remains running. Next: run rehearsal verify or inspect the local database. This database-only project has no application to open.",
+                        start: hasApplicationLaunch
+                            ? "Next: run rehearsal open for hands-on testing or rehearsal status."
+                            : "The database is running. Next: run rehearsal status or rehearsal verify; no application launch is configured.",
                         migrate: "Next: run rehearsal verify to prove the current runtime.",
-                        reset: "Next: run rehearsal open or rehearsal verify.",
+                        reset: hasApplicationLaunch
+                            ? "Next: run rehearsal open or rehearsal verify."
+                            : "Next: run rehearsal verify or inspect the local database; no application launch is configured.",
                         status: "Next: run rehearsal verify, reset, stop, or discard.",
                         stop: "Next: run rehearsal start when you want to resume.",
                         discard: "The disposable runtime was removed; the immutable baseline remains.",

package/dist/src/cli/runtime_commands.mjs

@@ -20,7 +20,8 @@ import { buildRuntimeManagerArguments } from "../targets/target.mjs";
 import { parseRuntimeStatusSnapshot, renderRuntimeStatusSnapshot, } from "../runtime/status.mjs";
 import { applyRuntimePersistence, shouldStopRuntime, } from "../runtime/persistence.mjs";
 import { executeRuntimeTargetStack } from "./runtime_stack_execution.mjs";
-import { summarizeRuntimeManagerFailure } from "./runtime_failure_summary.mjs";
+import { summarizeRuntimeManagerFailure, runtimePortFailureGuidance, } from "./runtime_failure_summary.mjs";
+import { readManagerMigrationFailure } from "../runtime/migration_failure.mjs";
 import { releaseOwnedColimaWhenIdle } from "../runtime/container_engine_ownership.mjs";
 import { inspectRehearsalResources } from "../runtime/resource_inventory.mjs";
 import { assertLocalDockerContext } from "../runtime/local_docker_context.mjs";
@@ -59,8 +60,12 @@ const parseCommand = (source) => {
 const projectCommandEnvironment = (additional = {}) => createCleanProcessEnvironment({ overrides: additional });
 const RUNTIME_STARTUP_FAILURE_PATTERN = /container\b.*\b(?:is not ready|starting|unhealthy)|health(?:check)?\b.*\b(?:failed|starting|unhealthy)|out of memory|\boom\b|no space left|resource temporarily unavailable/iu;
 export const classifyManagerFailure = ({ action, output, inferredCategory, }) => {
+    if (/^(?:Error:\s*)?The baseline (?:PostgreSQL|Supabase) migration failed \(/mu.test(output))
+        return "baseline_invalid";
+    if (/^(?:Error:\s*)?The confirmed candidate (?:PostgreSQL|Supabase) migration failed \(/mu.test(output))
+        return "migration_candidate_failure";
     if (RUNTIME_STARTUP_FAILURE_PATTERN.test(output) ||
-        /Supabase startup failed \(/u.test(output) ||
+        /(?:PostgreSQL|Supabase) startup failed \(/u.test(output) ||
         /^Error:\s*supabase start(?:\s|$)/imu.test(output)) {
         return "runtime_dependency_failure";
     }
@@ -272,22 +277,31 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
                 inferredCategory: inferred.category,
             });
             const startupFailure = category === "runtime_dependency_failure";
-            const engineCapacity = startupFailure
+            const migrationFailure = readManagerMigrationFailure(completeOutput);
+            const portGuidance = runtimePortFailureGuidance(conciseOutput);
+            const engineCapacity = startupFailure && portGuidance.length === 0
                 ? inspectContainerCapacity()
                 : undefined;
             throw new RehearsalError({
                 category,
                 code: `MANAGER_${action.toUpperCase()}_FAILED`,
-                message: `The local Rehearsal ${action} operation did not complete.`,
+                message: `The local Rehearsal ${action} operation did not complete.${migrationFailure ? ` ${migrationFailure.summary}` : ""}`,
                 expected: "the isolated runtime operation to finish and verify",
                 actual: conciseOutput || `exit ${result.status}`,
-                context: { action, ...(engineCapacity ? { engineCapacity } : {}) },
+                context: {
+                    action,
+                    target: targetName ?? "primary",
+                    ...(migrationFailure ? { migrationFailure } : {}),
+                    ...(engineCapacity ? { engineCapacity } : {}),
+                },
                 refused: "The runtime was not reported as trusted.",
                 suggestions: [
+                    ...(migrationFailure?.suggestions ?? []),
+                    ...portGuidance,
                     "Review the concise failure above, then rerun rehearsal doctor before retrying.",
-                    ...(startupFailure
+                    ...(startupFailure && portGuidance.length === 0
                         ? [
-                            "Stop unrelated local stacks or increase Docker/Colima capacity, then retry. Rehearsal will not change engine settings or bypass service health checks.",
+                            "If startup evidence confirms a resource shortage, stop only stacks you own or increase Docker/Colima capacity, then retry. Rehearsal will not change engine settings or bypass service health checks.",
                             "Run docker stats --no-stream to identify active containers using the shared engine.",
                         ]
                         : []),

package/dist/src/cli/runtime_failure_summary.d.mts

@@ -1 +1,2 @@
+export declare const runtimePortFailureGuidance: (output: string) => readonly string[];
 export declare const summarizeRuntimeManagerFailure: (output: string) => string;

package/dist/src/cli/runtime_failure_summary.mjs

@@ -1,5 +1,17 @@
 /** Keep useful manager failures rather than debug advice and trailing Node stacks. */
 import { redactDiagnosticValue } from "../shared/diagnostics.mjs";
+import { readManagerMigrationFailure, renderMigrationFailureDiagnostic, } from "../runtime/migration_failure.mjs";
+import { portStartupGuidance } from "../targets/port_start_failure.mjs";
+export const runtimePortFailureGuidance = (output) => {
+    const provider = output.match(/^(?:Error:\s*)?(PostgreSQL|Supabase) startup failed \((?:exit -?\d+|process failure)\)\.$/mu)?.[1];
+    const evidence = output
+        .match(/^Reported startup evidence: ([a-z_, ]+)\.$/mu)?.[1]
+        ?.split(/,\s*/u);
+    const port = evidence?.find((value) => value === "port_in_use" || value === "port_unavailable");
+    return provider && (port === "port_in_use" || port === "port_unavailable")
+        ? portStartupGuidance(port, provider === "PostgreSQL" ? "postgresql" : "supabase").split("\n")
+        : [];
+};
 export const summarizeRuntimeManagerFailure = (output) => {
     let nodeSourceContext = false;
     const lines = output
@@ -27,16 +39,22 @@ export const summarizeRuntimeManagerFailure = (output) => {
         .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s"']+/giu, "[REDACTED_URL]")
         .replace(/\b[A-Z][A-Z0-9_]*\s*=\s*[^\s]+/gu, "[REDACTED_ENV]")
         .replace(/(?:\/[A-Za-z0-9_.-]+){2,}(?::\d+(?::\d+)?)?/gu, "[LOCAL_PATH]"));
-    const startup = lines.findIndex((line) => /Supabase startup failed \(/u.test(line));
+    const startup = lines.findIndex((line) => /(?:PostgreSQL|Supabase) startup failed \(/u.test(line));
     const failure = lines.reduce((last, line, index) => (/^[A-Za-z]*Error:/u.test(line) ? index : last), -1);
     const migration = lines.findIndex((line) => /^Error: The (?:confirmed candidate|baseline) (?:PostgreSQL|Supabase) migration failed \(exit (?:-?\d+|unknown); stderr \d+ bytes\)\. SQL and provider output are withheld\.$/u.test(line));
     const rollbackFailed = /The runtime operation failed and its owned runtime could not be removed automatically\./u.test(output);
+    const migrationDiagnostic = migration >= 0 ? readManagerMigrationFailure(lines.join("\n")) : undefined;
     const selected = startup >= 0
         ? lines
-            .slice(startup, startup + 4)
-            .filter((line) => /^(?:Error:\s*)?Supabase startup failed \(|^Reported startup evidence:|^Reported service states:|^Provider logs, paths, environment values and connection URLs are omitted\./u.test(line))
+            .slice(startup, startup + 12)
+            .filter((line) => /^(?:Error:\s*)?(?:PostgreSQL|Supabase) startup failed \(|^Reported startup evidence:|^Reported service states:|^Provider logs, (?:command arguments, )?paths, environment values and connection URLs are omitted\./u.test(line))
         : migration >= 0
-            ? [lines[migration]]
+            ? [
+                lines[migration],
+                ...(migrationDiagnostic
+                    ? [renderMigrationFailureDiagnostic(migrationDiagnostic)]
+                    : []),
+            ]
             : rollbackFailed
                 ? [
                     "Error: The operation failed; the original cause could not be safely summarized.",
@@ -44,10 +62,18 @@ export const summarizeRuntimeManagerFailure = (output) => {
                 : failure >= 0
                     ? lines.slice(failure, failure + 8)
                     : lines.slice(-8);
+    if (startup >= 0)
+        selected.push(...runtimePortFailureGuidance(selected.join("\n")));
     if (rollbackFailed)
         selected.push("Owned rollback cleanup could not be confirmed. Resources may remain; inspect activity and status before retrying. No cleanup success is claimed.");
     if (startup >= 0 &&
         /owned cleanup could not be proved|owned resources were retained|Resources and data were retained|retained resources need review/iu.test(output))
         selected.push("Owned startup cleanup could not be proved; resources and data were retained. Inspect activity and status before retrying.");
+    if (selected.join("\n").length > 2_000 && migrationDiagnostic?.source) {
+        // Human summary stays bounded and retains cleanup warnings; structured output
+        // independently reads the complete, bounded manager frame.
+        const { source: _source, ...diagnostic } = migrationDiagnostic;
+        selected[1] = renderMigrationFailureDiagnostic(diagnostic);
+    }
     return selected.join("\n").slice(0, 2_000);
 };

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

@@ -0,0 +1,28 @@
+/** Translate provider-native SQLSTATE evidence into fixed, privacy-safe guidance. */
+import { type MigrationFailureSource } from "./migration_failure_source.mjs";
+export type MigrationFailureClassification = "syntax" | "schema" | "constraint" | "permission" | "connectivity" | "timeout_or_cancel" | "unknown";
+export interface MigrationFailureDiagnostic {
+    readonly schemaVersion: 1;
+    readonly provider: "postgresql" | "supabase";
+    readonly classification: MigrationFailureClassification;
+    readonly sqlState: string | null;
+    readonly evidence: "provider_sqlstate" | "unavailable" | "ambiguous";
+    readonly summary: string;
+    readonly suggestions: readonly string[];
+    readonly source?: MigrationFailureSource;
+}
+export declare const migrationFailureDiagnostic: ({ provider, sqlState, evidence, }: {
+    provider: MigrationFailureDiagnostic["provider"];
+    sqlState?: string | null;
+    evidence?: MigrationFailureDiagnostic["evidence"];
+}) => MigrationFailureDiagnostic;
+/** Read only known provider error envelopes, never arbitrary mentions of SQLSTATE. */
+export declare const diagnoseMigrationFailure: ({ provider, stderr, }: {
+    provider: MigrationFailureDiagnostic["provider"];
+    stderr: string;
+}) => MigrationFailureDiagnostic;
+export declare const renderMigrationFailureDiagnostic: (diagnostic: MigrationFailureDiagnostic) => string;
+/** Closed public projection: reject free text or metadata not generated by this owner. */
+export declare const parseMigrationFailureDiagnostic: (value: unknown) => MigrationFailureDiagnostic;
+/** Parse only Rehearsal's fixed migration header and adjacent fixed code line. */
+export declare const readManagerMigrationFailure: (output: string) => MigrationFailureDiagnostic | undefined;

package/dist/src/runtime/migration_failure.mjs

@@ -0,0 +1,197 @@
+/** Translate provider-native SQLSTATE evidence into fixed, privacy-safe guidance. */
+import { parseMigrationFailureSource, readMigrationSourceFrame, renderMigrationSourceFrame, } from "./migration_failure_source.mjs";
+const explanations = {
+    "42601": [
+        "syntax",
+        "The database reported a SQL syntax error.",
+        "Review the candidate SQL for missing keywords, punctuation or malformed statements; then review the new exact plan before retrying.",
+    ],
+    "23502": [
+        "constraint",
+        "Rows do not satisfy a NOT NULL requirement.",
+        "Review existing NULL values and any new writes. Backfill or transform incompatible rows before enforcing NOT NULL.",
+    ],
+    "23503": [
+        "constraint",
+        "Rows do not satisfy a foreign-key constraint.",
+        "Review missing referenced rows and migration ordering before enforcing the foreign key.",
+    ],
+    "23505": [
+        "constraint",
+        "Rows do not satisfy a uniqueness requirement.",
+        "Review duplicate values and choose a data-preserving resolution before adding the unique constraint or index.",
+    ],
+    "23514": [
+        "constraint",
+        "Rows do not satisfy a CHECK constraint.",
+        "Existing rows may not satisfy the new constraint. Review and backfill incompatible rows before enforcing it; also check values written by the migration.",
+    ],
+    "23P01": [
+        "constraint",
+        "Rows conflict with an exclusion constraint.",
+        "Review overlapping or conflicting values before enforcing the exclusion constraint.",
+    ],
+    "42P01": [
+        "schema",
+        "The migration references a table that is unavailable in this schema.",
+        "Review table names, schema qualification and migration ordering; this is not a confirmed syntax error.",
+    ],
+    "42703": [
+        "schema",
+        "The migration references a column that is unavailable in this schema.",
+        "Review column names and migration ordering; this is not a confirmed syntax error.",
+    ],
+    "42704": [
+        "schema",
+        "The migration references a database object that is unavailable.",
+        "Review object names, schema qualification and migration ordering.",
+    ],
+    "42804": [
+        "schema",
+        "The migration uses incompatible data types.",
+        "Review the column types and any required explicit, data-preserving conversion.",
+    ],
+    "42P07": [
+        "schema",
+        "The migration attempts to create a table that already exists.",
+        "Review baseline history and candidate ordering instead of deleting migration history.",
+    ],
+    "42701": [
+        "schema",
+        "The migration attempts to create a column that already exists.",
+        "Review baseline history and candidate ordering instead of deleting migration history.",
+    ],
+    "42501": [
+        "permission",
+        "The database denied permission for a migration operation.",
+        "Review the intended local role and required privileges; do not switch to hosted credentials or bypass permissions.",
+    ],
+    "28P01": [
+        "permission",
+        "The database rejected authentication.",
+        "Review the disposable local runtime credentials without printing or sharing them.",
+    ],
+    "57014": [
+        "timeout_or_cancel",
+        "The database reported a cancelled statement, possibly from a timeout.",
+        "Review statement timeout and cancellation evidence. No automatic retry or successful rollback is implied.",
+    ],
+};
+export const migrationFailureDiagnostic = ({ provider, sqlState = null, evidence = sqlState ? "provider_sqlstate" : "unavailable", }) => {
+    const safeCode = sqlState &&
+        /^[0-9A-Z]{5}$/u.test(sqlState) &&
+        !/^(?:00|01|02)/u.test(sqlState)
+        ? sqlState
+        : null;
+    const explanation = safeCode ? explanations[safeCode] : undefined;
+    const connectivity = safeCode?.startsWith("08");
+    return {
+        schemaVersion: 1,
+        provider,
+        classification: explanation?.[0] ?? (connectivity ? "connectivity" : "unknown"),
+        sqlState: safeCode,
+        evidence: safeCode
+            ? "provider_sqlstate"
+            : evidence === "ambiguous"
+                ? "ambiguous"
+                : "unavailable",
+        summary: explanation?.[1] ??
+            (connectivity
+                ? "The database reported a connection failure."
+                : "The failure could not be classified from recognized provider SQLSTATE evidence. It is not a confirmed syntax error."),
+        suggestions: [
+            explanation?.[2] ??
+                (connectivity
+                    ? "Check the disposable local database connection and runtime status before retrying."
+                    : "Review the exact candidate locally and its database requirements. Do not assume syntax, data or permissions are the cause."),
+            "No automatic SQL change or retry was performed. The failure itself does not prove rollback or cleanup; inspect runtime status before retrying.",
+        ],
+    };
+};
+/** Read only known provider error envelopes, never arbitrary mentions of SQLSTATE. */
+export const diagnoseMigrationFailure = ({ provider, stderr, }) => {
+    // Truncation could hide a conflicting error. Refuse rather than guess from a slice.
+    if (Buffer.byteLength(stderr) > 128 * 1024)
+        return migrationFailureDiagnostic({ provider });
+    const codes = new Set();
+    for (const line of stderr
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, "")
+        .split(/\r?\n/u)) {
+        const match = provider === "postgresql"
+            ? line.match(/^(?:psql:(?:<stdin>|[^\r\n]+):\d+:\s*)?(?:ERROR|FATAL):\s+([0-9A-Z]{5})(?::(?:\s|$)|\s*$)/u)
+            : line.match(/^ERROR:\s+[^\r\n]*\(SQLSTATE ([0-9A-Z]{5})\)\s*$/u);
+        if (match?.[1] && !/^(?:00|01|02)/u.test(match[1]))
+            codes.add(match[1]);
+    }
+    return migrationFailureDiagnostic({
+        provider,
+        sqlState: codes.size === 1 ? [...codes][0] : null,
+        evidence: codes.size > 1 ? "ambiguous" : "unavailable",
+    });
+};
+export const renderMigrationFailureDiagnostic = (diagnostic) => [
+    `Migration SQLSTATE: ${diagnostic.sqlState ?? diagnostic.evidence}.`,
+    ...(diagnostic.source === undefined
+        ? []
+        : [renderMigrationSourceFrame(diagnostic.source)]),
+    diagnostic.summary,
+    ...diagnostic.suggestions,
+].join("\n");
+/** Closed public projection: reject free text or metadata not generated by this owner. */
+export const parseMigrationFailureDiagnostic = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid safe migration diagnostic.");
+    const record = value;
+    if (Object.keys(record)
+        .filter((key) => key !== "source")
+        .sort()
+        .join(",") !==
+        "classification,evidence,provider,schemaVersion,sqlState,suggestions,summary" ||
+        record.schemaVersion !== 1 ||
+        typeof record.provider !== "string" ||
+        !["postgresql", "supabase"].includes(record.provider) ||
+        !(record.sqlState === null || typeof record.sqlState === "string") ||
+        !["provider_sqlstate", "unavailable", "ambiguous"].includes(String(record.evidence)))
+        throw new Error("Invalid safe migration diagnostic.");
+    const canonical = migrationFailureDiagnostic({
+        provider: record.provider,
+        sqlState: record.sqlState,
+        evidence: record.evidence,
+    });
+    if (record.classification !== canonical.classification ||
+        record.sqlState !== canonical.sqlState ||
+        record.evidence !== canonical.evidence ||
+        record.summary !== canonical.summary ||
+        JSON.stringify(record.suggestions) !== JSON.stringify(canonical.suggestions))
+        throw new Error("Invalid safe migration diagnostic.");
+    return record.source === undefined
+        ? canonical
+        : { ...canonical, source: parseMigrationFailureSource(record.source) };
+};
+/** Parse only Rehearsal's fixed migration header and adjacent fixed code line. */
+export const readManagerMigrationFailure = (output) => {
+    if (Buffer.byteLength(output) > 128 * 1024)
+        return undefined;
+    const match = output.match(/^(?:[\t ]*Error:[\t ]*)?The (?:confirmed candidate|baseline) (PostgreSQL|Supabase) migration failed \(exit (?:-?\d+|unknown); stderr \d+ bytes\)\. SQL and provider output are withheld\.\r?\n[\t ]*Migration SQLSTATE: ([0-9A-Z]{5}|unavailable|ambiguous)\.[\t ]*$/mu);
+    if (!match)
+        return undefined;
+    const code = match[2];
+    const diagnostic = migrationFailureDiagnostic({
+        provider: match[1] === "PostgreSQL" ? "postgresql" : "supabase",
+        sqlState: /^[0-9A-Z]{5}$/u.test(code) ? code : null,
+        evidence: code === "ambiguous" ? "ambiguous" : "unavailable",
+    });
+    const afterCode = output
+        .slice(match.index + match[0].length)
+        .replace(/^\r?\n/u, "")
+        .split(/\r?\n/u)[0];
+    const source = readMigrationSourceFrame(output, afterCode);
+    const expectedKind = /The baseline /u.test(match[0])
+        ? "baseline"
+        : "candidate";
+    return source === undefined ||
+        source.kind !== expectedKind ||
+        diagnostic.provider !== "postgresql"
+        ? diagnostic
+        : { ...diagnostic, source };
+};

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

@@ -0,0 +1,16 @@
+/** Closed attempted-input provenance. No statement/source-position inference. */
+export interface MigrationFailureSource {
+    readonly schemaVersion: 1;
+    readonly kind: "baseline" | "candidate";
+    readonly filename: string;
+    readonly sha256: string;
+    readonly workspaceRelativePath: string | null;
+    readonly line: null;
+    readonly column: null;
+    readonly evidence: "owned_execution_input";
+}
+export declare const isMigrationWorkspacePath: (value: unknown) => value is string;
+export declare const parseMigrationFailureSource: (value: unknown) => MigrationFailureSource;
+export declare const renderMigrationSourceFrame: (source: MigrationFailureSource) => string;
+/** Only a single complete, adjacent core frame can contribute provenance. */
+export declare const readMigrationSourceFrame: (output: string, adjacentLine: string | undefined) => MigrationFailureSource | undefined;

package/dist/src/runtime/migration_failure_source.mjs

@@ -0,0 +1,68 @@
+const controls = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u;
+export const isMigrationWorkspacePath = (value) => typeof value === "string" &&
+    Buffer.byteLength(value) <= 1024 &&
+    value.length > 0 &&
+    !/[\\:%?#]/u.test(value) &&
+    !controls.test(value) &&
+    value
+        .split("/")
+        .every((part) => part.length > 0 && part !== "." && part !== "..");
+export const parseMigrationFailureSource = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid migration input provenance.");
+    const source = value;
+    if (Object.keys(source).sort().join(",") !==
+        "column,evidence,filename,kind,line,schemaVersion,sha256,workspaceRelativePath" ||
+        source.schemaVersion !== 1 ||
+        !["baseline", "candidate"].includes(String(source.kind)) ||
+        typeof source.kind !== "string" ||
+        typeof source.filename !== "string" ||
+        Buffer.byteLength(source.filename) > 255 ||
+        !/^\d{14}_[a-z0-9_]+\.sql$/u.test(source.filename) ||
+        typeof source.sha256 !== "string" ||
+        !/^[a-f0-9]{64}$/u.test(source.sha256) ||
+        (source.workspaceRelativePath !== null &&
+            (!isMigrationWorkspacePath(source.workspaceRelativePath) ||
+                source.workspaceRelativePath.split("/").at(-1) !== source.filename)) ||
+        source.line !== null ||
+        source.column !== null ||
+        source.evidence !== "owned_execution_input")
+        throw new Error("Invalid migration input provenance.");
+    return {
+        schemaVersion: 1,
+        kind: source.kind,
+        filename: source.filename,
+        sha256: source.sha256,
+        workspaceRelativePath: source.workspaceRelativePath,
+        line: null,
+        column: null,
+        evidence: "owned_execution_input",
+    };
+};
+const framePrefix = "Rehearsal migration input v1: ";
+export const renderMigrationSourceFrame = (source) => framePrefix +
+    Buffer.from(JSON.stringify(parseMigrationFailureSource(source))).toString("base64url");
+/** Only a single complete, adjacent core frame can contribute provenance. */
+export const readMigrationSourceFrame = (output, adjacentLine) => {
+    try {
+        const frames = output
+            .split(/\r?\n/u)
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith(framePrefix));
+        if (frames.length !== 1 || adjacentLine?.trim() !== frames[0])
+            return undefined;
+        const encoded = frames[0].slice(framePrefix.length);
+        if (encoded.length > 4096 || !/^[A-Za-z0-9_-]+$/u.test(encoded))
+            return undefined;
+        const bytes = Buffer.from(encoded, "base64url");
+        if (bytes.length > 2048 || bytes.toString("base64url") !== encoded)
+            return undefined;
+        const source = parseMigrationFailureSource(JSON.parse(bytes.toString("utf8")));
+        return renderMigrationSourceFrame(source) === frames[0]
+            ? source
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/src/shared/diagnostics.mjs

@@ -84,6 +84,11 @@ export class RehearsalError extends Error {
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const inferCategory = (error) => {
     const message = errorMessage(error);
+    // Fixed driver phase precedes incidental words in safe remediation text.
+    if (/^(?:Error:\s*)?The baseline (?:PostgreSQL|Supabase) migration failed \(/mu.test(message))
+        return "baseline_invalid";
+    if (/^(?:Error:\s*)?The confirmed candidate (?:PostgreSQL|Supabase) migration failed \(/mu.test(message))
+        return "migration_candidate_failure";
     if (/checksum/iu.test(message))
         return "baseline_checksum_mismatch";
     if (/container\b.*\b(?:is not ready|starting|unhealthy)|health(?:check)?\b.*\b(?:failed|starting|unhealthy)|out of memory|\boom\b|no space left|resource temporarily unavailable/iu.test(message)) {