@rehearsal-db/core 1.1.0 → 1.3.0

package/dist/src/runtime/workload_queue.mjs

@@ -0,0 +1,211 @@
+/** Cooperative local-user lifecycle admission. Not a host-memory or container limit. */
+import { createHash, randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
+import { RehearsalError } from "../shared/diagnostics.mjs";
+import { workloadQueueDirectory } from "./workload_queue_location.mjs";
+import { WorkloadQueueStore, } from "./workload_queue_store.mjs";
+export const withWorkloadDiagnostics = async (task) => {
+    try {
+        return await task();
+    }
+    catch (error) {
+        if (error instanceof RehearsalError)
+            throw error;
+        throw new RehearsalError({
+            category: "runtime_dependency_failure",
+            code: "WORKLOAD_QUEUE_REFUSED",
+            message: error instanceof Error
+                ? error.message
+                : "Local workload coordination was refused.",
+            refused: "No new guarded runtime phase or foreign workload was started, stopped or recovered by this refusal.",
+            suggestions: [
+                "Run rehearsal workloads to inspect participating owners.",
+                "Cancel a waiting request or let its owner finish. Before recovering a dead holder, check its owned commands and descendants; never delete live queue state.",
+            ],
+        });
+    }
+};
+const openStore = async (options, create) => {
+    const store = new WorkloadQueueStore(await workloadQueueDirectory(options.stateDirectory));
+    return (await store.initialize(create)) ? store : null;
+};
+const earlier = (left, right) => left.number < right.number ||
+    (left.number === right.number && left.token < right.token);
+const digest = (entries) => {
+    const stale = entries.filter(({ alive, ticket }) => !alive && ticket.phase === "held");
+    return stale.length
+        ? createHash("sha256")
+            .update(JSON.stringify(stale
+            .map(({ file, identity, ticket }) => ({ file, identity, ticket }))
+            .sort((a, b) => a.file.localeCompare(b.file))))
+            .digest("hex")
+        : null;
+};
+const snapshot = (entries) => ({
+    schemaVersion: 1,
+    scope: "local-user-boot-process-namespace",
+    capacity: "not-measured",
+    recoveryDigest: digest(entries),
+    entries: entries
+        .map(({ ticket, alive }) => ({
+        id: ticket.token,
+        command: ticket.command,
+        pid: ticket.pid,
+        phase: ticket.phase,
+        owner: alive ? "alive" : "dead",
+        createdAt: ticket.createdAt,
+        recoveryRequired: !alive && ticket.phase === "held",
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id)),
+});
+export const inspectWorkloads = async (options = {}) => {
+    const store = await openStore(options, false);
+    return snapshot(store ? await store.list() : []);
+};
+/** Explicitly reviewed metadata recovery only; never stops processes or removes data. */
+export const recoverWorkloads = async (confirmation, options = {}) => {
+    const store = await openStore(options, false);
+    if (!store)
+        throw new Error("No stale workload holder is available to recover.");
+    const entries = await store.list();
+    const expected = digest(entries);
+    if (!expected || confirmation !== expected)
+        throw new Error("Workload recovery confirmation changed or is missing. Run rehearsal workloads --json and review again.");
+    // A dead parent is not proof that its children are gone. The operator must check
+    // owned commands first; age, wait expiry and liveness never authorize auto-steal.
+    const eligible = entries.filter(({ alive, ticket }) => !alive && ticket.phase === "held");
+    for (const entry of eligible) {
+        const current = await store.read(entry.file);
+        if (!current || current.alive || current.identity !== entry.identity)
+            throw new Error("Workload recovery state changed; no live owner was removed.");
+    }
+    for (const entry of eligible)
+        await store.remove(entry);
+    return {
+        schemaVersion: 1,
+        recovered: eligible.length,
+        databasesChanged: false,
+    };
+};
+export const acquireWorkload = async ({ command, waitTimeoutSeconds, signal, onWaiting, ...options }) => {
+    if (!Number.isInteger(waitTimeoutSeconds) ||
+        waitTimeoutSeconds < 0 ||
+        waitTimeoutSeconds > 300)
+        throw new Error("Workload wait timeout must be an integer from 0 to 300 seconds.");
+    signal?.throwIfAborted();
+    const store = (await openStore(options, true));
+    if ((await store.list()).length >= 64)
+        throw new Error("Workload queue is full; no workload was started.");
+    const ticket = {
+        schemaVersion: 1,
+        token: randomUUID(),
+        pid: process.pid,
+        command,
+        phase: "choosing",
+        number: 0,
+        createdAt: new Date().toISOString(),
+    };
+    const file = `ticket-${ticket.token}.json`;
+    const removeOwned = async () => {
+        const entry = await store.read(file);
+        if (entry) {
+            if (entry.ticket.pid !== process.pid ||
+                entry.ticket.token !== ticket.token)
+                throw new Error("Workload ownership changed; no foreign ticket was removed.");
+            await store.remove(entry);
+        }
+    };
+    const started = performance.now();
+    let notified = false;
+    let held = false;
+    try {
+        // Choosing + number ordering follows the bakery protocol. Each participant
+        // writes only its unique record; no stale-reclaimer can rename a new owner.
+        await store.write(ticket, true);
+        const entries = await store.list();
+        ticket.number =
+            1 + Math.max(0, ...entries.map(({ ticket: entry }) => entry.number));
+        if (!Number.isSafeInteger(ticket.number))
+            throw new Error("Workload ticket number limit reached.");
+        ticket.phase = "queued";
+        await store.write(ticket);
+        for (;;) {
+            signal?.throwIfAborted();
+            const current = await store.list();
+            const own = current.find((entry) => entry.file === file);
+            if (!own ||
+                own.ticket.phase !== "queued" ||
+                own.ticket.number !== ticket.number)
+                throw new Error("Workload ticket changed or disappeared; no workload was started.");
+            let blocked = false;
+            for (const entry of current) {
+                if (entry.file === file)
+                    continue;
+                if (!entry.alive && entry.ticket.phase !== "held") {
+                    await store.remove(entry); // This owner never began guarded work.
+                    continue;
+                }
+                if (entry.ticket.phase === "choosing" ||
+                    entry.ticket.phase === "held" ||
+                    earlier(entry.ticket, ticket))
+                    blocked = true;
+            }
+            if (!blocked) {
+                signal?.throwIfAborted();
+                ticket.phase = "held";
+                await store.write(ticket);
+                held = true;
+                break;
+            }
+            if (!notified) {
+                onWaiting?.();
+                notified = true;
+            }
+            if (performance.now() - started >= waitTimeoutSeconds * 1000)
+                throw new Error("Local workload queue wait expired. No queued runtime phase was started. Run rehearsal workloads; a dead holder requires reviewed recovery, not a forced stop.");
+            try {
+                await delay(Math.min(100, Math.max(1, waitTimeoutSeconds * 1000 - (performance.now() - started))), undefined, { signal });
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw signal.reason;
+                throw error;
+            }
+        }
+    }
+    finally {
+        if (!held)
+            await removeOwned();
+    }
+    let released = false;
+    return {
+        release: async () => {
+            if (!released) {
+                await removeOwned();
+                released = true;
+            }
+        },
+    };
+};
+export const withWorkloadAdmission = async ({ enabled, execute, ...options }) => {
+    if (!enabled)
+        return execute();
+    const lease = await withWorkloadDiagnostics(() => acquireWorkload(options));
+    let result;
+    try {
+        options.signal?.throwIfAborted();
+        result = await execute();
+    }
+    catch (error) {
+        try {
+            await lease.release();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "The runtime phase and its workload metadata release both failed.");
+        }
+        throw error;
+    }
+    await withWorkloadDiagnostics(() => lease.release());
+    return result;
+};

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

@@ -0,0 +1 @@
+export declare const workloadQueueDirectory: (stateDirectory?: string) => Promise<string>;

package/dist/src/runtime/workload_queue_location.mjs

@@ -0,0 +1,43 @@
+/** Stable same-user/boot/process-namespace coordination; never use per-run TMPDIR. */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, readlink } from "node:fs/promises";
+import { userInfo } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { promisify } from "node:util";
+let scopePromise;
+const currentScope = async () => {
+    let identity;
+    if (process.platform === "linux") {
+        identity = `${(await readFile("/proc/sys/kernel/random/boot_id", "utf8")).trim()}:${await readlink("/proc/self/ns/pid")}`;
+    }
+    else if (process.platform === "darwin") {
+        const { stdout } = await promisify(execFile)("/usr/sbin/sysctl", ["-n", "kern.boottime"], {
+            env: {},
+            timeout: 1000,
+            maxBuffer: 1024,
+        });
+        const boot = /^\{ sec = (\d+), usec = (\d+) \}/u.exec(stdout);
+        if (!boot)
+            throw new Error("Cannot establish the local workload queue boot identity.");
+        identity = `${boot[1]}:${boot[2]}`;
+    }
+    else {
+        throw new Error("The local workload queue requires macOS or Linux (including WSL).");
+    }
+    return createHash("sha256")
+        .update(`${process.platform}:${userInfo().uid}:${identity}`)
+        .digest("hex");
+};
+export const workloadQueueDirectory = async (stateDirectory) => {
+    const home = userInfo().homedir;
+    const root = stateDirectory ??
+        process.env.REHEARSAL_USER_STATE_DIRECTORY ??
+        (process.platform === "darwin"
+            ? join(home, "Library", "Application Support", "Rehearsal")
+            : join(home, ".local", "state", "rehearsal"));
+    if (!isAbsolute(root) || root.includes("\0"))
+        throw new Error("REHEARSAL_USER_STATE_DIRECTORY must be an absolute local state directory.");
+    scopePromise ??= currentScope();
+    return join(root, "workloads-v1", await scopePromise);
+};

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

