@rehearsal-db/core 0.1.0-rc.2 → 0.1.0-rc.3

package/dist/src/cli/runtime_commands.mjs

@@ -13,7 +13,11 @@ import { buildRehearsalPlan, runRehearsalDoctor } from "../runtime/plan.mjs";
 import { inspectRuntimeTopologyCandidates, loadRuntimeTopology, } from "../runtime/topology.mjs";
 import { RehearsalError, normalizeRehearsalError, redactDiagnosticValue, } from "../shared/diagnostics.mjs";
 import { assertInstalledPackageFingerprint } from "../shared/operation_guard.mjs";
+import { getOperationCancellationSignal, throwIfOperationCancelled, } from "../shared/cancellation.mjs";
+import { runOwnedProcess } from "../shared/owned_process.mjs";
 import { buildRuntimeManagerArguments } from "../targets/target.mjs";
+import { parseRuntimeStatusSnapshot, renderRuntimeStatusSnapshot, } from "../runtime/status.mjs";
+import { applyRuntimePersistence } from "../runtime/persistence.mjs";
 import { formatDuration, isHumanTerminal, promptForConfirmation, terminalStyle, useStyledPrompts, } from "./terminal.mjs";
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 export const buildRuntimeStackPlan = async (planOptions) => {
@@ -38,6 +42,11 @@ export const buildRuntimeStackPlan = async (planOptions) => {
             candidateCount: candidates.candidateCount,
             candidateSha256: candidates.candidateSha256,
         },
+        lifecycle: {
+            run: topology.primary.config.lifecycle.run,
+            open: topology.primary.config.lifecycle.open,
+            dataOnStop: "preserved",
+        },
         execution: [
             "verify every immutable baseline and migration prefix",
             "restore and migrate the primary runtime",
@@ -47,6 +56,9 @@ export const buildRuntimeStackPlan = async (planOptions) => {
                 .map((target) => `run ${target.name} preparation: ${target.declaration.prepareCommand}`),
             ...topology.dependents.map((target) => `run ${target.name} proof: ${target.config.application.proofCommand}`),
             `run primary proof: ${topology.primary.config.application.proofCommand}`,
+            topology.primary.config.lifecycle.run === "stop-after-run"
+                ? "stop every database target after proofs while preserving its data"
+                : "keep every database target available until an explicit stop",
         ],
         guarantee: "Every database target is isolated by its own project ID, ports, artifact directory, and local-only safety policy. No production resources will be contacted.",
     };
@@ -256,15 +268,18 @@ export const topologyEnvironmentFiles = (topology) => ({
         target.paths.applicationEnvironment,
     ])),
 });
