@rehearsal-db/core 1.1.0 → 1.3.0

package/dist/src/targets/migration_impact_runtime.mjs

@@ -0,0 +1,367 @@
+/** Private non-starting transport for one explicitly selected owned local runtime. */
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { lstat, open, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { isLocalDockerEndpoint } from "../runtime/local_docker_context.mjs";
+import { diagnoseMigrationFailure } from "../runtime/migration_failure.mjs";
+import { holdPathAncestry } from "../shared/held_path_ancestry.mjs";
+import { runOwnedProcess } from "../shared/owned_process.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
+import { assertDockerResourceLabels } from "./docker_resource_ownership.mjs";
+export class MigrationImpactRuntimeError extends Error {
+    reason;
+    constructor(reason) {
+        super("The selected local runtime could not complete bounded read-only inspection; private output withheld.");
+        this.reason = reason;
+        this.name = "MigrationImpactRuntimeError";
+    }
+}
+const INSPECTION_BYTES = 65536;
+const SQL_INPUT_BYTES = 262144;
+const SQL_OUTPUT_BYTES = 131072;
+function fail(reason) {
+    throw new MigrationImpactRuntimeError(reason);
+}
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const object = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail("runtime_unavailable");
+    return value;
+};
+const inside = (root, path) => {
+    const child = relative(root, path);
+    return (child !== "" &&
+        child !== ".." &&
+        !child.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+        !isAbsolute(child));
+};
+const CONTAINER_FORMAT = '{"id":{{json .Id}},"name":{{json .Name}},"image":{{json .Config.Image}},"imageId":{{json .Image}},"labels":{{json .Config.Labels}},"running":{{json .State.Running}},"ports":{{json .NetworkSettings.Ports}}}';
+/** No lifecycle, adapter, source-reader, URL or credential-file access is permitted here. */
+export async function openMigrationImpactRuntime(options) {
+    const { target, baseline } = options;
+    const signal = options.signal ?? AbortSignal.timeout(30000);
+    const run = options.runProcessImplementation ?? runOwnedProcess;
+    const cancelled = () => {
+        if (signal.aborted)
+            fail("cancelled");
+    };
+    cancelled();
+    const provider = target.config.runtime.target;
+    const projectId = target.config.runtime.projectId;
+    const postgres = provider === "postgresql" ? target.config.postgresql : null;
+    const databasePort = target.config.runtime.ports.database;
+    if (!["postgresql", "supabase"].includes(provider) ||
+        (provider === "postgresql" && !postgres))
+        fail("ownership_mismatch");
+    const dataSha256 = baseline.files["sanitized-data.ndjson"]?.sha256;
+    if (!/^[a-f0-9]{64}$/u.test(dataSha256 ?? "") ||
+        !/^\d{8}T\d{6}Z-[a-f0-9]{12}$/u.test(baseline.generationId))
+        fail("stale_runtime");
+    let root, receiptDirectory;
+    try {
+        root = await realpath(resolve(options.projectRoot));
+        const lexicalRoot = resolve(options.projectRoot), configured = resolve(target.paths.runtimeWorkdir);
+        receiptDirectory = inside(lexicalRoot, configured)
+            ? resolve(root, relative(lexicalRoot, configured))
+            : configured;
+        if (!inside(root, receiptDirectory) ||
+            (await realpath(receiptDirectory)) !== receiptDirectory)
+            fail("ownership_mismatch");
+    }
+    catch {
+        fail("ownership_mismatch");
+    }
+    const readReceipt = async () => {
+        cancelled();
+        let ancestry;
+        try {
+            ancestry = await holdPathAncestry(receiptDirectory);
+            await ancestry.assertUnchanged();
+            const path = join(ancestry.path, "baseline.json"), leaf = await lstat(path, { bigint: true });
+            if (!leaf.isFile() ||
+                leaf.isSymbolicLink() ||
+                leaf.size > BigInt(INSPECTION_BYTES) ||
+                (leaf.mode & 63n) !== 0n ||
+                (typeof process.getuid === "function" &&
+                    leaf.uid !== BigInt(process.getuid())))
+                fail("stale_runtime");
+            const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const before = await handle.stat({ bigint: true });
+                if (!before.isFile() ||
+                    before.dev !== leaf.dev ||
+                    before.ino !== leaf.ino ||
+                    before.size !== leaf.size ||
+                    before.mtimeNs !== leaf.mtimeNs ||
+                    before.ctimeNs !== leaf.ctimeNs)
+                    fail("stale_runtime");
+                const bytes = Buffer.alloc(Number(before.size) + 1);
+                let length = 0;
+                while (length < bytes.length) {
+                    const next = await handle.read(bytes, length, bytes.length - length, length);
+                    if (!next.bytesRead)
+                        break;
+                    length += next.bytesRead;
+                }
+                const after = await handle.stat({ bigint: true }), current = await lstat(path, { bigint: true });
+                if (BigInt(length) !== before.size ||
+                    !current.isFile() ||
+                    current.isSymbolicLink() ||
+                    [after, current].some((stat) => stat.dev !== before.dev ||
+                        stat.ino !== before.ino ||
+                        stat.size !== before.size ||
+                        stat.mtimeNs !== before.mtimeNs ||
+                        stat.ctimeNs !== before.ctimeNs))
+                    fail("stale_runtime");
+                await ancestry.assertUnchanged();
+                const contents = bytes.subarray(0, length);
+                const marker = object(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(contents)));
+                if (marker.target !== provider ||
+                    marker.generationId !== baseline.generationId ||
+                    marker.dataSha256 !== dataSha256 ||
+                    (postgres
+                        ? marker.formatVersion !== 1 ||
+                            marker.image !== postgres.image ||
+                            typeof marker.databasePassword !== "string" ||
+                            marker.databasePassword.length < 32
+                        : marker.formatVersion !== baseline.formatVersion ||
+                            marker.schemaSha256 !==
+                                (baseline.files["production-schema.sql"]?.sha256 ?? null)))
+                    fail("stale_runtime");
+                return {
+                    sha256: digest(contents),
+                    inode: `${before.dev}:${before.ino}:${before.ctimeNs}:${before.mtimeNs}`,
+                };
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (error instanceof MigrationImpactRuntimeError)
+                throw error;
+            fail("stale_runtime");
+        }
+        finally {
+            try {
+                await ancestry?.close();
+            }
+            catch {
+                cancelled();
+                fail("stale_runtime");
+            }
+        }
+    };
+    const initialReceipt = await readReceipt();
+    let endpoint;
+    const invoke = async (args, input) => {
+        cancelled();
+        const maximum = input === undefined ? INSPECTION_BYTES : SQL_OUTPUT_BYTES;
+        try {
+            const result = await run({
+                command: "docker",
+                args,
+                cwd: root,
+                env: createCleanProcessEnvironment({
+                    overrides: { DOCKER_HOST: endpoint },
+                }),
+                signal,
+                stdin: "ignore",
+                ...(input === undefined ? {} : { input }),
+                maxOutputBytes: maximum,
+                cancellationGraceMs: 1000,
+            });
+            cancelled();
+            if (typeof result.stdout !== "string" ||
+                typeof result.stderr !== "string" ||
+                !Number.isSafeInteger(result.stdoutByteCount) ||
+                !Number.isSafeInteger(result.stderrByteCount) ||
+                result.stdoutByteCount < Buffer.byteLength(result.stdout) ||
+                result.stderrByteCount < Buffer.byteLength(result.stderr) ||
+                result.stdoutByteCount > maximum ||
+                result.stderrByteCount > INSPECTION_BYTES ||
+                (input === undefined &&
+                    result.stdoutByteCount + result.stderrByteCount > INSPECTION_BYTES))
+                fail(input === undefined ? "runtime_unavailable" : "query_failed");
+            if (result.error || result.signal || result.status !== 0) {
+                if (input !== undefined) {
+                    const code = diagnoseMigrationFailure({
+                        provider: "postgresql",
+                        stderr: result.stderr,
+                    }).sqlState;
+                    if (code === "55P03")
+                        fail("lock_timeout");
+                    if (code === "57014")
+                        fail("statement_timeout");
+                    if (code === "25P04")
+                        fail("transaction_timeout");
+                }
+                fail(input === undefined ? "runtime_unavailable" : "query_failed");
+            }
+            return result.stdout;
+        }
+        catch (error) {
+            cancelled();
+            if (error instanceof MigrationImpactRuntimeError)
+                throw error;
+            fail(input === undefined ? "runtime_unavailable" : "query_failed");
+        }
+    };
+    const parse = (text) => {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            fail("runtime_unavailable");
+        }
+    };
+    const context = (await invoke(["context", "show"])).trim();
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/u.test(context))
+        fail("ownership_mismatch");
+    const selected = parse(await invoke([
+        "context",
+        "inspect",
+        "--format",
+        "{{json .Endpoints.docker.Host}}",
+        context,
+    ]));
+    if (!isLocalDockerEndpoint(selected))
+        fail("ownership_mismatch");
+    endpoint = selected;
+    const engineId = async () => {
+        const value = parse(await invoke(["info", "--format", "{{json .ID}}"]));
+        if (typeof value !== "string" || !/^[a-zA-Z0-9:-]{1,128}$/u.test(value))
+            fail("runtime_unavailable");
+        return value;
+    };
+    const engine = await engineId();
+    const expectedName = postgres
+        ? `${projectId}-postgresql`
+        : `supabase_db_${projectId}`;
+    const inspect = async (id) => {
+        const value = object(parse(await invoke([
+            "container",
+            "inspect",
+            "--format",
+            CONTAINER_FORMAT,
+            id,
+        ])));
+        if (typeof value.id !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(value.id) ||
+            value.name !== `/${expectedName}` ||
+            value.running !== true ||
+            typeof value.imageId !== "string" ||
+            !/^sha256:[a-f0-9]{64}$/u.test(value.imageId))
+            fail("runtime_unavailable");
+        try {
+            assertDockerResourceLabels({
+                labels: value.labels,
+                expectedLabel: postgres
+                    ? "com.rehearsal-db.project"
+                    : "com.supabase.cli.project",
+                projectId,
+            });
+        }
+        catch {
+            fail("ownership_mismatch");
+        }
+        if (postgres) {
+            const ports = object(value.ports), mappings = ports["5432/tcp"];
+            if (value.image !== postgres.image ||
+                !Array.isArray(mappings) ||
+                mappings.length !== 1)
+                fail("ownership_mismatch");
+            const mapping = object(mappings[0]);
+            if (mapping.HostIp !== "127.0.0.1" ||
+                mapping.HostPort !== String(databasePort))
+                fail("ownership_mismatch");
+        }
+        return { id: value.id, imageId: value.imageId };
+    };
+    const container = await inspect(expectedName);
+    const assertCurrent = async () => {
+        cancelled();
+        const currentReceipt = await readReceipt();
+        if (currentReceipt.sha256 !== initialReceipt.sha256 ||
+            currentReceipt.inode !== initialReceipt.inode)
+            fail("stale_runtime");
+        if ((await engineId()) !== engine)
+            fail("stale_runtime");
+        const current = await inspect(container.id);
+        if (current.id !== container.id || current.imageId !== container.imageId)
+            fail("stale_runtime");
+        const finalReceipt = await readReceipt();
+        if (finalReceipt.sha256 !== initialReceipt.sha256 ||
+            finalReceipt.inode !== initialReceipt.inode)
+            fail("stale_runtime");
+    };
+    await assertCurrent();
+    return Object.freeze({
+        identitySha256: digest(JSON.stringify({
+            endpoint,
+            engine,
+            container,
+            receipt: initialReceipt.sha256,
+            provider,
+            projectId,
+            generation: baseline.generationId,
+        })),
+        assertCurrent,
+        runSql: async (input) => {
+            // Compile the remaining server deadline only after the final potentially
+            // slow Docker/receipt preflight. Never rewrite a caller's SQL text.
+            if (typeof input === "function")
+                await assertCurrent();
+            const sql = typeof input === "function" ? input() : input;
+            if (typeof sql !== "string" ||
+                Buffer.byteLength(sql) > SQL_INPUT_BYTES ||
+                sql.length === 0 ||
+                sql.includes("\0"))
+                fail("query_failed");
+            if (typeof input !== "function")
+                await assertCurrent();
+            let result = "", failure;
+            try {
+                // Docker exec inherits container variables unless env -i clears them;
+                // force a local socket so PGHOSTADDR/service/options cannot redirect it.
+                result = await invoke([
+                    "exec",
+                    "--interactive",
+                    container.id,
+                    "/usr/bin/env",
+                    "-i",
+                    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+                    "PGSSLMODE=disable",
+                    "PGPASSFILE=/dev/null",
+                    "psql",
+                    "--no-psqlrc",
+                    "--no-password",
+                    "--host=/var/run/postgresql",
+                    "--port=5432",
+                    "--quiet",
+                    "--no-align",
+                    "--tuples-only",
+                    "--set",
+                    "ON_ERROR_STOP=1",
+                    "--set",
+                    "VERBOSITY=sqlstate",
+                    "--username",
+                    // Supabase's application-facing postgres role is NOSUPERUSER.
+                    // The fixed disk bound and namespace lock require its built-in
+                    // local administrator; no role changes or credentials are needed.
+                    postgres?.user ?? "supabase_admin",
+                    "--dbname",
+                    postgres?.database ?? "postgres",
+                ], sql);
+            }
+            catch (error) {
+                failure = error;
+            }
+            await assertCurrent();
+            if (failure)
+                throw failure;
+            return result;
+        },
+    });
+}

