@rehearsal-db/core 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,9 +1,60 @@
 # 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.2.0] - 2026-10-24
+
+### Added
+
+- An optional `migrationImpact: 1` contract: offline `inspect impact` and explicitly
+  confirmed `measure impact` for one selected, already-verified disposable local
+  sandbox. Bounded read-only snapshot aggregates cover narrow supported row,
+  populated/NULL, duplicate and foreign-key orphan counts; unsupported or incomplete
+  evidence stays unknown. No pending migration is executed, no runtime is started
+  or repaired, and no SQL, object names or row contents are returned. Counts are
+  not sequential simulation, production prediction or a safety verdict. Existing
+  project locking/cancellation is reused without adding a rehearsal gate or CLI fee.
+- An optional versioned `inspect insights` contract for bounded, read-only static
+  migration warnings. Findings bind to exact pending file bytes and the complete
+  existing candidate digest, with fixed explanations and lexical locations.
+  Unsupported, malformed or truncated analysis remains unknown; no detected
+  warning is never SQL validity, database verification or a safety verdict.
+- Project-local input bounds, unchanged leaf/directory identity checks and shared
+  input hash binding. Inspection neither executes SQL nor starts an engine or
+  contacts a database. Existing migration-plan v1 and failure diagnosis remain
+  separate, unchanged contracts.
+
+### Documentation
+
+- Clarify reviewed PostgreSQL/application/full service dependencies and resource
+  measurement limits without adding service exclusions or a new acceptance gate.
+- Distinguish project runtime hooks from native migration-tool history support.
+
+## [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
 
@@ -815,7 +866,8 @@ 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.2...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

package/COMPATIBILITY.md

@@ -26,12 +26,49 @@ 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.
+
+The 1.2.0 source candidate adds optional capability
+`rehearsalContracts.migrationInsights: 1` and `inspect insights --json`. It preserves
+existing migration-plan v1, baseline formats, digest meaning and failure diagnosis.
+Consumers must check the capability and exact plan/file bindings; absent or
+unavailable static analysis is not safety evidence. This candidate version and its
+setup target do not establish publication or completed editor/native acceptance.
+
+Further source work adds optional `rehearsalContracts.migrationImpact: 1` with
+`inspect impact` and `measure impact`. Consumers must explicitly select a configured
+local target and bind measurement consent to the exact whole-plan digest. Preview
+does not contact a database; measurement reads only the current verified sandbox,
+without applying migrations, starting/repairing a runtime or changing database data.
+Aggregate execution requires PostgreSQL 17 or newer with server-side transaction
+deadlines and narrowly supported ordinary-table/built-in semantics; older servers
+remain unknown, with no automatic database upgrade.
+Supabase measurement uses the ownership-proven local container's built-in
+`supabase_admin` socket role so the fixed disk bound and catalog lock can be enforced.
+It does not promote `postgres`, change grants, load credentials or connect remotely.
+Read-only catalog preflight is separate from the count snapshot. Bounded strong
+relation locks precede that snapshot and temporarily block writers and metadata
+changes in the selected disposable sandbox; this is not a nonblocking query promise.
+Counts are decimal strings or `null` with an explicit unknown reason, never a safety
+verdict, sequential simulation or production prediction. Partial/unknown measurement
+uses `not_ready` with the existing not-ready exit `1`; normal rehearsal gates and existing JSON contracts
+are unchanged. This unpublished source capability does not claim a new editor UI,
+new database family or additional platform/native acceptance.
+Older strict editor activity consumers can reject the new `measure impact` operation
+kind, including a retained completed receipt. Pair this capability with an editor
+consumer explicitly supporting that kind; the CLI does not silently rename the
+operation, relax unknown-kind validation or update an active editor installation.
+
 ## 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.2**;
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.2.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).
 
@@ -198,6 +198,7 @@ Start here:
 - [VS Code extension](docs/vscode.md) — use the project-aware visual workbench
 - [Safe hands-on tutorial](docs/tutorial.md) — try the full flow in a disposable project
 - [Troubleshooting](docs/troubleshooting.md) — fix common setup problems