-const runProjectCommand = ({ source, configuredRoot, label, project, environment = {}, }) => {
+const runProjectCommand = async ({ source, configuredRoot, label, project, environment = {}, }) => {
     const [command, ...args] = parseCommand(source);
-    const result = spawnSync(command, args, {
+    const cancellationSignal = getOperationCancellationSignal();
+    const result = await runOwnedProcess({
+        command,
+        args,
         cwd: configuredRoot,
-        encoding: "utf8",
         env: projectCommandEnvironment(environment),
-        stdio: ["ignore", "pipe", "pipe"],
-        maxBuffer: 16 * 1024 * 1024,
+        stdin: "ignore",
+        ...(cancellationSignal ? { signal: cancellationSignal } : {}),
     });
+    throwIfOperationCancelled();
     if (result.error || result.status !== 0) {
         throw new RehearsalError({
             category: "application_proof_failure",
@@ -286,7 +301,7 @@ const runProjectCommand = ({ source, configuredRoot, label, project, environment
     };
 };
 export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, getActivePackageFingerprint, }) => {
-    const runManager = ({ action, flags, configPath = flags.configPath, confirmation = flags.confirmation, targetName, }) => {
+    const runManager = async ({ action, flags, configPath = flags.configPath, confirmation = flags.confirmation, targetName, }) => {
         const fingerprint = getActivePackageFingerprint();
         if (fingerprint) {
             assertInstalledPackageFingerprint({
@@ -299,6 +314,7 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
             action,
             ...(configPath === undefined ? {} : { configPath }),
             ...(confirmation === undefined ? {} : { confirmation }),
+            structuredResult: action === "status",
         });
         const runtimeStartedMs = performance.now();
         const actionDescription = {
@@ -321,13 +337,25 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
         else if (isHumanTerminal(flags)) {
             console.log(`\n${terminalStyle(flags, "1;36", action === "run" ? "REHEARSING" : "REHEARSAL")}\n${terminalStyle(flags, "36", "→")} ${describedAction}. This can take a moment.`);
         }
-        const result = spawnSync(process.execPath, args, {
+        const cancellationSignal = getOperationCancellationSignal();
+        // VS Code extensions launch the package CLI through Electron's executable in
+        // Node mode. Preserve that mode only for Rehearsal's nested Node manager;
+        // project-owned application commands continue to receive the reduced
+        // project environment above.
+        const managerEnvironment = {
+            ...(cancellationSignal ? { REHEARSAL_CANCELLABLE_OPERATION: "1" } : {}),
+            ...(process.env.ELECTRON_RUN_AS_NODE === "1"
+                ? { ELECTRON_RUN_AS_NODE: "1" }
+                : {}),
+        };
+        const result = await runOwnedProcess({
+            command: process.execPath,
+            args,
             cwd: projectRoot,
-            encoding: "utf8",
-            env: projectCommandEnvironment(),
-            stdio: ["inherit", "pipe", "pipe"],
-            maxBuffer: 16 * 1024 * 1024,
+            env: projectCommandEnvironment(managerEnvironment),
+            ...(cancellationSignal ? { signal: cancellationSignal } : {}),
         });
+        throwIfOperationCancelled();
         const currentFingerprint = getActivePackageFingerprint();
         if (currentFingerprint) {
             assertInstalledPackageFingerprint({
@@ -396,11 +424,17 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
         else if (isHumanTerminal(flags)) {
             console.log(`${terminalStyle(flags, "32", "✓")} Local runtime step completed in ${formatDuration(durationMs)}.`);
         }
+        const runtimeStatus = action === "status"
+            ? parseRuntimeStatusSnapshot(JSON.parse(String(result.stdout ?? "")))
+            : undefined;
         return {
             action,
             target: targetName ?? "primary",
             durationMs: Math.round(durationMs * 100) / 100,
-            output: String(redactDiagnosticValue(String(result.stdout ?? "").trim())),
+            output: runtimeStatus
+                ? renderRuntimeStatusSnapshot(runtimeStatus)
+                : String(redactDiagnosticValue(String(result.stdout ?? "").trim())),
+            ...(runtimeStatus ? { runtimeStatus } : {}),
         };
     };
     const runRuntimeStack = async ({ command, flags, planOptions, session, }) => {
@@ -410,16 +444,17 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
         const targets = reverse
             ? [...topology.targets].reverse()
             : topology.targets;
-        const results = targets.map((target) => {
+        const results = [];
+        for (const target of targets) {
             const confirmation = session.targetConfirmations?.get(target.configPath);
-            return runManager({
+            results.push(await runManager({
                 action: command,
                 flags,
                 configPath: target.configPath,
                 ...(confirmation === undefined ? {} : { confirmation }),
                 ...(topology.targets.length > 1 ? { targetName: target.name } : {}),
-            });
-        });
+            }));
+        }
         if (results.length === 1)
             return { topology, runtime: results[0] };
         return {
@@ -449,22 +484,24 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
                 : { environment: options.environment }),
         });
     };
-    const prepareDependentTargets = ({ topology, environment, }) => topology.dependents.flatMap((target) => {
-        if (!target.declaration?.prepareCommand)
-            return [];
-        return [
-            {
+    const prepareDependentTargets = async ({ topology, environment, }) => {
+        const preparations = [];
+        for (const target of topology.dependents) {
+            if (!target.declaration?.prepareCommand)
+                continue;
+            preparations.push({
                 target: target.name,
-                ...runProjectCommand({
+                ...(await runProjectCommand({
                     source: target.declaration.prepareCommand,
                     configuredRoot: topology.projectRoot,
                     label: `preparation command for ${target.name}`,
                     project: topology.primary.config.project.name,
                     environment,
-                }),
-            },
-        ];
-    });
+                })),
+            });
+        }
+        return preparations;
+    };
     const proveRuntimeStack = async ({ topology, planOptions, environment, }) => {
         const dependentProofs = [];
         for (const target of topology.dependents) {
@@ -479,7 +516,7 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
         });
         return { applicationProof, dependentProofs };
     };
-    const startRuntimeApplication = async ({ flags, planOptions, session: commandSession, }) => {
+    const startRuntimeApplication = async ({ flags, planOptions, session: commandSession, onRuntimeStarted = () => undefined, }) => {
         const topology = await loadRuntimeTopology(planOptions);
         const application = topology.primary.config.application;
         if (!application.readiness) {
@@ -505,13 +542,14 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
             planOptions,
             session: commandSession,
         });
+        onRuntimeStarted();
         const verified = await runRuntimeStack({
             command: "verify",
             flags,
             planOptions,
             session: commandSession,
         });
-        const preparations = prepareDependentTargets({
+        const preparations = await prepareDependentTargets({
             topology,
             environment: topologyCommandEnvironment(topology),
         });
@@ -531,15 +569,34 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
         };
     };
     const openRuntimeApplication = async ({ flags, planOptions, session: commandSession, onReady = () => undefined, }) => {
-        const active = await startRuntimeApplication({
-            flags,
-            planOptions,
-            session: commandSession,
-        });
-        const closed = await holdApplicationSession({
-            session: active.session,
-            onReady,
+        const topology = await loadRuntimeTopology(planOptions);
+        let runtimeStarted = false;
+        const { result, lifecycle } = await applyRuntimePersistence({
+            mode: topology.primary.config.lifecycle.open,
+            canStop: () => runtimeStarted,
+            operation: async () => {
+                const active = await startRuntimeApplication({
+                    flags,
+                    planOptions,
+                    session: commandSession,
+                    onRuntimeStarted: () => {
+                        runtimeStarted = true;
+                    },
+                });
+                const closed = await holdApplicationSession({
+                    session: active.session,
+                    onReady,
+                });
+                return { active, closed };
+            },
+            stop: async () => (await runRuntimeStack({
+                command: "stop",
+                flags,
+                planOptions,
+                session: commandSession,
+            })).runtime,
         });
+        const { active, closed } = result;
         return {
             action: "open",
             started: active.started,
@@ -551,6 +608,7 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
                 stoppedBy: closed.signal,
                 diagnostics: closed.diagnostics,
             },
+            lifecycle,
         };
     };
     const prepareCandidateConfirmation = async ({ command, flags, planOptions, session, }) => {

package/dist/src/cli/source_commands.d.mts

@@ -2,6 +2,7 @@
  * CLI orchestration for temporary production-source access and safe baseline
  * replacement. Domain validation remains in src/source and src/baseline.
  */
+import { activateBaselineGeneration } from "../baseline/artifact.mjs";
 import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
 import type { RehearsalCliFlags } from "./arguments.mjs";
 import type { CliSessionState } from "./command_contract.mjs";
@@ -53,6 +54,10 @@ export declare const loadPreparationContext: (planOptions: RehearsalConfigPathOp
             containerRuntime: Readonly<{
                 autoStartColima: boolean;
             }>;
+            lifecycle: Readonly<{
+                run: "keep-until-stop" | "stop-after-run";
+                open: "keep-until-stop" | "stop-on-application-exit";
+            }>;
             cleanup: Readonly<{
                 retainBaselineGenerations: number;
             }>;
@@ -201,6 +206,10 @@ export declare const buildRefreshWorkflowPlan: (planOptions: RehearsalConfigPath
             containerRuntime: Readonly<{
                 autoStartColima: boolean;
             }>;
+            lifecycle: Readonly<{
+                run: "keep-until-stop" | "stop-after-run";
+                open: "keep-until-stop" | "stop-on-application-exit";
+            }>;
             cleanup: Readonly<{
                 retainBaselineGenerations: number;
             }>;
@@ -323,7 +332,7 @@ export declare const buildRefreshWorkflowPlan: (planOptions: RehearsalConfigPath
         digest: string;
     };
 }>;
-export declare const createRefreshWorkflow: ({ runRuntimeStack, prepareDependentTargets, topologyCommandEnvironment, buildPlan, refreshBaseline, }: {
+export declare const createRefreshWorkflow: ({ runRuntimeStack, prepareDependentTargets, topologyCommandEnvironment, buildPlan, refreshBaseline, activateBaseline, }: {
     runRuntimeStack: (input: {
         command: "reset";
         flags: RehearsalCliFlags;
@@ -336,10 +345,11 @@ export declare const createRefreshWorkflow: ({ runRuntimeStack, prepareDependent
     prepareDependentTargets: (input: {
         topology: RuntimeTopology;
         environment: NodeJS.ProcessEnv;
-    }) => unknown[];
+    }) => Promise<unknown[]>;
     topologyCommandEnvironment: (topology: RuntimeTopology) => NodeJS.ProcessEnv;
     buildPlan?: (options: RehearsalConfigPathOptions) => Promise<RefreshPlanContext>;
     refreshBaseline?: typeof runSourceBaselineRefresh;
+    activateBaseline?: typeof activateBaselineGeneration;
 }) => ({ flags, planOptions, session, }: SourceCommandInput & {
     session: CliSessionState;
 }) => Promise<{

package/dist/src/cli/source_commands.mjs

@@ -14,6 +14,7 @@ import { refreshPostgresqlBaseline } from "../source/baseline.mjs";
 import { resolvePrivacyMappedAssets } from "../source/privacy_paths.mjs";
 import { applyPostgresqlSourceAccess, planPostgresqlSourceAccessRetirement, resolvePostgresqlSourceStatePaths, retirePostgresqlSourceAccess, } from "../source/postgresql_access.mjs";
 import { loadRuntimeTopology } from "../runtime/topology.mjs";
+import { isOperationCancelled, throwIfOperationCancelled, withOperationCancellationShield, } from "../shared/cancellation.mjs";
 const parseSourceAccessReceipt = (source) => {
     const parsed = JSON.parse(source);
     if (typeof parsed.targetFingerprint !== "string" ||
@@ -224,7 +225,7 @@ export const buildRefreshWorkflowPlan = async (planOptions) => {
         },
     };
 };
-export const createRefreshWorkflow = ({ runRuntimeStack, prepareDependentTargets, topologyCommandEnvironment, buildPlan = buildRefreshWorkflowPlan, refreshBaseline = runSourceBaselineRefresh, }) => async ({ flags, planOptions, session, }) => {
+export const createRefreshWorkflow = ({ runRuntimeStack, prepareDependentTargets, topologyCommandEnvironment, buildPlan = buildRefreshWorkflowPlan, refreshBaseline = runSourceBaselineRefresh, activateBaseline = activateBaselineGeneration, }) => async ({ flags, planOptions, session, }) => {
     const context = await buildPlan(planOptions);
     if (!flags.refreshConfirmation) {
         return { mode: "preview", plan: context.plan };
@@ -236,40 +237,48 @@ export const createRefreshWorkflow = ({ runRuntimeStack, prepareDependentTargets
     let runtime;
     let preparations = [];
     try {
+        throwIfOperationCancelled();
         refreshed = await refreshBaseline({ planOptions });
+        throwIfOperationCancelled();
         const stack = await runRuntimeStack({
             command: "reset",
             flags,
             planOptions,
             session,
         });
+        throwIfOperationCancelled();
         runtime = stack.runtime;
-        preparations = prepareDependentTargets({
+        preparations = await prepareDependentTargets({
             topology: stack.topology,
             environment: topologyCommandEnvironment(stack.topology),
         });
+        throwIfOperationCancelled();
     }
     catch (error) {
         if (refreshed) {
-            await activateBaselineGeneration({
-                artifactRoot: context.loaded.paths.artifactDirectory,
-                generationId: context.plan.review.currentBaseline,
-            });
             try {
-                const rollback = await runRuntimeStack({
-                    command: "reset",
-                    flags,
-                    planOptions,
-                    session,
-                });
-                prepareDependentTargets({
-                    topology: rollback.topology,
-                    environment: topologyCommandEnvironment(rollback.topology),
+                await withOperationCancellationShield(async () => {
+                    await activateBaseline({
+                        artifactRoot: context.loaded.paths.artifactDirectory,
+                        generationId: context.plan.review.currentBaseline,
+                    });
+                    const rollback = await runRuntimeStack({
+                        command: "reset",
+                        flags,
+                        planOptions,
+                        session,
+                    });
+                    await prepareDependentTargets({
+                        topology: rollback.topology,
+                        environment: topologyCommandEnvironment(rollback.topology),
+                    });
                 });
             }
             catch (rollbackError) {
                 throw new AggregateError([error, rollbackError], "The refreshed runtime failed and the previous local runtime could not be restored automatically. The previous immutable baseline is active; run rehearsal reset after correcting the reported problem.");
             }
+            if (isOperationCancelled(error))
+                throw error;
             throw new Error("The refreshed runtime failed verification. Rehearsal restored the previous baseline and local runtime.", { cause: error });
         }
         throw error;

package/dist/src/project/configuration_contract.d.mts

@@ -1,5 +1,7 @@
 /** Public configuration types, format version, and stable defaults. */
 export type RehearsalConfigVersion = 1;
+export type RunPersistenceMode = "keep-until-stop" | "stop-after-run";
+export type OpenPersistenceMode = "keep-until-stop" | "stop-on-application-exit";
 export interface RehearsalConfig {
     schemaVersion: RehearsalConfigVersion;
     project: {
@@ -38,6 +40,10 @@ export interface RehearsalConfig {
     containerRuntime?: {
         autoStartColima?: boolean;
     };
+    lifecycle?: {
+        run?: RunPersistenceMode;
+        open?: OpenPersistenceMode;
+    };
     cleanup?: {
         retainBaselineGenerations?: number;
     };
@@ -108,6 +114,10 @@ export declare const REHEARSAL_DEFAULTS: Readonly<{
     containerRuntime: Readonly<{
         autoStartColima: false;
     }>;
+    lifecycle: Readonly<{
+        run: RunPersistenceMode;
+        open: OpenPersistenceMode;
+    }>;
     cleanup: Readonly<{
         retainBaselineGenerations: 2;
     }>;

package/dist/src/project/configuration_contract.mjs

@@ -3,6 +3,10 @@ export const REHEARSAL_CONFIG_VERSION = 1;
 export const REHEARSAL_DEFAULTS = Object.freeze({
     baseline: Object.freeze({ artifactDirectory: ".rehearsal" }),
     containerRuntime: Object.freeze({ autoStartColima: false }),
+    lifecycle: Object.freeze({
+        run: "keep-until-stop",
+        open: "keep-until-stop",
+    }),
     cleanup: Object.freeze({ retainBaselineGenerations: 2 }),
     runtime: Object.freeze({
         applicationUrl: "http://localhost:5175",

package/dist/src/project/configuration_normalization.d.mts

@@ -41,6 +41,10 @@ export declare const normalizeRehearsalConfig: (input: unknown) => Readonly<{
     containerRuntime: Readonly<{
         autoStartColima: boolean;
     }>;
+    lifecycle: Readonly<{
+        run: "keep-until-stop" | "stop-after-run";
+        open: "keep-until-stop" | "stop-on-application-exit";
+    }>;
     cleanup: Readonly<{
         retainBaselineGenerations: number;
     }>;

package/dist/src/project/configuration_normalization.mjs

@@ -8,6 +8,12 @@ import { validateConfigurationSchema } from "./configuration_schema.mjs";
 import { assertBoolean, assertCommand, assertDatabaseIdentifier, assertEnvironmentKey, assertEnvironmentReference, assertHttpStatus, assertIdentifier, assertKnownKeys, assertLoopbackUrl, assertNonEmptyString, assertPlainObject, assertPort, assertPostgresImage, assertPositiveInteger, assertRelativePath, assertStringArray, } from "./configuration_validation.mjs";
 const LOOPBACK_HOSTS = new Set(REHEARSAL_DEFAULTS.safety.allowedHosts);
 const SUPPORTED_SUPABASE_OAUTH_PROVIDERS = new Set(["github", "google"]);
+const assertChoice = (value, choices, path) => {
+    if (typeof value !== "string" || !choices.includes(value)) {
+        throw new Error(`${path} must be one of: ${choices.join(", ")}.`);
+    }
+    return value;
+};
 const normalizeApplicationEnvironmentMappings = (value = {}) => {
     const mappings = assertPlainObject(value, "config.application.environmentVariables");
     return Object.freeze(Object.fromEntries(Object.entries(mappings).map(([key, reference]) => {
@@ -17,7 +23,7 @@ const normalizeApplicationEnvironmentMappings = (value = {}) => {
     })));
 };
 export const normalizeRehearsalConfig = (input) => {
-    const { root, project, runtime, runtimeTarget, supabase, postgresql, baseline, containerRuntime, cleanup, preparation, dependentTargets, application, readiness, httpProofs, safety, verification, authentication, } = validateConfigurationSchema(input);
+    const { root, project, runtime, runtimeTarget, supabase, postgresql, baseline, containerRuntime, lifecycle, cleanup, preparation, dependentTargets, application, readiness, httpProofs, safety, verification, authentication, } = validateConfigurationSchema(input);
     const projectName = assertIdentifier(project.name, "config.project.name");
     const normalizedDependentTargets = dependentTargets.map((target, index) => {
         const path = `config.dependentTargets[${index}]`;
@@ -190,6 +196,10 @@ export const normalizeRehearsalConfig = (input) => {
             autoStartColima: assertBoolean(containerRuntime.autoStartColima ??
                 REHEARSAL_DEFAULTS.containerRuntime.autoStartColima, "config.containerRuntime.autoStartColima"),
         }),
+        lifecycle: Object.freeze({
+            run: assertChoice(lifecycle.run ?? REHEARSAL_DEFAULTS.lifecycle.run, ["keep-until-stop", "stop-after-run"], "config.lifecycle.run"),
+            open: assertChoice(lifecycle.open ?? REHEARSAL_DEFAULTS.lifecycle.open, ["keep-until-stop", "stop-on-application-exit"], "config.lifecycle.open"),
+        }),
         cleanup: Object.freeze({
             retainBaselineGenerations: assertPositiveInteger(cleanup.retainBaselineGenerations ??
                 REHEARSAL_DEFAULTS.cleanup.retainBaselineGenerations, "config.cleanup.retainBaselineGenerations"),

package/dist/src/project/configuration_rendering.mjs

@@ -67,6 +67,13 @@ export default defineRehearsalConfig({
 		autoStartColima: false,
 	},
 
+	// Choose when Rehearsal stops its database targets. Stopping preserves all
+	// database and Storage changes; only reset or discard removes runtime state.
+	lifecycle: {
+		run: "keep-until-stop", // Or "stop-after-run" for bounded automated checks.
+		open: "keep-until-stop", // Or "stop-on-application-exit" after Ctrl+C/Ctrl+Z.
+	},
+
 	// Keep this many baseline generations, always including the active one.
 	cleanup: {
 		retainBaselineGenerations: 2,
@@ -173,6 +180,13 @@ export default defineRehearsalConfig({
 		autoStartColima: false,
 	},
 
+	// Choose when Rehearsal stops its database targets. Stopping preserves all
+	// database changes; only reset or discard removes runtime state.
+	lifecycle: {
+		run: "keep-until-stop", // Or "stop-after-run" for bounded automated checks.
+		open: "keep-until-stop", // Or "stop-on-application-exit" after Ctrl+C/Ctrl+Z.
+	},
+
 	// Keep this many baseline generations, always including the active one.
 	cleanup: {
 		retainBaselineGenerations: 2,

package/dist/src/project/configuration_resolution.d.mts

@@ -41,6 +41,10 @@ export declare const loadRehearsalConfig: ({ projectRoot, configPath, }?: Rehear
         containerRuntime: Readonly<{
             autoStartColima: boolean;
         }>;
+        lifecycle: Readonly<{
+            run: "keep-until-stop" | "stop-after-run";
+            open: "keep-until-stop" | "stop-on-application-exit";
+        }>;
         cleanup: Readonly<{
             retainBaselineGenerations: number;
         }>;

package/dist/src/project/configuration_schema.d.mts

@@ -9,6 +9,7 @@ export interface ValidatedConfigurationSchema {
     postgresql: PlainObject | null;
     baseline: PlainObject;
     containerRuntime: PlainObject;
+    lifecycle: PlainObject;
     cleanup: PlainObject;
     preparation: PlainObject | null;
     dependentTargets: PlainObject[];

package/dist/src/project/configuration_schema.mjs

@@ -16,6 +16,7 @@ export const validateConfigurationSchema = (input) => {
         "postgresql",
         "baseline",
         "containerRuntime",
+        "lifecycle",
         "cleanup",
         "preparation",
         "runtimePolicy",
@@ -71,6 +72,8 @@ export const validateConfigurationSchema = (input) => {
     assertKnownKeys(baseline, ["artifactDirectory", "sanitizationPolicy"], "config.baseline");
     const containerRuntime = assertPlainObject(root.containerRuntime ?? {}, "config.containerRuntime");
     assertKnownKeys(containerRuntime, ["autoStartColima"], "config.containerRuntime");
+    const lifecycle = assertPlainObject(root.lifecycle ?? {}, "config.lifecycle");
+    assertKnownKeys(lifecycle, ["run", "open"], "config.lifecycle");
     const cleanup = assertPlainObject(root.cleanup ?? {}, "config.cleanup");
     assertKnownKeys(cleanup, ["retainBaselineGenerations"], "config.cleanup");
     const preparation = root.preparation === undefined
@@ -147,6 +150,7 @@ export const validateConfigurationSchema = (input) => {
         postgresql,
         baseline,
         containerRuntime,
+        lifecycle,
         cleanup,
         preparation,
         dependentTargets,

package/dist/src/runtime/lifecycle_engine.mjs

@@ -4,6 +4,7 @@ import { resolveActiveBaselinePaths, verifyActiveBaseline, } from "../baseline/a
 import { readBoundRuntimeSanitizationPolicy } from "../baseline/sanitization_policy.mjs";
 import { readMigrationFileInventory } from "./migration_history.mjs";
 import { createCandidateMigrationReceipt } from "./restore.mjs";
+import { reachOperationCancellationCheckpoint, withOperationCancellationShield, } from "../shared/cancellation.mjs";
 export const readActiveRuntimeInput = async ({ artifactRoot, manifestPath, validate, }) => {
     const [baseline, paths, policyBytes] = await Promise.all([
         verifyActiveBaseline({ artifactRoot }),
@@ -70,10 +71,17 @@ export const readMatchingRuntimeMarker = async ({ path, expected, mismatchMessag
 };
 export const withOwnedRuntimeRollback = async ({ operation, rollback, }) => {
     try {
-        return await operation();
+        const result = await operation();
+        await reachOperationCancellationCheckpoint();
+        return result;
     }
     catch (error) {
-        await rollback().catch(() => undefined);
+        try {
+            await withOperationCancellationShield(rollback);
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], "The runtime operation failed and its owned runtime could not be removed automatically.");
+        }
         throw error;
     }
 };

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

@@ -0,0 +1,19 @@
+/** Explicit, non-destructive persistence policy for project-owned runtimes. */
+import type { OpenPersistenceMode, RunPersistenceMode } from "../project/configuration_contract.mjs";
+export type RuntimePersistenceMode = RunPersistenceMode | OpenPersistenceMode;
+export interface RuntimePersistenceOutcome<StopResult> {
+    readonly mode: RuntimePersistenceMode;
+    readonly runtimeState: "running" | "stopped";
+    readonly dataState: "preserved";
+    readonly stop: StopResult | null;
+}
+export declare const shouldStopRuntime: (mode: RuntimePersistenceMode) => boolean;
+export declare const applyRuntimePersistence: <Result, StopResult>({ mode, operation, stop, canStop, }: {
+    mode: RuntimePersistenceMode;
+    operation: () => Promise<Result>;
+    stop: () => Promise<StopResult>;
+    canStop?: () => boolean;
+}) => Promise<{
+    result: Result;
+    lifecycle: RuntimePersistenceOutcome<StopResult>;
+}>;

package/dist/src/runtime/persistence.mjs

@@ -0,0 +1,40 @@
+/** Explicit, non-destructive persistence policy for project-owned runtimes. */
+import { withOperationCancellationShield } from "../shared/cancellation.mjs";
+export const shouldStopRuntime = (mode) => mode === "stop-after-run" || mode === "stop-on-application-exit";
+export const applyRuntimePersistence = async ({ mode, operation, stop, canStop = () => true, }) => {
+    let result;
+    let operationFailed = false;
+    let operationError;
+    try {
+        result = await operation();
+    }
+    catch (error) {
+        operationFailed = true;
+        operationError = error;
+    }
+    let stopResult = null;
+    let stopped = false;
+    if (shouldStopRuntime(mode) && canStop()) {
+        try {
+            stopResult = await withOperationCancellationShield(stop);
+            stopped = true;
+        }
+        catch (stopError) {
+            if (operationFailed) {
+                throw new AggregateError([operationError, stopError], "The Rehearsal operation failed and its owned runtime could not be stopped automatically.");
+            }
+            throw stopError;
+        }
+    }
+    if (operationFailed)
+        throw operationError;
+    return {
+        result: result,
+        lifecycle: Object.freeze({
+            mode,
+            runtimeState: stopped ? "stopped" : "running",
+            dataState: "preserved",
+            stop: stopResult,
+        }),
+    };
+};

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

@@ -49,6 +49,11 @@ export declare const buildRehearsalPlan: (options?: RehearsalConfigPathOptions)
             sha256: string;
         }[];
     };
+    lifecycle: {
+        run: "keep-until-stop" | "stop-after-run";
+        open: "keep-until-stop" | "stop-on-application-exit";
+        dataOnStop: string;
+    };
     execution: string[];
     guarantee: string;
     paths: {