@@ -0,0 +1,27 @@
+export interface WorkloadTicket {
+    schemaVersion: 1;
+    token: string;
+    pid: number;
+    command: "start" | "run" | "reset" | "migrate";
+    phase: "choosing" | "queued" | "held";
+    number: number;
+    createdAt: string;
+}
+export interface StoredWorkloadTicket {
+    ticket: WorkloadTicket;
+    file: string;
+    identity: string;
+    alive: boolean;
+}
+export declare const workloadOwnerAlive: (pid: number) => boolean;
+export declare class WorkloadQueueStore {
+    readonly directory: string;
+    private rootIdentity;
+    constructor(directory: string);
+    initialize(create: boolean): Promise<boolean>;
+    assertRoot(): Promise<void>;
+    read(file: string): Promise<StoredWorkloadTicket | null>;
+    list(): Promise<StoredWorkloadTicket[]>;
+    write(ticket: WorkloadTicket, initial?: boolean): Promise<void>;
+    remove(entry: StoredWorkloadTicket): Promise<void>;
+}

package/dist/src/runtime/workload_queue_store.mjs

@@ -0,0 +1,182 @@
+/** Private bounded atomic ticket files. A ticket name is never reused. */
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, opendir, rename, unlink, } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+const missing = (error) => error.code === "ENOENT";
+const identity = (stat) => `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+const privateOwned = (stat) => stat.uid === process.getuid() && (stat.mode & 0o077) === 0;
+const validTicket = (value, token) => value !== null &&
+    typeof value === "object" &&
+    value.schemaVersion === 1 &&
+    value.token === token &&
+    Number.isSafeInteger(value.pid) &&
+    value.pid > 0 &&
+    ["start", "run", "reset", "migrate"].includes(value.command) &&
+    ["choosing", "queued", "held"].includes(value.phase) &&
+    Number.isSafeInteger(value.number) &&
+    value.number >= 0 &&
+    (value.phase === "choosing") === (value.number === 0) &&
+    typeof value.createdAt === "string" &&
+    Number.isFinite(Date.parse(value.createdAt)) &&
+    new Date(value.createdAt).toISOString() === value.createdAt &&
+    Object.keys(value).sort().join(",") ===
+        "command,createdAt,number,phase,pid,schemaVersion,token";
+export const workloadOwnerAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        // EPERM/unknown visibility is never permission to reclaim.
+        throw new Error("Cannot prove workload owner liveness; no workload was admitted or recovered.");
+    }
+};
+export class WorkloadQueueStore {
+    directory;
+    rootIdentity;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async initialize(create) {
+        if (create) {
+            await mkdir(dirname(this.directory), { recursive: true, mode: 0o700 });
+            await mkdir(this.directory, { mode: 0o700 }).catch((error) => {
+                if (error.code !== "EEXIST")
+                    throw error;
+            });
+        }
+        const parent = await lstat(dirname(this.directory)).catch((error) => {
+            if (missing(error))
+                return null;
+            throw error;
+        });
+        if (!parent)
+            return false;
+        if (!parent.isDirectory() || !privateOwned(parent))
+            throw new Error("Workload state parent must be a private owned directory, not a link.");
+        let stat;
+        try {
+            stat = await lstat(this.directory);
+        }
+        catch (error) {
+            if (missing(error))
+                return false;
+            throw error;
+        }
+        if (!stat.isDirectory() || !privateOwned(stat))
+            throw new Error("Workload queue must be a private owned directory, not a link.");
+        this.rootIdentity = `${stat.dev}:${stat.ino}`;
+        return true;
+    }
+    async assertRoot() {
+        const stat = await lstat(this.directory);
+        if (!stat.isDirectory() ||
+            !privateOwned(stat) ||
+            `${stat.dev}:${stat.ino}` !== this.rootIdentity)
+            throw new Error("Workload queue directory changed; no further workload phase was started.");
+    }
+    async read(file) {
+        await this.assertRoot();
+        const match = /^ticket-([a-f0-9-]{36})\.json$/u.exec(file);
+        if (!match)
+            throw new Error("Unknown workload queue entry; inspect local state without deleting it.");
+        for (let attempt = 0; attempt < 4; attempt++) {
+            let handle;
+            try {
+                handle = await open(join(this.directory, file), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                const before = await handle.stat();
+                if (!before.isFile() || !privateOwned(before) || before.size > 4096)
+                    throw new Error("Invalid workload ticket ownership, type or size; queue refused.");
+                const bytes = Buffer.alloc(4097);
+                const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+                if (bytesRead > 4096)
+                    throw new Error("Workload ticket exceeds the bounded record size.");
+                const after = await lstat(join(this.directory, file));
+                if (identity(before) !== identity(after))
+                    continue;
+                let ticket;
+                try {
+                    ticket = JSON.parse(bytes.subarray(0, bytesRead).toString("utf8"));
+                }
+                catch {
+                    throw new Error("Invalid workload ticket JSON; queue refused.");
+                }
+                if (!validTicket(ticket, match[1]))
+                    throw new Error("Invalid workload ticket; queue refused.");
+                return {
+                    ticket,
+                    file,
+                    identity: identity(after),
+                    alive: workloadOwnerAlive(ticket.pid),
+                };
+            }
+            catch (error) {
+                if (missing(error))
+                    return null;
+                throw error;
+            }
+            finally {
+                await handle?.close();
+            }
+        }
+        throw new Error("Workload ticket kept changing; no workload was admitted.");
+    }
+    async list() {
+        await this.assertRoot();
+        const entries = [];
+        const directory = await opendir(this.directory);
+        let count = 0;
+        for await (const entry of directory) {
+            if (++count > 128)
+                throw new Error("Workload queue entry limit reached; inspect state before retrying.");
+            // Complete files are published by link/rename; private drafts never grant admission.
+            if (/^draft-[a-f0-9-]{36}$/u.test(entry.name))
+                continue;
+            const value = await this.read(entry.name);
+            if (value)
+                entries.push(value);
+        }
+        return entries;
+    }
+    async write(ticket, initial = false) {
+        await this.assertRoot();
+        const file = join(this.directory, `ticket-${ticket.token}.json`);
+        const draft = join(this.directory, `draft-${randomUUID()}`);
+        const handle = await open(draft, "wx", 0o600);
+        try {
+            try {
+                await handle.writeFile(JSON.stringify(ticket));
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await this.assertRoot();
+            if (initial)
+                await link(draft, file);
+            else
+                await rename(draft, file);
+        }
+        finally {
+            await unlink(draft).catch((error) => {
+                if (!missing(error))
+                    throw error;
+            });
+        }
+    }
+    async remove(entry) {
+        const current = await this.read(entry.file);
+        if (!current)
+            return;
+        if (entry.identity !== current.identity)
+            throw new Error("Workload ticket changed; this ticket was not recovered.");
+        await this.assertRoot();
+        await unlink(join(this.directory, entry.file)).catch((error) => {
+            if (!missing(error))
+                throw error;
+        });
+    }
+}

package/dist/src/shared/cancellation.mjs

@@ -9,10 +9,12 @@ export const OPERATION_CANCELLATION_SIGNALS = [
 ];
 const CANCELLABLE_COMMANDS = new Set([
     "migrate",
+    "measure impact",
     "open",
     "refresh",
     "reset",
     "run",
+    "start",
     "stop-stale",
 ]);
 let activeSignal;

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>;