@rehearsal-db/core 1.0.0 → 1.0.2

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/plan.mjs

@@ -21,6 +21,8 @@ import { readRehearsalServiceEnvironment } from "./service_environment.mjs";
 import { readBoundRuntimeSanitizationPolicy, validateRuntimeSanitizationPolicy, } from "../baseline/sanitization_policy.mjs";
 import { buildAuthenticationReview, buildBaselineScopeReview, } from "./project_review.mjs";
 import { readVerifiedBaselineShapeEvidence } from "../source/shape_files.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const hasErrorCode = (error, code) => typeof error === "object" &&
     error !== null &&
@@ -29,7 +31,7 @@ const hasErrorCode = (error, code) => typeof error === "object" &&
 const commandAvailable = (command, args = ["--version"]) => {
     const result = spawnSync(command, args, {
         encoding: "utf8",
-        env: Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined ? [] : [[key, process.env[key]]])),
+        env: createCleanProcessEnvironment(),
         stdio: ["ignore", "pipe", "pipe"],
     });
     return {
@@ -378,6 +380,23 @@ export const inspectRehearsalMigrations = async (options = {}) => {
     };
 };
 export const runRehearsalDoctor = async (options = {}) => {
+    const host = await inspectHostPlatform({
+        projectRoot: options.projectRoot ?? process.cwd(),
+    });
+    if (!host.supported) {
+        return {
+            state: "NOT READY",
+            checks: [
+                {
+                    id: "operating-system",
+                    label: "Operating-system support",
+                    status: "fail",
+                    detail: host.detail,
+                    remediation: host.remediation,
+                },
+            ],
+        };
+    }
     let loaded;
     try {
         loaded = await loadRehearsalConfig(options);
@@ -426,12 +445,9 @@ export const runRehearsalDoctor = async (options = {}) => {
             id: "operating-system",
             label: "Operating-system support",
             run: async () => {
-                if (!["darwin", "linux"].includes(process.platform)) {
-                    throw new Error(`${process.platform} is not supported by the version-1 contract.`);
-                }
-                return `${process.platform} is in the supported matrix`;
+                return host.detail;
             },
-            remediation: "Use macOS or Linux; WSL and native Windows require separate proof before support.",
+            remediation: host.remediation,
         },
         {
             id: "package-manager",
@@ -594,9 +610,7 @@ export const runRehearsalDoctor = async (options = {}) => {
                         ], {
                             cwd: projectRoot,
                             encoding: "utf8",
-                            env: Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined
-                                ? []
-                                : [[key, process.env[key]]])),
+                            env: createCleanProcessEnvironment(),
                             stdio: ["ignore", "pipe", "pipe"],
                         });
                         if (status.status !== 0 ||
@@ -614,12 +628,9 @@ export const runRehearsalDoctor = async (options = {}) => {
                     const status = spawnSync("supabase", ["status", "-o", "env", "--workdir", paths.runtimeWorkdir], {
                         cwd: projectRoot,
                         encoding: "utf8",
-                        env: {
-                            ...Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined
-                                ? []
-                                : [[key, process.env[key]]])),
-                            ...serviceEnvironment,
-                        },
+                        env: createCleanProcessEnvironment({
+                            overrides: serviceEnvironment,
+                        }),
                         stdio: ["ignore", "pipe", "pipe"],
                     });
                     if (status.status !== 0 ||

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

@@ -0,0 +1,16 @@
+export declare const NATIVE_WINDOWS_REMEDIATION = "Use WSL2, not a native Windows terminal: run wsl --install -d Ubuntu in PowerShell and confirm version 2 with wsl --list --verbose (upgrade with wsl --set-version Ubuntu 2 if needed). Enable Docker Desktop Settings > Resources > WSL integration for that distribution. Keep the project in its Linux home filesystem (for example ~/projects, not /mnt/c), install a supported Linux Node.js version and project tools there, open it with VS Code Remote - WSL, then rerun rehearsal doctor inside WSL2.";
+export interface HostPlatformInspection {
+    readonly kind: "macos" | "linux" | "wsl2" | "wsl-unverified" | "windows" | "other";
+    readonly supported: boolean;
+    readonly detail: string;
+    readonly remediation: string;
+}
+export interface HostPlatformOptions {
+    readonly projectRoot?: string;
+    readonly platform?: NodeJS.Platform;
+    readonly kernelRelease?: string;
+    readonly readKernelRelease?: () => Promise<string>;
+    readonly inspectFilesystem?: (path: string) => Promise<number>;
+}
+export declare const inspectHostPlatform: ({ projectRoot, platform, kernelRelease, readKernelRelease, inspectFilesystem, }?: HostPlatformOptions) => Promise<HostPlatformInspection>;
+export declare const assertSupportedHostPlatform: (options?: HostPlatformOptions) => Promise<void>;

package/dist/src/shared/host_platform.mjs

@@ -0,0 +1,109 @@
+/** Read-only host capability checks; never substitute environment hints for proof. */
+import { open, statfs } from "node:fs/promises";
+import { release } from "node:os";
+import { RehearsalError } from "./diagnostics.mjs";
+export const NATIVE_WINDOWS_REMEDIATION = "Use WSL2, not a native Windows terminal: run wsl --install -d Ubuntu in PowerShell and confirm version 2 with wsl --list --verbose (upgrade with wsl --set-version Ubuntu 2 if needed). Enable Docker Desktop Settings > Resources > WSL integration for that distribution. Keep the project in its Linux home filesystem (for example ~/projects, not /mnt/c), install a supported Linux Node.js version and project tools there, open it with VS Code Remote - WSL, then rerun rehearsal doctor inside WSL2.";
+const readProcKernelRelease = async () => {
+    const file = await open("/proc/sys/kernel/osrelease", "r");
+    try {
+        const buffer = Buffer.alloc(512);
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await file.close();
+    }
+};
+// WSL's Windows drive mounts do not provide the private modes and atomic symlink
+// contract used by baselines. Accept proven Linux filesystem types, not paths.
+const WSL_POSIX_FILESYSTEM_TYPES = new Set([
+    0xef53, // ext2/ext3/ext4 (WSL2 distribution filesystem)
+    0x58465342, // XFS
+    0x9123683e, // Btrfs
+]);
+export const inspectHostPlatform = async ({ projectRoot = process.cwd(), platform = process.platform, kernelRelease = release(), readKernelRelease = readProcKernelRelease, inspectFilesystem = async (path) => (await statfs(path)).type, } = {}) => {
+    if (platform === "darwin") {
+        return {
+            kind: "macos",
+            supported: true,
+            detail: "macOS is in the supported host matrix; project readiness checks still apply.",
+            remediation: "Resolve the remaining project readiness checks on macOS.",
+        };
+    }
+    if (platform === "win32") {
+        return {
+            kind: "windows",
+            supported: false,
+            detail: "Native Windows runtime and preparation operations are unsupported: POSIX private-file, process-group, and atomic baseline-pointer guarantees have not been established.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    if (platform !== "linux") {
+        return {
+            kind: "other",
+            supported: false,
+            detail: "This operating system is outside the verified macOS/Linux runtime contract.",
+            remediation: "Use a supported macOS or Linux environment. Windows users should use WSL2 with the project on its Linux home filesystem and Docker Desktop WSL integration.",
+        };
+    }
+    let procRelease = "";
+    try {
+        procRelease = (await readKernelRelease()).slice(0, 512);
+    }
+    catch {
+        // os.release() is independent kernel evidence when procfs is unavailable.
+    }
+    const evidence = `${kernelRelease.slice(0, 512)}\n${procRelease}`;
+    if (!/microsoft|\bwsl2?\b/iu.test(evidence)) {
+        return {
+            kind: "linux",
+            supported: true,
+            detail: "Linux is in the supported host matrix; project readiness checks still apply.",
+            remediation: "Resolve the remaining project readiness checks on Linux.",
+        };
+    }
+    if (!/microsoft-standard|\bwsl2\b/iu.test(evidence)) {
+        return {
+            kind: "wsl-unverified",
+            supported: false,
+            detail: "A WSL kernel was detected, but WSL2 kernel capabilities were not proven. WSL1 is unsupported.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    let filesystemType = null;
+    try {
+        filesystemType = await inspectFilesystem(projectRoot);
+    }
+    catch {
+        // Unknown filesystem evidence must not be interpreted as POSIX capability.
+    }
+    if (filesystemType === null ||
+        !WSL_POSIX_FILESYSTEM_TYPES.has(filesystemType)) {
+        return {
+            kind: "wsl2",
+            supported: false,
+            detail: "WSL2 was detected, but this project is not on a proven Linux filesystem. Windows drive mounts and unknown filesystem types are unsupported for private baseline data.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    return {
+        kind: "wsl2",
+        supported: true,
+        detail: "WSL2 kernel and a Linux project filesystem were detected. Run in VS Code Remote - WSL with Linux tools and Docker Desktop WSL integration; the remaining readiness and private-file checks still apply.",
+        remediation: NATIVE_WINDOWS_REMEDIATION,
+    };
+};
+export const assertSupportedHostPlatform = async (options = {}) => {
+    const inspection = await inspectHostPlatform(options);
+    if (inspection.supported)
+        return;
+    throw new RehearsalError({
+        category: "unsafe_environment",
+        code: "HOST_PLATFORM_UNSUPPORTED",
+        message: inspection.detail,
+        expected: "A supported macOS/Linux runtime with its existing safety guarantees.",
+        actual: inspection.kind,
+        refused: "No project configuration, child process, or runtime operation was started.",
+        suggestions: [inspection.remediation],
+    });
+};

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;

package/dist/src/shared/operation_guard.mjs

@@ -6,7 +6,7 @@ import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { REHEARSAL_VERSION } from "./diagnostics.mjs";
 import { refreshLiveOperationProgress, } from "./operation_progress_contract.mjs";
-import { archiveOperationProgress, readOwnedOperationProgress, readRecentOperationProgress, writeOwnedOperationProgress, } from "./operation_progress_storage.mjs";
+import { archiveOperationProgress, readOwnedOperationProgress, readOwnedOperationProgressRecord, readRecentOperationHistory, writeOwnedOperationProgress, } from "./operation_progress_storage.mjs";
 const LOCK_ROOT = join(tmpdir(), "rehearsal-db-operation-locks");
 const OPERATION_KINDS = new Set([
     "stop-stale",
@@ -164,7 +164,7 @@ export const acquireProjectOperation = async ({ projectRoot, command, }) => {
                 command,
                 id: digest(token),
                 startedAt: owner.startedAt,
-                async writeProgress(progress) {
+                async writeProgress(progress, migrationFailure) {
                     const current = await readPrivateLockOwner(ownerPath);
                     assertOwnership(current);
                     if (progress.startedAt !== owner.startedAt)
@@ -174,25 +174,29 @@ export const acquireProjectOperation = async ({ projectRoot, command, }) => {
                         token,
                         operationId: digest(token),
                         progress,
+                        ...(migrationFailure === undefined ? {} : { migrationFailure }),
                     });
                 },
                 async release() {
                     const current = await readPrivateLockOwner(ownerPath);
                     assertOwnership(current);
-                    const progress = await readOwnedOperationProgress({
+                    const stored = await readOwnedOperationProgressRecord({
                         lockDirectory,
                         token,
                         operationId: digest(token),
                         startedAt: owner.startedAt,
                     });
-                    if (progress) {
+                    if (stored) {
                         try {
                             await archiveOperationProgress({
                                 projectHash,
                                 operationKinds: OPERATION_KINDS,
                                 kind: command,
                                 rehearsalVersion: REHEARSAL_VERSION,
-                                progress,
+                                progress: stored.progress,
+                                ...(stored.migrationFailure === undefined
+                                    ? {}
+                                    : { migrationFailure: stored.migrationFailure }),
                             });
                         }
                         catch {
@@ -240,7 +244,7 @@ export const acquireProjectOperation = async ({ projectRoot, command, }) => {
     }
     throw new Error("Rehearsal could not acquire its project operation lock.");
 };
-const operationState = (state, owner = null, progress = null, recent = null) => Object.freeze({
+const operationState = (state, owner = null, progress = null, recent = null, recentFailures = null) => Object.freeze({
     schemaVersion: 1,
     state,
     operation: owner
@@ -252,6 +256,7 @@ const operationState = (state, owner = null, progress = null, recent = null) =>
         })
         : null,
     recent,
+    recentFailures,
 });
 export const inspectProjectOperationState = async ({ projectRoot, }) => {
     await assertPrivateLockRoot();
@@ -259,7 +264,7 @@ export const inspectProjectOperationState = async ({ projectRoot, }) => {
     const projectHash = digest(canonicalRoot);
     const lockDirectory = join(LOCK_ROOT, projectHash);
     const ownerPath = join(lockDirectory, "owner.json");
-    const recent = await readRecentOperationProgress({
+    const { recent, recentFailures } = await readRecentOperationHistory({
         projectHash,
         operationKinds: OPERATION_KINDS,
     });
@@ -269,14 +274,14 @@ export const inspectProjectOperationState = async ({ projectRoot, }) => {
     }
     catch (error) {
         if (hasErrorCode(error, "ENOENT"))
-            return operationState("idle", null, null, recent);
+            return operationState("idle", null, null, recent, recentFailures);
         throw error;
     }
     if (!details.isDirectory() ||
         details.isSymbolicLink() ||
         (details.mode & 0o077) !== 0 ||
         (typeof process.getuid === "function" && details.uid !== process.getuid())) {
-        return operationState("invalid", null, null, recent);
+        return operationState("invalid", null, null, recent, recentFailures);
     }
     let owner;
     try {
@@ -284,11 +289,11 @@ export const inspectProjectOperationState = async ({ projectRoot, }) => {
     }
     catch (error) {
         if (hasErrorCode(error, "ENOENT"))
-            return operationState("idle", null, null, recent);
-        return operationState("invalid", null, null, recent);
+            return operationState("idle", null, null, recent, recentFailures);
+        return operationState("invalid", null, null, recent, recentFailures);
     }
     if (owner.projectHash !== projectHash)
-        return operationState("invalid", null, null, recent);
+        return operationState("invalid", null, null, recent, recentFailures);
     const live = processIsAlive(owner.pid);
     const progress = await readOwnedOperationProgress({
         lockDirectory,
@@ -296,7 +301,7 @@ export const inspectProjectOperationState = async ({ projectRoot, }) => {
         operationId: digest(owner.token),
         startedAt: owner.startedAt,
     });
-    return operationState(live ? "busy" : "stale", owner, live && progress ? refreshLiveOperationProgress(progress) : progress, recent);
+    return operationState(live ? "busy" : "stale", owner, live && progress ? refreshLiveOperationProgress(progress) : progress, recent, recentFailures);
 };
 export const inspectProjectOperationLocks = async () => readdir(LOCK_ROOT).catch((error) => {
     if (hasErrorCode(error, "ENOENT"))