@rehearsal-db/core 1.2.0 → 1.3.0

package/dist/src/project/configuration_resource_policy.mjs

@@ -1,5 +1,5 @@
 /** Resource limits and proof dependencies, validated before any runtime starts. */
-import { assertPositiveInteger, } from "./configuration_validation.mjs";
+import { assertKnownKeys, assertPlainObject, assertPositiveInteger, } from "./configuration_validation.mjs";
 export const APPLICATION_REQUIRED_SERVICES = Object.freeze([
     "database",
     "auth",
@@ -29,6 +29,24 @@ const nullablePositiveInteger = (value, path) => {
     return normalized;
 };
 export const normalizeResourcePolicy = (resources) => {
+    let workloadQueue;
+    if (resources.workloadQueue !== undefined) {
+        const path = "config.resources.workloadQueue";
+        const value = assertPlainObject(resources.workloadQueue, path);
+        assertKnownKeys(value, ["enabled", "waitTimeoutSeconds"], path);
+        if (typeof value.enabled !== "boolean")
+            throw new Error(`${path}.enabled must be a boolean.`);
+        const waitTimeoutSeconds = value.waitTimeoutSeconds === undefined ? 30 : value.waitTimeoutSeconds;
+        if (!Number.isInteger(waitTimeoutSeconds) ||
+            typeof waitTimeoutSeconds !== "number" ||
+            waitTimeoutSeconds < 0 ||
+            waitTimeoutSeconds > 300)
+            throw new Error(`${path}.waitTimeoutSeconds must be an integer from 0 to 300.`);
+        workloadQueue = Object.freeze({
+            enabled: value.enabled,
+            waitTimeoutSeconds,
+        });
+    }
     const schedule = resources.cleanupSchedule ?? "manual";
     if (typeof schedule !== "string" ||
         !["manual", "daily-preview", "weekly-preview"].includes(schedule)) {
@@ -39,6 +57,7 @@ export const normalizeResourcePolicy = (resources) => {
         throw new Error("config.resources.retainedEnvironmentCount must be at most 1000.");
     }
     return Object.freeze({
+        ...(workloadQueue === undefined ? {} : { workloadQueue }),
         staleAfterSeconds: nullablePositiveInteger(resources.staleAfterSeconds, "config.resources.staleAfterSeconds"),
         retainedEnvironmentCount,
         maximumBytes: nullablePositiveInteger(resources.maximumBytes, "config.resources.maximumBytes"),

package/dist/src/project/configuration_schema.mjs

@@ -92,6 +92,7 @@ export const validateConfigurationSchema = (input) => {
         "retainedEnvironmentCount",
         "maximumBytes",
         "cleanupSchedule",
+        "workloadQueue",
     ], "config.resources");
     const preparation = root.preparation === undefined
         ? null

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

@@ -0,0 +1,39 @@
+import { type WorkloadTicket } from "./workload_queue_store.mjs";
+interface QueueOptions {
+    stateDirectory?: string;
+}
+export declare const withWorkloadDiagnostics: <Result>(task: () => Promise<Result>) => Promise<Result>;
+export declare const inspectWorkloads: (options?: QueueOptions) => Promise<{
+    schemaVersion: 1;
+    scope: "local-user-boot-process-namespace";
+    capacity: "not-measured";
+    recoveryDigest: string | null;
+    entries: {
+        id: string;
+        command: "migrate" | "reset" | "run" | "start";
+        pid: number;
+        phase: "choosing" | "held" | "queued";
+        owner: "alive" | "dead";
+        createdAt: string;
+        recoveryRequired: boolean;
+    }[];
+}>;
+/** Explicitly reviewed metadata recovery only; never stops processes or removes data. */
+export declare const recoverWorkloads: (confirmation: string, options?: QueueOptions) => Promise<{
+    schemaVersion: 1;
+    recovered: number;
+    databasesChanged: false;
+}>;
+export declare const acquireWorkload: ({ command, waitTimeoutSeconds, signal, onWaiting, ...options }: QueueOptions & {
+    command: WorkloadTicket["command"];
+    waitTimeoutSeconds: number;
+    signal?: AbortSignal;
+    onWaiting?: () => void;
+}) => Promise<{
+    release: () => Promise<void>;
+}>;
+export declare const withWorkloadAdmission: <Result>({ enabled, execute, ...options }: Parameters<typeof acquireWorkload>[0] & {
+    enabled: boolean;
+    execute: () => Promise<Result>;
+}) => Promise<Result>;
+export {};

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

@@ -14,6 +14,7 @@ const CANCELLABLE_COMMANDS = new Set([
     "refresh",
     "reset",
     "run",
+    "start",
     "stop-stale",
 ]);
 let activeSignal;

package/docs/architecture.md

@@ -77,6 +77,15 @@ 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. It also

package/docs/commands.md

@@ -3,6 +3,26 @@
 Run commands from the project directory containing `rehearsal.config.mjs`. The examples
 use `npx`, so a global install is not required.
 
+## Participating local workloads
+
+Core 1.3.0 and later builds advertising `rehearsalContracts.workloadQueue: 1` support
+`npx --no-install rehearsal workloads --json`. This read-only command needs no
+project configuration or Docker. Its version-1 `data` lists lifecycle ticket IDs,
+commands, PIDs, phases (`choosing`, `queued`, `held`), owner liveness and creation
+times. It reports `capacity: "not-measured"`: this is cooperative admission, not
+a claim about spare host/VM memory. Project paths, migration SQL and credentials
+are not included. Enable participation with
+[`resources.workloadQueue`](configuration.md#resource-review-policies).
+
+A dead holder blocks new admission until explicitly reviewed. Confirm its owned
+commands and descendants have ended before running
+`npx --no-install rehearsal workloads recover --confirm-workloads=<recoveryDigest>`.
+The exact inspection digest binds only the dead held records; changed records,
+missing confirmation and live owners refuse recovery. This operation clears local
+queue metadata only. It does not stop processes/containers or alter databases.
+Waiting requests can be cancelled; expiry never steals a live holder. Read-only
+inspection does not clean stale records or create state directories.
+
 ## Guided mode
 
 For editor-style review, `npx rehearsal inspect plan --json` returns a bounded,
@@ -15,8 +35,8 @@ Rehearsal does not infer SQL safety from filenames.
 In a core build advertising `rehearsalContracts.migrationInsights: 1`, run
 `npx --no-install rehearsal inspect insights --json` to inspect pending SQL without
 starting an engine, connecting to a database, running application commands or changing
-files. This additive contract does not change `inspect plan` version 1. It is new
-development work, not a capability of the original tested core 1.1.0 candidate.
+files. This additive contract, introduced in core 1.2.0, does not change
+`inspect plan` version 1. Older releases without the capability do not provide it.
 
 The normal version-1 command envelope contains `data.schemaVersion: 1`, the exact
 complete `candidateSha256`, candidate count, aggregate verdict and per-target entries.
@@ -50,10 +70,10 @@ The CLI and these essential safety warnings remain free.
 
 ### Current-sandbox data impact
 
-A source build advertising `rehearsalContracts.migrationImpact: 1` adds two free,
-optional commands. This is unpublished development work, not a capability of an
-already-installed release. It does not change migration-plan v1, static Insights,
-failure diagnosis, or the gates for `run` and `migrate`.
+A build advertising `rehearsalContracts.migrationImpact: 1` adds two free,
+optional commands, introduced in core 1.2.0. Check the installed capability rather
+than assuming an older release provides them. It does not change migration-plan v1,
+static Insights, failure diagnosis, or the gates for `run` and `migrate`.
 
 ```bash
 npx --no-install rehearsal inspect impact --target=primary --json