@rehearsal-db/core 1.0.2 → 1.2.0

package/dist/src/runtime/privileges.mjs

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

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

@@ -36,7 +36,7 @@ declare const candidateSummary: (inspection: MigrationInspection) => Readonly<{
         status: string;
     }[];
 }>;
-export declare const inspectRuntimeTopologyCandidates: (options?: RehearsalConfigPathOptions) => Promise<Readonly<{
+export declare const inspectRuntimeTopologyCandidates: (options?: RehearsalConfigPathOptions, inspectMigrations?: typeof inspectRehearsalMigrations) => Promise<Readonly<{
     topology: Readonly<{
         projectRoot: string;
         primary: RuntimeTopologyTarget;

package/dist/src/runtime/topology.mjs

@@ -103,13 +103,13 @@ const candidateSummary = (inspection) => {
         candidates: Object.freeze(candidates),
     });
 };
-export const inspectRuntimeTopologyCandidates = async (options = {}) => {
+export const inspectRuntimeTopologyCandidates = async (options = {}, inspectMigrations = inspectRehearsalMigrations) => {
     const topology = await loadRuntimeTopology(options);
     const targets = [];
     for (const target of topology.targets) {
         targets.push(Object.freeze({
             ...target,
-            summary: candidateSummary(await inspectRehearsalMigrations({
+            summary: candidateSummary(await inspectMigrations({
                 projectRoot: topology.projectRoot,
                 configPath: target.configPath,
             })),

package/dist/src/shared/cancellation.mjs

@@ -9,6 +9,7 @@ export const OPERATION_CANCELLATION_SIGNALS = [
 ];
 const CANCELLABLE_COMMANDS = new Set([
     "migrate",
+    "measure impact",
     "open",
     "refresh",
     "reset",

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

@@ -0,0 +1,7 @@
+export declare const HELD_PATH_ANCESTRY_MAXIMUM_DIRECTORIES = 128;
+export interface HeldPathAncestry {
+    readonly path: string;
+    assertUnchanged(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare const holdPathAncestry: (directory: string) => Promise<HeldPathAncestry>;

package/dist/src/shared/held_path_ancestry.mjs

@@ -0,0 +1,110 @@
+/**
+ * Timestamp-based concurrent-change guard for a canonical directory ancestry.
+ * This is not atomic openat resolution or a sandbox: it cannot prevent every
+ * transient access or privileged timestamp manipulation. Callers retain their
+ * own project-containment, regular-file and exact-input identity checks, use
+ * only `path` for reads, assert before/after those reads, and close in finally.
+ */
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+export const HELD_PATH_ANCESTRY_MAXIMUM_DIRECTORIES = 128;
+const unavailable = () => new Error("Path ancestry is unavailable, unsafe or changed.");
+const identity = (details) => {
+    if (!details.isDirectory() ||
+        details.isSymbolicLink() ||
+        typeof details.dev !== "bigint" ||
+        typeof details.ino !== "bigint" ||
+        typeof details.ctimeNs !== "bigint" ||
+        typeof details.mtimeNs !== "bigint")
+        throw unavailable();
+    return {
+        dev: details.dev,
+        ino: details.ino,
+        ctimeNs: details.ctimeNs,
+        mtimeNs: details.mtimeNs,
+    };
+};
+const same = (left, right) => left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.ctimeNs === right.ctimeNs &&
+    left.mtimeNs === right.mtimeNs;
+export const holdPathAncestry = async (directory) => {
+    const handles = [];
+    const entries = [];
+    let closed = false;
+    let closing;
+    const close = () => {
+        if (closing)
+            return closing;
+        closed = true;
+        closing = (async () => {
+            let failed = false;
+            for (const handle of handles.splice(0).reverse()) {
+                try {
+                    await handle.close();
+                }
+                catch {
+                    failed = true;
+                }
+            }
+            if (failed)
+                throw unavailable();
+        })();
+        return closing;
+    };
+    try {
+        if (!isAbsolute(directory))
+            throw unavailable();
+        const path = resolve(directory);
+        const root = parse(path).root;
+        const segments = relative(root, path).split(sep).filter(Boolean);
+        if (segments.length + 1 > HELD_PATH_ANCESTRY_MAXIMUM_DIRECTORIES)
+            throw unavailable();
+        // Reject aliases and all symlink ancestors, including ancestors above the
+        // caller's project root. Root aliases must be canonicalized by the caller.
+        if ((await realpath(path)) !== path)
+            throw unavailable();
+        const paths = [root];
+        for (const segment of segments)
+            paths.push(join(paths.at(-1), segment));
+        for (const current of paths) {
+            const before = identity(await lstat(current, { bigint: true }));
+            const handle = await open(current, constants.O_RDONLY |
+                constants.O_DIRECTORY |
+                constants.O_NOFOLLOW |
+                constants.O_NONBLOCK);
+            // Retain immediately: a later stat failure must still close this handle.
+            handles.push(handle);
+            const opened = identity(await handle.stat({ bigint: true }));
+            const after = identity(await lstat(current, { bigint: true }));
+            if (!same(before, opened) || !same(before, after))
+                throw unavailable();
+            entries.push({ path: current, handle, identity: before });
+        }
+        const assertUnchanged = async () => {
+            try {
+                if (closed || (await realpath(path)) !== path)
+                    throw unavailable();
+                for (const entry of entries) {
+                    const held = identity(await entry.handle.stat({ bigint: true }));
+                    const lexical = identity(await lstat(entry.path, { bigint: true }));
+                    if (!same(entry.identity, held) || !same(entry.identity, lexical))
+                        throw unavailable();
+                }
+                if ((await realpath(path)) !== path)
+                    throw unavailable();
+            }
+            catch {
+                await close().catch(() => { });
+                throw unavailable();
+            }
+        };
+        await assertUnchanged();
+        return Object.freeze({ path, assertUnchanged, close });
+    }
+    catch {
+        await close().catch(() => { });
+        throw unavailable();
+    }
+};

package/dist/src/shared/operation_guard.mjs

@@ -21,6 +21,7 @@ const OPERATION_KINDS = new Set([
     "identity connect",
     "init",
     "migrate",
+    "measure impact",
     "open",
     "privacy key",
     "refresh",

package/dist/src/targets/migration_impact_runtime.d.mts

@@ -0,0 +1,22 @@
+import type { BaselineManifest } from "../baseline/artifact.mjs";
+import type { RuntimeTopologyTarget } from "../runtime/topology.mjs";
+import { runOwnedProcess } from "../shared/owned_process.mjs";
+export type MigrationImpactRuntimeFailureReason = "runtime_unavailable" | "ownership_mismatch" | "stale_runtime" | "query_failed" | "lock_timeout" | "statement_timeout" | "transaction_timeout" | "cancelled";
+export declare class MigrationImpactRuntimeError extends Error {
+    readonly reason: MigrationImpactRuntimeFailureReason;
+    constructor(reason: MigrationImpactRuntimeFailureReason);
+}
+export interface MigrationImpactRuntime {
+    readonly identitySha256: string;
+    runSql(sql: string | (() => string)): Promise<string>;
+    assertCurrent(): Promise<void>;
+}
+export interface OpenMigrationImpactRuntimeOptions {
+    readonly projectRoot: string;
+    readonly target: RuntimeTopologyTarget;
+    readonly baseline: BaselineManifest;
+    readonly signal?: AbortSignal;
+    readonly runProcessImplementation?: typeof runOwnedProcess;
+}
+/** No lifecycle, adapter, source-reader, URL or credential-file access is permitted here. */
+export declare function openMigrationImpactRuntime(options: OpenMigrationImpactRuntimeOptions): Promise<MigrationImpactRuntime>;