+- [Updates](docs/updating.md) — update the CLI or extension without resetting data
 - [Next steps](docs/roadmap.md) — see the current product sequence
 
 Reference:
@@ -214,9 +215,12 @@ Reference:
 - [Standalone workflow and security gates](docs/standalone-workflow.md)
 - [Runtime and local identity policies](docs/runtime-policies.md)
 - [Glossary](docs/glossary.md)
-- [Repository architecture](docs/architecture.md)
 - [Stability and the first stable release](docs/stability.md)
-- [Release process](docs/releasing.md)
+
+For maintainers developing and publishing Rehearsal:
+
+- [Repository architecture](docs/architecture.md)
+- [Maintainer release process](docs/releasing.md)
 
 ## Getting support
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "1.0.2",
+    "version": "1.2.0",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -27,6 +27,8 @@
         "resourceInventory": 1,
         "resourceManager": 1,
         "migrationReview": 1,
+        "migrationInsights": 1,
+        "migrationImpact": 1,
         "configurationReview": 1,
         "baselineShape": 1
     },

package/dist/src/cli/arguments.mjs

@@ -150,6 +150,7 @@ export const commandMutatesProject = ({ command, flags, guided, }) => {
         "open",
         "start",
         "migrate",
+        "measure impact",
         "reset",
         "stop",
         "discard",

package/dist/src/cli/basic_command_handlers.mjs

@@ -35,6 +35,9 @@ Commands:
   inspect baseline           Show verified baseline provenance
   inspect migrations         Classify represented, applied, and candidate migrations
   inspect plan               Review ordered migrations, required dependencies, and warnings
+  inspect insights           Review bounded static SQL warnings; never a safety verdict
+  inspect impact             Preview aggregate measurements for one explicit --target
+  measure impact             Measure reviewed aggregates on that running local sandbox
   start                      Start an existing verified local runtime
   migrate --confirm-candidates= Apply the exact candidate suffix without resetting
   reset                      Restore and verify the immutable local baseline
@@ -48,6 +51,7 @@ Commands:
 
 Options: --help, -h --version, -V --json --verbose --debug --plain
          --config=<path> --target=<provider for setup; configured name for runtime>
+         --confirm-candidates=<whole-plan digest for run, migrate, or measure impact>
          --confirm-source-access=<digest> --confirm-source-retirement=<digest>
          --confirm-refresh=<digest>`;
 export const createBasicCommandHandlers = () => [

package/dist/src/cli/editor_command_handlers.mjs

@@ -1,9 +1,33 @@
 /** Versioned, read-only contracts for editor review; never a second runtime engine. */
 import { inspectMigrationReviewPlan } from "../runtime/migration_plan.mjs";
+import { inspectMigrationInsights, renderMigrationInsights, } from "../runtime/migration_insights.mjs";
+import { inspectMigrationImpact, measureMigrationImpact, renderMigrationImpact, } from "../runtime/migration_impact.mjs";
 import { exactCommands, renderedCommand } from "./command_contract.mjs";
 import { applyStopStalePlan, inspectStopStalePlan, stopReviewedStaleTarget, } from "../runtime/stale_environment_plan.mjs";
 import { inspectConfigurationMetadata, reviewConfigurationProposal, } from "../project/configuration_review.mjs";
 export const createEditorCommandHandlers = () => [
+    exactCommands("migration-impact-preview", ["inspect impact"], async ({ planOptions, flags }) => {
+        const data = await inspectMigrationImpact(planOptions, flags.target);
+        return renderedCommand({ data, render: renderMigrationImpact });
+    }),
+    exactCommands("migration-impact-measurement", ["measure impact"], async ({ planOptions, flags }) => {
+        const data = await measureMigrationImpact({
+            options: planOptions,
+            targetName: flags.target,
+            confirmation: flags.confirmation,
+        });
+        const incomplete = ["partial", "unknown"].includes(data.measurementStatus);
+        return renderedCommand({
+            data,
+            render: renderMigrationImpact,
+            status: incomplete ? "not_ready" : "success",
+            ...(incomplete ? { exitCode: 1 } : {}),
+        });
+    }),
+    exactCommands("migration-insights", ["inspect insights"], async ({ planOptions }) => {
+        const data = await inspectMigrationInsights(planOptions);
+        return renderedCommand({ data, render: renderMigrationInsights });
+    }),
     exactCommands("configuration", ["configuration", "configuration review"], async ({ command, planOptions, flags }) => {
         const data = command === "configuration review"
             ? await reviewConfigurationProposal(planOptions, flags.proposalPath ??

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_history.d.mts

@@ -24,7 +24,11 @@ export interface MigrationReplayReceipt {
     entries: MigrationReplayEntry[];
     historySha256: string;
 }
-export declare const readMigrationFileInventory: (directory: URL) => Promise<MigrationFileEntry[]>;
+export declare const readMigrationFileInventory: (directory: URL, options?: {
+    readonly maximumFiles?: number;
+    readonly maximumDirectoryEntries?: number;
+    readonly readBytes?: (path: URL, filename: string) => Promise<Buffer>;
+}) => Promise<MigrationFileEntry[]>;
 export declare const readMigrationSourceBundle: ({ directory, sourceLedger, }: {
     directory: URL;
     sourceLedger: readonly MigrationLedgerEntry[];

package/dist/src/runtime/migration_history.mjs

@@ -4,7 +4,7 @@
  * this module is reusable script infrastructure.
  */
 import { createHash } from "node:crypto";
-import { readFile, readdir } from "node:fs/promises";
+import { opendir, readFile, readdir } from "node:fs/promises";
 const migrationNamePattern = /^(\d{14})_(.+)\.sql$/u;
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
 const canonicalJson = (value) => `${JSON.stringify(value, null, "\t")}\n`;
@@ -32,17 +32,35 @@ const assertOrderedUniqueHistory = (entries, label) => {
     }
     return entries;
 };
-export const readMigrationFileInventory = async (directory) => {
-    const names = (await readdir(directory))
-        .filter((name) => name.endsWith(".sql"))
-        .sort();
+export const readMigrationFileInventory = async (directory, options = {}) => {
+    let names = [];
+    if (options.maximumDirectoryEntries === undefined) {
+        names = (await readdir(directory)).filter((name) => name.endsWith(".sql"));
+    }
+    else {
+        let visited = 0;
+        // Async directory iteration closes its descriptor on success and refusal.
+        // Bounded callers must not allocate an arbitrary directory listing first.
+        for await (const entry of await opendir(directory)) {
+            if (++visited > options.maximumDirectoryEntries)
+                throw new Error("Migration inspection exceeds its bounded directory inventory.");
+            if (entry.name.endsWith(".sql"))
+                names.push(entry.name);
+        }
+    }
+    names.sort();
+    if (options.maximumFiles !== undefined && names.length > options.maximumFiles)
+        throw new Error("Migration inspection exceeds its bounded file inventory.");
     const entries = [];
     for (const filename of names) {
         const match = migrationNamePattern.exec(filename);
         if (!match) {
             throw new Error(`Invalid migration filename in ${directory}: ${filename}`);
         }
-        const bytes = await readFile(new URL(filename, directory));
+        const path = new URL(filename, directory);
+        const bytes = options.readBytes
+            ? await options.readBytes(path, filename)
+            : await readFile(path);
         entries.push({
             version: match[1],
             name: match[2],

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

@@ -0,0 +1,125 @@
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import { type MigrationImpactTask, type MigrationImpactUnknownReason } from "./migration_impact_plan.mjs";
+import { type MigrationImpactCount } from "./migration_impact_queries.mjs";
+import { openMigrationImpactRuntime } from "../targets/migration_impact_runtime.mjs";
+type CountUnknownReason = "unsupported_runtime_metadata" | "unsupported_server_version" | "query_failed" | "lock_timeout" | "statement_timeout" | "total_timeout" | "input_limit";
+interface PreparedEntry {
+    readonly filename: string;
+    readonly sha256: string;
+    readonly tasks: readonly MigrationImpactTask[];
+    readonly unknownReasons: readonly MigrationImpactUnknownReason[];
+}
+declare const prepare: (options: RehearsalConfigPathOptions, targetName: string | undefined) => Promise<{
+    projectRoot: string;
+    target: import("./topology.mjs").RuntimeTopologyTarget & {
+        summary: ReturnType<(inspection: {
+            baselineGenerationId: string;
+            baselineCutoff: string;
+            candidateSha256: string;
+            migrations: {
+                version: string;
+                name: string;
+                filename: string;
+                sha256: string;
+                status: string;
+            }[];
+            definitions: {
+                represented_by_baseline: string;
+                applied_to_current_runtime: string;
+                candidate: string;
+                modified: string;
+                invalid: string;
+            };
+        }) => Readonly<{
+            baselineGenerationId: string;
+            candidateSha256: string;
+            candidateCount: number;
+            candidates: readonly {
+                version: string;
+                name: string;
+                filename: string;
+                sha256: string;
+                status: string;
+            }[];
+        }>>;
+    };
+    baseline: import("../baseline/artifact.mjs").BaselineManifest;
+    entries: PreparedEntry[];
+    binding: string;
+    candidateSha256: string;
+    candidateCount: number;
+}>;
+type Prepared = Awaited<ReturnType<typeof prepare>>;
+declare const reportFor: ({ prepared, measured, counts, reason, snapshotAt, runtimeIdentitySha256, contactedDatabase, }: {
+    prepared: Prepared;
+    measured?: boolean;
+    counts?: readonly MigrationImpactCount[];
+    reason?: CountUnknownReason;
+    snapshotAt?: string | null;
+    runtimeIdentitySha256?: string | null;
+    contactedDatabase?: boolean;
+}) => {
+    schemaVersion: 1;
+    inspectorVersion: string;
+    candidateSha256: string;
+    candidateCount: number;
+    target: {
+        name: string;
+        provider: "postgresql" | "supabase";
+        baselineGenerationId: string;
+        candidateSha256: string;
+    };
+    mode: "measurement" | "preview";
+    measurementStatus: "measured" | "not_required" | "partial" | "planned" | "unknown";
+    snapshotAt: string | null;
+    runtimeIdentitySha256: string | null;
+    entries: {
+        filename: string;
+        sha256: string;
+        coverage: "incomplete" | "recognized_forms";
+        unknownReasons: readonly MigrationImpactUnknownReason[];
+        measurements: {
+            operation: "broad_delete" | "drop_column" | "drop_table" | "new_constraint" | "not_null" | "truncate";
+            metric: "duplicate_rows" | "nulls" | "orphan_rows" | "populated" | "rows";
+            line: number;
+            column: number;
+            evidence: "measured_current_snapshot" | "planned" | "unknown";
+            count: string | null;
+            unknownReason: CountUnknownReason | null;
+        }[];
+    }[];
+    summary: {
+        plannedCount: number;
+        measuredCount: number;
+        unknownMeasurementCount: number;
+        unknownEntryCount: number;
+    };
+    limits: Readonly<{
+        maximumMeasurements: 100;
+        lockTimeoutMilliseconds: 1000;
+        statementTimeoutMilliseconds: 5000;
+        totalTimeoutMilliseconds: 30000;
+        maximumOutputBytes: 131072;
+        maximumScriptBytes: 262144;
+    }>;
+    safety: {
+        appliesMigrations: boolean;
+        startsOrRepairsRuntime: boolean;
+        returnsRowContents: boolean;
+        returnsSqlOrObjectNames: boolean;
+        contactsDatabase: boolean;
+        transaction: "repeatable_read_read_only" | null;
+    };
+    limitation: string;
+};
+export type MigrationImpactReport = ReturnType<typeof reportFor>;
+export declare const inspectMigrationImpact: (options?: RehearsalConfigPathOptions, targetName?: string) => Promise<MigrationImpactReport>;
+export declare const measureMigrationImpact: ({ options, targetName, confirmation, }: {
+    options?: RehearsalConfigPathOptions;
+    targetName?: string | undefined;
+    confirmation?: string | undefined;
+}, implementation?: {
+    openRuntime?: typeof openMigrationImpactRuntime;
+}) => Promise<MigrationImpactReport>;
+export declare const renderMigrationImpact: (report: MigrationImpactReport) => string;
+export {};