@rehearsal-db/core 1.0.1 → 1.1.0

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/runtime/policy.d.mts

@@ -1,4 +1,5 @@
 /** Build narrowly validated local restore prerequisites and structural checks. */
+import { type RuntimePrivilege } from "./privileges.mjs";
 type PolicyObject = Record<string, unknown>;
 interface RuntimeRelation {
     readonly schema: string;
@@ -55,6 +56,7 @@ export interface RuntimePolicy {
     readonly triggers: readonly RuntimeTrigger[];
     readonly localRows: readonly RuntimeLocalRow[];
     readonly expectations: readonly RuntimeExpectation[];
+    readonly privileges?: readonly RuntimePrivilege[];
 }
 export declare const IDENTITY_CLAIM_RECEIPT_SQL = "create schema if not exists rehearsal_internal;\ncreate table if not exists rehearsal_internal.identity_claims (\n  identity_name text primary key,\n  placeholder_user_id uuid not null unique,\n  local_user_id uuid not null,\n  claimed_at timestamptz not null default now()\n);";
 export declare const validateRuntimePolicy: (input: unknown) => RuntimePolicy;

package/dist/src/runtime/policy.mjs

@@ -1,4 +1,5 @@
 /** Build narrowly validated local restore prerequisites and structural checks. */
+import { buildRuntimePrivilegeVerificationChecks, validateRuntimePrivileges, } from "./privileges.mjs";
 const IDENTIFIER = /^[a-z][a-z0-9_]{0,62}$/u;
 const IDENTITY_NAME = /^[a-z0-9][a-z0-9-]{1,62}$/u;
 const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/iu;
@@ -58,7 +59,14 @@ create table if not exists rehearsal_internal.identity_claims (
 );`;
 export const validateRuntimePolicy = (input) => {
     const policy = object(input, "runtimePolicy");
-    keys(policy, ["policyVersion", "prerequisites", "triggers", "localRows", "expectations"], "runtimePolicy");
+    keys(policy, [
+        "policyVersion",
+        "prerequisites",
+        "triggers",
+        "localRows",
+        "expectations",
+        "privileges",
+    ], "runtimePolicy");
     if (policy.policyVersion !== 1)
         throw new Error("Runtime policy must use policyVersion 1.");
     const prerequisites = object(policy.prerequisites ?? {}, "runtimePolicy.prerequisites");
@@ -216,6 +224,9 @@ export const validateRuntimePolicy = (input) => {
         triggers: Object.freeze(triggers),
         localRows: Object.freeze(localRows),
         expectations: Object.freeze(expectations),
+        ...(Object.hasOwn(policy, "privileges")
+            ? { privileges: validateRuntimePrivileges(policy.privileges) }
+            : {}),
     });
 };
 export const buildRuntimePrerequisiteSql = (input) => {
@@ -360,6 +371,7 @@ export const buildRuntimeVerificationSql = (input) => {
     }
     checks.push(`if exists (select 1 from pg_constraint where not convalidated) then
     raise exception 'Rehearsal found an unvalidated structural constraint'; end if;`);
+    checks.push(...buildRuntimePrivilegeVerificationChecks(policy.privileges ?? []));
     return `do $rehearsal_verify$
 begin
   ${checks.join("\n  ")}

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

@@ -0,0 +1,25 @@
+/** Validate opt-in effective privileges and build catalog-only verification checks. */
+export interface RuntimePrivilegeArgumentType {
+    readonly schema: "pg_catalog";
+    readonly name: string;
+}
+interface RuntimePrivilegeBase {
+    readonly schema: string;
+    readonly role: string;
+    readonly required: readonly string[];
+    readonly forbidden: readonly string[];
+}
+export type RuntimePrivilege = RuntimePrivilegeBase & ({
+    readonly kind: "schema";
+} | {
+    readonly kind: "table" | "sequence";
+    readonly name: string;
+} | {
+    readonly kind: "function";
+    readonly name: string;
+    readonly argumentTypes: readonly RuntimePrivilegeArgumentType[];
+});
+export declare const validateRuntimePrivileges: (input: unknown) => readonly RuntimePrivilege[];
+/** Blocks are embedded inside the policy verifier; no ACL or object writes are emitted. */
+export declare const buildRuntimePrivilegeVerificationChecks: (entries: readonly RuntimePrivilege[]) => readonly string[];
+export {};

package/dist/src/runtime/privileges.mjs

@@ -0,0 +1,198 @@
+/** Validate opt-in effective privileges and build catalog-only verification checks. */
+const IDENTIFIER = /^[a-z][a-z0-9_]{0,62}$/u;
+const TYPE_IDENTIFIER = /^[a-z_][a-z0-9_]{0,62}$/u;
+const PRIVILEGES = {
+    schema: ["CREATE", "USAGE"],
+    table: [
+        "SELECT",
+        "INSERT",
+        "UPDATE",
+        "DELETE",
+        "TRUNCATE",
+        "REFERENCES",
+        "TRIGGER",
+        "MAINTAIN",
+    ],
+    sequence: ["USAGE", "SELECT", "UPDATE"],
+    function: ["EXECUTE"],
+};
+const COLUMN_PRIVILEGES = new Set(["SELECT", "INSERT", "UPDATE", "REFERENCES"]);
+const object = (value, label) => {
+    if (value === null ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+};
+const keys = (value, allowed, label) => {
+    if (Object.keys(value).some((key) => !allowed.includes(key)))
+        throw new Error(`${label} contains unsupported fields.`);
+};
+const identifier = (value, label) => {
+    if (typeof value !== "string" || !IDENTIFIER.test(value))
+        throw new Error(`${label} is not a safe PostgreSQL identifier.`);
+    return value;
+};
+const permissions = (value, allowed, label) => {
+    if (!Array.isArray(value) ||
+        value.length > allowed.length ||
+        value.includes(undefined) ||
+        value.some((entry) => typeof entry !== "string" || !allowed.includes(entry)) ||
+        new Set(value).size !== value.length) {
+        throw new Error(`${label} must contain distinct supported privileges.`);
+    }
+    return Object.freeze([...value]);
+};
+export const validateRuntimePrivileges = (input) => {
+    if (!Array.isArray(input) ||
+        input.length > 1_024 ||
+        input.includes(undefined))
+        throw new Error("runtimePolicy.privileges must be an array of at most 1024 declarations.");
+    const observed = new Map();
+    return Object.freeze(input.map((value, index) => {
+        const label = `runtimePolicy.privileges[${index}]`;
+        const entry = object(value, label);
+        if (typeof entry.kind !== "string" ||
+            !Object.hasOwn(PRIVILEGES, entry.kind)) {
+            throw new Error(`${label}.kind is unsupported.`);
+        }
+        const kind = entry.kind;
+        keys(entry, [
+            "kind",
+            "schema",
+            "role",
+            "required",
+            "forbidden",
+            ...(kind === "schema" ? [] : ["name"]),
+            ...(kind === "function" ? ["argumentTypes"] : []),
+        ], label);
+        const schema = identifier(entry.schema, `${label}.schema`);
+        const role = identifier(entry.role, `${label}.role`);
+        const allowed = PRIVILEGES[kind];
+        const required = permissions(Object.hasOwn(entry, "required") ? entry.required : [], allowed, `${label}.required`);
+        const forbidden = permissions(Object.hasOwn(entry, "forbidden") ? entry.forbidden : [], allowed, `${label}.forbidden`);
+        if (required.length + forbidden.length === 0)
+            throw new Error(`${label} must declare a required or forbidden privilege.`);
+        const base = { schema, role, required, forbidden };
+        let normalized;
+        if (kind === "schema")
+            normalized = Object.freeze({ ...base, kind });
+        else {
+            const name = identifier(entry.name, `${label}.name`);
+            if (kind !== "function")
+                normalized = Object.freeze({ ...base, kind, name });
+            else {
+                if (!Array.isArray(entry.argumentTypes) ||
+                    entry.argumentTypes.length > 32 ||
+                    entry.argumentTypes.includes(undefined))
+                    throw new Error(`${label}.argumentTypes must be an array of at most 32 types.`);
+                const argumentTypes = entry.argumentTypes.map((value, argumentIndex) => {
+                    const typeLabel = `${label}.argumentTypes[${argumentIndex}]`;
+                    const type = object(value, typeLabel);
+                    keys(type, ["schema", "name"], typeLabel);
+                    if (type.schema !== "pg_catalog" ||
+                        typeof type.name !== "string" ||
+                        !TYPE_IDENTIFIER.test(type.name)) {
+                        throw new Error(`${typeLabel} must name a safe pg_catalog type.`);
+                    }
+                    return Object.freeze({
+                        schema: "pg_catalog",
+                        name: type.name,
+                    });
+                });
+                normalized = Object.freeze({
+                    ...base,
+                    kind,
+                    name,
+                    argumentTypes: Object.freeze(argumentTypes),
+                });
+            }
+        }
+        const identity = JSON.stringify([
+            kind,
+            schema,
+            normalized.kind === "schema" ? null : normalized.name,
+            role,
+            normalized.kind === "function" ? normalized.argumentTypes : null,
+        ]);
+        const earlier = observed.get(identity) ?? {
+            required: new Set(),
+            forbidden: new Set(),
+        };
+        if (required.some((privilege) => forbidden.includes(privilege) || earlier.forbidden.has(privilege)) ||
+            forbidden.some((privilege) => earlier.required.has(privilege))) {
+            throw new Error(`${label} has overlapping required and forbidden privileges.`);
+        }
+        required.forEach((privilege) => earlier.required.add(privilege));
+        forbidden.forEach((privilege) => earlier.forbidden.add(privilege));
+        observed.set(identity, earlier);
+        return normalized;
+    }));
+};
+const literal = (value) => `'${value.replaceAll("'", "''")}'`;
+const typeLookup = (type) => `select t.oid from pg_catalog.pg_type t
+      join pg_catalog.pg_namespace n on n.oid = t.typnamespace
+      where n.nspname = 'pg_catalog' and t.typname = ${literal(type.name)}`;
+const objectLookup = (entry) => {
+    if (entry.kind === "schema")
+        return `select n.oid into rehearsal_object from pg_catalog.pg_namespace n
+    where n.nspname = ${literal(entry.schema)};`;
+    if (entry.kind === "function")
+        return `select p.oid into rehearsal_object from pg_catalog.pg_proc p
+    join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = ${literal(entry.schema)} and p.proname = ${literal(entry.name)}
+      and p.prokind = 'f' and p.pronargs = ${entry.argumentTypes.length}
+      ${entry.argumentTypes.map((type, index) => `and p.proargtypes[${index}] = (${typeLookup(type)})`).join("\n      ")};`;
+    return `select c.oid into rehearsal_object from pg_catalog.pg_class c
+    join pg_catalog.pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${literal(entry.schema)} and c.relname = ${literal(entry.name)}
+      and c.relkind ${entry.kind === "sequence" ? "= 'S'" : "in ('r', 'p', 'v', 'm', 'f')"};`;
+};
+const permissionCheck = (entry, privilege, forbidden) => {
+    const functionName = `pg_catalog.has_${entry.kind}_privilege`;
+    const tableCheck = `${functionName}(rehearsal_role, rehearsal_object, ${literal(privilege)})`;
+    const expression = entry.kind === "table" && forbidden && COLUMN_PRIVILEGES.has(privilege)
+        ? `(${tableCheck} or pg_catalog.has_any_column_privilege(rehearsal_role, rehearsal_object, ${literal(privilege)}))`
+        : tableCheck;
+    const evaluation = privilege === "MAINTAIN"
+        ? `if pg_catalog.current_setting('server_version_num')::integer < 170000 then
+      rehearsal_allowed := false;
+    else
+      rehearsal_allowed := ${expression};
+    end if;`
+        : `rehearsal_allowed := ${expression};`;
+    return `${evaluation}
+    if rehearsal_allowed is null then
+      raise exception 'Rehearsal privilege object is unavailable';
+    end if;
+    if rehearsal_allowed is ${forbidden ? "true" : "false"} then
+      raise exception 'Rehearsal ${forbidden ? "forbidden privilege is present" : "required privilege is missing"}';
+    end if;`;
+};
+/** Blocks are embedded inside the policy verifier; no ACL or object writes are emitted. */
+export const buildRuntimePrivilegeVerificationChecks = (entries) => entries.map((entry) => `declare
+    rehearsal_role pg_catalog.oid;
+    rehearsal_object pg_catalog.oid;
+    rehearsal_allowed boolean;
+  begin
+    select r.oid into rehearsal_role from pg_catalog.pg_roles r
+    where r.rolname = ${literal(entry.role)};
+    if rehearsal_role is null then
+      raise exception 'Rehearsal privilege role is missing';
+    end if;
+    ${entry.kind === "function"
+    ? entry.argumentTypes
+        .map((type) => `if not exists (${typeLookup(type)}) then
+      raise exception 'Rehearsal privilege argument type is missing';
+    end if;`)
+        .join("\n    ")
+    : ""}
+    ${objectLookup(entry)}
+    if rehearsal_object is null then
+      raise exception 'Rehearsal privilege object is missing';
+    end if;
+    ${entry.required.map((privilege) => permissionCheck(entry, privilege, false)).join("\n    ")}
+    ${entry.forbidden.map((privilege) => permissionCheck(entry, privilege, true)).join("\n    ")}
+  end;`);

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)) {

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

@@ -1,5 +1,7 @@
 /** Project-wide mutation lock and installed-package integrity guard. */
+import type { MigrationFailureDiagnostic } from "../runtime/migration_failure.mjs";
 import { type OperationProgressSnapshot, type RecentOperationProgress } from "./operation_progress_contract.mjs";
+import { type RecentOperationFailure } from "./operation_progress_storage.mjs";
 export interface InstalledPackageFingerprint {
     readonly files: number;
     readonly sha256: string;
@@ -8,7 +10,7 @@ export interface ProjectOperation {
     readonly command: string;
     readonly id: string;
     readonly startedAt: string;
-    writeProgress(progress: OperationProgressSnapshot): Promise<void>;
+    writeProgress(progress: OperationProgressSnapshot, migrationFailure?: MigrationFailureDiagnostic): Promise<void>;
     release(): Promise<void>;
     releaseSync(): void;
 }
@@ -22,6 +24,7 @@ export type ProjectOperationState = Readonly<{
         progress: OperationProgressSnapshot | null;
     }> | null;
     recent: readonly RecentOperationProgress[] | null;
+    recentFailures?: readonly RecentOperationFailure[] | null;
 }>;
 export declare const createInstalledPackageFingerprint: ({ packageRoot, }: {
     packageRoot: string;