package/docs/README.md

@@ -10,17 +10,26 @@ applies only the exact migrations you approve, and runs your application's own p
 You do not need to read this documentation from top to bottom. Choose what you want to
 accomplish and follow that path.
 
-## Start here
+## Getting started
+
+Install Rehearsal, rehearse a migration, understand the result and fix a failure.
 
 | Your goal                           | Best next page                        |
 | ----------------------------------- | ------------------------------------- |
 | Add Rehearsal to a project          | [Getting started](getting-started.md) |
 | Use the visual database workbench   | [VS Code extension](vscode.md)        |
 | Try it in a disposable project      | [Hands-on tutorial](tutorial.md)      |
+| Update an existing installation     | [Releases and updates](updating.md)   |
 | Fix a setup or runtime problem      | [Troubleshooting](troubleshooting.md) |
 | Browse the friendlier web-docs home | [Documentation home](index.md)        |
 
-## Work safely
+## User reference
+
+Look up only what you need for your next decision. Start with
+[supported environments](https://github.com/Ddupasquier/rehearsal-db/blob/main/COMPATIBILITY.md),
+[configuration](configuration.md) or [troubleshooting](troubleshooting.md).
+
+### Data safety
 
 - [Baselines](baselines.md) — the verified starting copy
 - [Sanitization](sanitization.md) — what may enter that copy
@@ -28,7 +37,7 @@ accomplish and follow that path.
 - [Security model](security-model.md) — the independent safety barriers
 - [Standalone workflow](standalone-workflow.md) — the complete declarative contract
 
-## Look something up
+### Commands and settings
 
 - [CLI commands](commands.md)
 - [Configuration](configuration.md)
@@ -37,13 +46,17 @@ accomplish and follow that path.
 - [Runtime and identity policies](runtime-policies.md)
 - [Database adapters](adapters.md)
 - [Glossary](glossary.md)
+- [Roadmap](roadmap.md)
 
-## Follow the project
+## Maintainers
+
+These pages explain developing and publishing Rehearsal itself, not using it in
+your application. Installing or updating does not require the publisher checklist.
 
-- [Roadmap](roadmap.md)
-- [Stability and release verification](stability.md)
 - [Repository architecture](architecture.md)
-- [Release process](releasing.md)
+- [Building and testing](https://github.com/Ddupasquier/rehearsal-db/blob/main/CONTRIBUTING.md)
+- [Release verification](stability.md)
+- [Maintainers: publishing Rehearsal](releasing.md)
 
 To preview the styled documentation locally, run `npm run docs:preview`, then open the
 address it prints.

package/docs/adapters.md

@@ -35,3 +35,13 @@ adapter responsibility.
 Keep adapters small, deterministic, tested, and visibly project-owned. If a behavior is
 generic across unrelated projects, propose it for the engine instead of copying it into
 every adapter.
+
+## Migration-tool histories are a separate contract
+
+Project runtime hooks do not add Prisma, Drizzle, Knex, Django or Alembic support.
+The current timestamped-SQL inventory and Rehearsal/Supabase migration ledger must
+not be presented as native compatibility with those tools. Do not flatten native
+migration directories, rewrite an applied ledger or use a schema-push shortcut to
+fit this adapter API. Versioned native history, exact review and owned-target
+execution belong to the separate core integration tracked by
+[issue #174](https://github.com/Ddupasquier/rehearsal-db/issues/174).

package/docs/architecture.md

@@ -39,6 +39,23 @@ rehearsal-db/
 - Public consumers use only the paths declared in `package.json#exports`.
 - Unit tests mirror their source domain. Cross-domain workflows belong in
   `tests/integration/`; durable public promises belong in `tests/contracts/`.
+- `tests/helpers/public_cli.mjs` bounds setup-test child output and projects only
+  fixed failure categories, exit/signal metadata and recognized setup refusal kinds.
+  It never retains raw child errors, argv, provider text or output in failure reports.
+  An unrecognized failure stays unclassified; a later green test does not establish
+  the cause of a historical failure. This test helper is not shipped product code.
+
+## Documentation audiences
+
+Site navigation separates Getting started, User reference and Maintainers. Installation,
+rehearsal, results and failure recovery belong in the first journey; configuration,
+supported environments, troubleshooting and data safety belong in reference. Keep
+deletion, production-access and unsupported-behavior warnings visible to users.
+
+`docs/updating.md` answers release changes, compatibility, updating, breaking changes
+and origin verification with links to deeper owners. Build, test and publishing details
+belong in maintainer guidance, not installation prerequisites. `docs/releasing.md` owns
+current publishing controls; historical incidents stay in release and issue history.
 
 ## CLI modules
 
@@ -60,9 +77,19 @@ typed registry and produce the same result contract:
   `update_advisory.mts` bounds public release metadata, private preferences and
   installation-origin checks. Neither participates in passive JSON inspection.
 - `runtime_commands.mts` coordinates local runtimes and project proofs.
+- `runtime_stack_runner.mts` selects configured targets, binds their reviewed engine
+  and configuration identities, executes the serial stack and retains receipt-bound
+  cleanup. `runtime_workload_admission.mts` applies optional lifecycle admission before
+  that work; application proofs and interactive sessions are deliberately outside it.
+- `workload_command_handlers.mts` exposes local queue inspection and exact dead-holder
+  metadata recovery without a project lock or Docker. `runtime/workload_queue.mts`
+  owns cooperative lifecycle admission; its store owns bounded private atomic tickets,
+  and its location helper binds the local user, boot and PID namespace independently
+  of per-command temporary directories. No background scheduler is installed.
 - `runtime_planning.mts` owns read-only stack plans and exact candidate summaries.
 - `editor_command_handlers.mts` exposes bounded migration and configuration review
-  contracts plus digest-bound, non-destructive stale-environment stop review.
+  contracts plus digest-bound, non-destructive stale-environment stop review. It also
+  keeps impact preview/measurement dispatch thin; aggregate policy stays in runtime.
 - `source_commands.mts` coordinates approved source access and refresh.
 - `renderers.mts` formats human-readable results without changing state.
 - `terminal.mts` owns prompts, colors, and terminal exit behavior.
@@ -98,6 +125,62 @@ handler-family module at 350 lines or fewer. A new command belongs in the narrow
 existing family, or in a new focused family when it represents a genuinely separate
 responsibility.
 
+Static Migration Insights has a separate additive contract from migration-plan v1 and
+post-failure SQLSTATE diagnosis. `runtime/migration_insights_input.mts` owns bounded
+regular-file reads and private exact-input text; the existing inventory, baseline-prefix
+and topology owners still calculate the candidate digest. Repeated shared-directory
+inputs must keep the same raw hash; findings retrieve text only by its expected hash.
+`shared/held_path_ancestry.mts` retains canonical directory identities and timestamps
+to refuse detected concurrent ancestry changes. This is not atomic `openat` resolution
+or a filesystem sandbox; leaf checks and existing workspace trust remain necessary.
+`migration_sql_lexer.mts` and
+`migration_sql_scan.mts` own bounded lexical positions and fixed review hints, not SQL
+validation. `migration_insights.mts` alone projects redacted public findings and explicit
+coverage/unknown states. The editor consumes that contract; it must not reimplement SQL
+analysis or infer runtime measurements from static warnings.
+
+Migration impact is a separate optional contract, not a new rehearsal gate.
+`runtime/migration_impact_plan.mts` recognizes only bounded simple SQL forms and retains
+private relation/column specifications; it does not execute migrations or claim SQL
+validity. `migration_impact_queries.mts` validates those specifications and generates
+fixed, identifier-quoted aggregate queries. `migration_impact_catalog.mts` owns the
+closed native index, statistics and operator-family predicates. Metadata checks refuse unsupported
+table, type and operator semantics; public output contains count strings or explicit
+unknowns, never those private specifications, SQL, object names or row contents.
+`migration_impact.mts` binds preview and measurement reports to the whole candidate
+digest, selected target, immutable baseline and exact input bytes. It rechecks the
+binding after measurement and never interprets current counts as sequential migration
+simulation or a production prediction.
+
+`targets/migration_impact_runtime.mts` owns access to an already-running, verified,
+ownership-proven local sandbox and its unchanged identity. It does not start/repair
+an engine, reset data or apply migrations. Measurement uses one read-only repeatable
+read count transaction with bounded locks, statements, output and total duration.
+The environment-scrubbed client connects only through the proven owned container's
+fixed local socket. PostgreSQL uses its configured local owner; Supabase uses its
+built-in `supabase_admin`, not the restricted application-facing `postgres` role.
+The fixed temporary-file bound and namespace-catalog lock require that local
+administrator. No grants, role promotion, password access, network connection or
+caller-selected SQL is added; the same read-only compiler and metadata refusals apply.
+A separate read-only catalog preflight retains relation OIDs; globally ordered
+`SHARE ROW EXCLUSIVE` locks precede the first repeatable-read snapshot, preventing
+index/statistics DDL from outrunning its metadata checks. Counts recheck the retained
+OIDs and supported semantics after locking. A concurrent name-to-view swap can
+transiently lock view dependencies within the selected sandbox, but cannot make the
+compiler execute that view query or return its counts. This is not atomic name/OID
+resolution or a sandbox for a compromised database server. The private transport
+also takes a bounded database-local namespace-catalog `SHARE` lock before relation
+name resolution, preventing schema rename/swap during checks and aggregates.
+This can temporarily block schema-catalog changes anywhere in that selected
+disposable database; it does not change another database or acquire a cluster-wide lock.
+The transport invokes the script compiler after final identity preflight so a slow check cannot
+leave an earlier, larger server deadline embedded in the submitted script. The CLI
+classifies `measure impact` for the existing project-operation lock and cancellation
+owner despite the SQL being read-only; operation metadata/history may be written.
+`inspect impact` is an offline preview. Both require one explicit configured target;
+measurement additionally requires the exact whole-plan confirmation. Neither command
+is a prerequisite for ordinary `run` or `migrate`, and both remain free CLI features.
+
 ## Configuration pipeline
 
 The stable `project/configuration.mts` facade keeps existing imports compatible while