@rehearsal-db/core 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,10 +1,66 @@
 # Changelog
 
-All notable Rehearsal package changes will be documented here. The format follows Keep
-a Changelog, and versions will follow Semantic Versioning after the package exists.
+All notable Rehearsal package changes are documented here. The format follows Keep
+a Changelog, and published versions follow Semantic Versioning.
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-10-21
+
+### Added
+
+- Optional read-only runtime privilege expectations for reviewed schemas, tables,
+  sequences and exact function signatures. Required and forbidden effective access is
+  separate from RLS, includes inherited and column-only permissions, and never repairs
+  grants automatically. Existing policies without this field keep their behavior.
+- Document explicit least-privilege Data API grants, forward-only correction and
+  positive/negative API proofs for Supabase's October 30 opt-in table-exposure change.
+
+### Fixed
+
+- Record the Supabase provider in newly written runtime receipts, so inventory can
+  distinguish recorded format/provider compatibility from unknown legacy provenance.
+  Older receipts remain unknown rather than being silently rewritten or reverified.
+- Bound newly generated Supabase project IDs to the provider's 40-character limit
+  with a deterministic suffix. Preserve valid existing identities; reject invalid
+  configured IDs without renaming or adopting resources.
+- Align OS setup helpers with core's Node.js 22, 24 and 26 support. macOS/Linux
+  helpers accept an explicit `REHEARSAL_NODE_PATH`, and missing-Node guidance points
+  to version-manager selection or the official installer without installing an OS tool.
+- Update compatible older CLI installations to the helper's exact current target
+  instead of treating every 1.0.1-or-newer installation as already current.
+
+## [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 +840,10 @@ 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.1.0...HEAD
+[1.1.0]: https://github.com/Ddupasquier/rehearsal-db/compare/v1.0.2...v1.1.0
+[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/COMPATIBILITY.md

@@ -26,12 +26,18 @@ The first `1.0.0` release requires external beta evidence, a support policy and
 settled public API described in [the stability policy](docs/stability.md). Supporting
 additional database families, package managers or operating systems is not implied.
 
-Rehearsal supports maintained even-numbered Node.js release lines that pass its CI
-matrix. Rehearsal 1.0 supports Node.js 22, 24, and 26; Node.js 24 LTS is the recommended
-default and the release-build runtime. End-of-life and odd-numbered Node.js releases are
-not supported. A future release may remove a Node.js line after its upstream end-of-life
+Rehearsal supports the maintained Node.js release lines verified by its existing CI
+matrix: Node.js 22, 24, and 26. Node.js 24 LTS is the recommended default and the
+release-build runtime. End-of-life and unverified future release lines are not
+supported. A future release may remove a Node.js line after its upstream end-of-life
 date, with that change called out in the changelog.
 
+Core 1.1.0's OS helpers accept the same three lines. A terminal or desktop launcher
+that cannot find Node does not mean an installed version is unsupported. Select it
+through the project's existing version manager or use the helper's explicit executable
+path; see [OS setup](installers/README.md). Helpers never install Node or switch a
+project's runtime automatically.
+
 ## Operating systems and execution location
 
 Core 1.0.1's platform boundary distinguishes the computer running VS Code from the

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.1.0**;
 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.
@@ -71,7 +71,7 @@ your migration is intended to change.
 
 Prefer OS-specific files? Use the [Windows / WSL 2](installers/windows/README.md),
 [macOS](installers/macos/README.md) or [Linux](installers/linux/README.md) setup folder.
-These readable helpers require existing Node.js 24 or 26 and check prerequisites by
+These readable helpers accept existing Node.js 22, 24 or 26 and check prerequisites by
 default; installation is an explicit option. They do not install OS tools or start a
 database. See [their exact behavior and release availability](installers/README.md).
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "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/project/configuration_contract.d.mts

@@ -126,6 +126,7 @@ export interface RehearsalConfig {
         protected?: boolean;
         target?: "supabase" | "postgresql";
         applicationUrl?: string;
+        /** Exact lowercase/digit/hyphen ownership ID: 2–40 Supabase, 2–63 PostgreSQL. */
         projectId?: string;
         apiPort?: number;
         databasePort: number;

package/dist/src/project/configuration_normalization.mjs

@@ -9,6 +9,7 @@ import { normalizeResourcePolicy, normalizeRequiredServices, } from "./configura
 import { normalizeConfigurationProfiles } from "./configuration_profiles.mjs";
 import { normalizeApplicationUrls } from "./configuration_application_urls.mjs";
 import { normalizeApplicationActivity } from "./configuration_activity.mjs";
+import { assertRuntimeProjectId } from "./runtime_project_identity.mjs";
 import { assertBoolean, assertCommand, assertDatabaseIdentifier, assertEnvironmentKey, assertEnvironmentReference, assertHttpStatus, assertIdentifier, assertKnownKeys, assertLoopbackUrl, assertNonEmptyString, assertPlainObject, assertPort, assertPostgresImage, assertPositiveInteger, assertRelativePath, assertStringArray, } from "./configuration_validation.mjs";
 const LOOPBACK_HOSTS = new Set(REHEARSAL_DEFAULTS.safety.allowedHosts);
 const SUPPORTED_SUPABASE_OAUTH_PROVIDERS = new Set(["github", "google"]);
@@ -351,7 +352,7 @@ export const normalizeRehearsalConfig = (input) => {
             protected: assertBoolean(runtime.protected ?? false, "config.runtime.protected"),
             target: runtimeTarget,
             applicationUrl: applicationUrls.applicationUrl,
-            projectId: assertNonEmptyString(runtime.projectId ?? REHEARSAL_DEFAULTS.runtime.projectId, "config.runtime.projectId"),
+            projectId: assertRuntimeProjectId(runtime.projectId ?? REHEARSAL_DEFAULTS.runtime.projectId, runtimeTarget),
             ports: Object.freeze(ports),
         }),
         safety: Object.freeze({

package/dist/src/project/configuration_rendering.mjs

@@ -1,4 +1,5 @@
 /** Render reviewed starter configurations without reading or writing a project. */
+import { createRuntimeProjectId } from "./runtime_project_identity.mjs";
 export const renderDetectedConfig = (detected, { applicationUrl = "http://localhost:5175", ports = { api: 58321, database: 58322, studio: 58323 }, } = {}) => `// @ts-check
 /**
  * Rehearsal configuration for ${detected.projectName}.
@@ -132,7 +133,7 @@ export default defineRehearsalConfig({
 		protected: false, // Pin data against reset, run, migrate, discard, and runtime cleanup.
 		target: "supabase",
 		applicationUrl: ${JSON.stringify(applicationUrl)},
-		projectId: "${detected.projectName}-rehearsal",
+		projectId: ${JSON.stringify(createRuntimeProjectId(detected.projectName, "supabase", detected.projectIdSeed))},
 		apiPort: ${ports.api},
 		databasePort: ${ports.database},
 		studioPort: ${ports.studio},
@@ -266,7 +267,7 @@ export default defineRehearsalConfig({
 		protected: false, // Pin data against reset, run, migrate, discard, and runtime cleanup.
 		target: "postgresql",
 		applicationUrl: ${JSON.stringify(applicationUrl)},
-		projectId: "${detected.projectName}-rehearsal",
+		projectId: ${JSON.stringify(createRuntimeProjectId(detected.projectName, "postgresql", detected.projectIdSeed))},
 		databasePort: ${databasePort},
 	},
 

package/dist/src/project/configuration_resolution.mjs

@@ -3,7 +3,6 @@ import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { findRehearsalConfigPath, } from "./configuration_discovery.mjs";
 import { normalizeRehearsalConfig } from "./configuration_normalization.mjs";
-import { assertIdentifier } from "./configuration_validation.mjs";
 export const loadRehearsalConfig = async ({ projectRoot = process.cwd(), configPath, } = {}) => {
     const root = resolve(projectRoot);
     const path = await findRehearsalConfigPath({
@@ -74,7 +73,6 @@ export const loadRehearsalConfig = async ({ projectRoot = process.cwd(), configP
             throw new Error("config.preparation.privacyKey must resolve to a secret file inside config.baseline.artifactDirectory.");
         }
     }
-    assertIdentifier(config.runtime.projectId, "config.runtime.projectId");
     return Object.freeze({
         config,
         configPath: path,

package/dist/src/project/project_detection.d.mts

@@ -1,6 +1,8 @@
 /** Inspect project-local files used to render a conservative starter config. */
 export interface DetectedProject {
     projectName: string;
+    /** Untruncated normalized name keeps shortened new runtime identities distinct. */
+    projectIdSeed?: string;
     packageManager: "npm" | "pnpm" | "yarn";
     hasSupabaseConfig: boolean;
     hasMigrations: boolean;

package/dist/src/project/project_detection.mjs

@@ -31,6 +31,7 @@ export const inspectDetectedProject = async ({ projectRoot = process.cwd(), } =
         "rehearsal-project";
     return {
         projectName,
+        projectIdSeed: normalizedProjectName || projectName,
         packageManager,
         hasSupabaseConfig: await hasPath("supabase/config.toml"),
         hasMigrations: await hasPath("supabase/migrations"),

package/dist/src/project/runtime_project_identity.d.mts

@@ -0,0 +1,5 @@
+/** Preserve exact configured runtime ownership and bound newly generated identities. */
+import type { RehearsalRuntimeTargetId } from "../targets/target.mjs";
+export declare const assertRuntimeProjectId: (value: unknown, target: RehearsalRuntimeTargetId) => string;
+/** Only new setup identities are shortened; valid existing generated IDs stay stable. */
+export declare const createRuntimeProjectId: (projectName: string, target: RehearsalRuntimeTargetId, identitySeed?: string) => string;

package/dist/src/project/runtime_project_identity.mjs

@@ -0,0 +1,41 @@
+/** Preserve exact configured runtime ownership and bound newly generated identities. */
+import { createHash } from "node:crypto";
+import { RehearsalError } from "../shared/diagnostics.mjs";
+import { assertIdentifier, assertNonEmptyString, } from "./configuration_validation.mjs";
+const maximumProjectIdLength = (target) => target === "supabase" ? 40 : 63;
+export const assertRuntimeProjectId = (value, target) => {
+    const projectId = assertNonEmptyString(value, "config.runtime.projectId");
+    const maximumLength = maximumProjectIdLength(target);
+    if (projectId.length < 2 || projectId.length > maximumLength) {
+        const provider = target === "supabase" ? "Supabase" : "PostgreSQL";
+        throw new RehearsalError({
+            category: "configuration_invalid",
+            code: "CONFIGURATION_INVALID",
+            message: `config.runtime.projectId must contain 2–${maximumLength} characters for ${provider}.`,
+            expected: `2–${maximumLength} lowercase letters, digits, or hyphens`,
+            actual: { length: projectId.length },
+            context: { field: "runtime.projectId", target, maximumLength },
+            refused: "No runtime was started or renamed. Rehearsal never truncates a configured project ID or adopts resources by prefix.",
+            suggestions: [
+                "Choose a distinct, explicitly reviewed ID for a new disposable runtime. Review existing resources before changing their configured identity.",
+            ],
+        });
+    }
+    return assertIdentifier(projectId, "config.runtime.projectId");
+};
+/** Only new setup identities are shortened; valid existing generated IDs stay stable. */
+export const createRuntimeProjectId = (projectName, target, identitySeed = projectName) => {
+    const candidate = `${projectName}-rehearsal`;
+    const maximumLength = maximumProjectIdLength(target);
+    if (candidate.length <= maximumLength)
+        return assertRuntimeProjectId(candidate, target);
+    const digest = createHash("sha256")
+        .update(`${identitySeed}-rehearsal`)
+        .digest("hex")
+        .slice(0, 12);
+    const suffix = `-${digest}-rehearsal`;
+    const prefix = projectName
+        .slice(0, maximumLength - suffix.length)
+        .replace(/-+$/u, "");
+    return assertRuntimeProjectId(`${prefix}${suffix}`, target);
+};

package/dist/src/project/setup.mjs

@@ -8,6 +8,7 @@ import { access, mkdir, open, readFile, rename, rm, writeFile, } from "node:fs/p
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, renderDetectedConfig, renderDetectedPostgresqlConfig, } from "./configuration.mjs";
 import { resolveRuntimeTarget } from "../targets/target.mjs";
+import { createRuntimeProjectId } from "./runtime_project_identity.mjs";
 export { assertSupportedRehearsalNodeRuntime, inspectRehearsalNodeRuntime, } from "../shared/node_runtime.mjs";
 import { assertSupportedRehearsalNodeRuntime } from "../shared/node_runtime.mjs";
 const CONFIG_PATH = "rehearsal.config.mjs";
@@ -257,7 +258,8 @@ export const planRehearsalSetup = async ({ projectRoot = process.cwd(), configPa
             ...(isPortAvailable ? { isAvailable: isPortAvailable } : {}),
         });
     const applicationUrl = existing?.config.runtime.applicationUrl ?? "http://localhost:5175";
-    const projectId = existing?.config.runtime.projectId ?? `${detected.projectName}-rehearsal`;
+    const projectId = existing?.config.runtime.projectId ??
+        createRuntimeProjectId(detected.projectName, runtimeTarget, detected.projectIdSeed);
     const sourceSupabaseConfig = runtimeTarget === "supabase"
         ? await readOptionalFile(join(root, "supabase/config.toml"))
         : null;

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;