@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.510

package/dist/foundation/release/bootstrap.js

@@ -0,0 +1,427 @@
+import { spawn } from "node:child_process";
+import { restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { connect } from "node:net";
+import { platform } from "node:os";
+import { resolve } from "node:path";
+import { selectCohortLaunch } from "./cohort-selection.js";
+import { CohortStateStore } from "./cohort-state.js";
+import { assertLaunchProfileId, createSupervisorStartupAttempt, readSupervisorStartupResult, resolveCohortEndpoint, resolveProductPaths, sessionSelectionArguments } from "../lifecycle/index.js";
+import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
+import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
+import { probeOwnership, readEndpointMetadata, removeEndpointArtifacts, sweepDeadEndpoints } from "./endpoints.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+import { selectUpdateLaunchRelease } from "./update-launch.js";
+import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
+import { scheduleReleaseCleanup } from "./release-gc.js";
+import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { markStartupPhase } from "../startup/index.js";
+import { launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
+export async function runBootstrap(options) {
+    const environment = withLaunchContext(options.environment ?? process.env, { launchProfile: options.launchIntent?.profileId ?? "a1" });
+    await markStartupPhase(environment, "bootstrap-start");
+    const launchProfileId = options.launchIntent?.profileId ?? "a1";
+    assertLaunchProfileId(launchProfileId);
+    const sessionArgs = sessionSelectionArguments(options.launchIntent?.sessionSelection);
+    if (sessionArgs.length > 0 && launchProfileId !== "a1")
+        throw new Error("session selection requires the normal A1 profile");
+    const output = options.output ?? process.stderr;
+    const paths = resolveProductPaths(environment);
+    await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
+    const stateStore = new CohortStateStore(paths.dataDir);
+    let state = await stateStore.read();
+    const launchDuringUpdate = async () => {
+        // Concurrency: read the journal before touching npm's mutable tree, including package.json.
+        const transaction = await new UpdateTransactionStore(paths.dataDir).read();
+        if (!transaction || transaction.status === "completed")
+            return null;
+        const prior = selectUpdateLaunchRelease(await stateStore.read(), transaction);
+        if (!prior)
+            return null;
+        const retained = await readCertifiedReleaseManifest(prior, resolve(paths.dataDir, "releases"));
+        await ensureSupervisor(retained, environment);
+        return await launchUi(retained, environment, sessionArgs);
+    };
+    const duringUpdate = await launchDuringUpdate();
+    if (duringUpdate !== null)
+        return duringUpdate;
+    // Invariant: records left by cohorts whose processes are gone say nothing about ownership, and there
+    // can now be several of them. Clearing them first keeps the decision below about what is
+    // actually running.
+    await sweepDeadEndpoints(paths).catch(() => []);
+    // Performance: reconciliation is serialized by cohort state, but launch never awaits a physical
+    // backlog. The scheduler commits a plan and starts a detached bounded worker.
+    const scheduleMaintenance = options.scheduleMaintenance ?? scheduleReleaseCleanup;
+    void scheduleMaintenance(paths.dataDir, paths).catch(() => { });
+    // Protocol: each cohort keeps its own endpoint, so a launch looks for the endpoint of the release it
+    // is about to run rather than for the one endpoint the runtime directory used to have.
+    const activeReleaseId = state.references.active;
+    let endpointPaths = activeReleaseId === null
+        ? { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath }
+        : resolveCohortEndpoint(paths, activeReleaseId, environment);
+    let endpoint = await readEndpointMetadata(endpointPaths.endpointMetadataPath);
+    if (endpoint === null) {
+        // Compatibility: a release that predates cohort-scoped endpoints published one endpoint for the whole
+        // runtime directory. Recognizing it is what lets a session started by that release keep
+        // working through the first launch that knows about cohorts.
+        const legacy = await readEndpointMetadata(paths.endpointMetadataPath);
+        if (legacy !== null) {
+            endpoint = legacy;
+            endpointPaths = { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+        }
+    }
+    let probe = endpoint ? await probeOwnership(endpoint) : "dead";
+    const installedVersion = await readInstalledVersion(options.packageRoot);
+    const activeId = state.references.active;
+    const active = activeId === null ? undefined : state.releases[activeId];
+    const activeIsLaunchable = active === undefined || (options.releaseIsLaunchable?.(active.releaseRoot) ?? true);
+    if (activeIsLaunchable && active?.approval === "approved" && active.packageVersion === installedVersion) {
+        const endpointMatches = endpoint?.releaseId === active.releaseId
+            && endpoint.releaseRoot === active.releaseRoot
+            && endpoint.contentDigest === active.contentDigest;
+        if (endpointMatches && probe === "live-verified") {
+            const retained = await readCertifiedReleaseManifest(active, resolve(paths.dataDir, "releases"));
+            return await launchUi(retained, environment, sessionArgs);
+        }
+        if (endpoint === null || probe === "dead") {
+            if (endpoint)
+                await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
+            await markStartupPhase(environment, "durable-validation-start");
+            const retained = await readRestartCertifiedRelease(active, paths.dataDir).catch(async () => {
+                const verified = await readMaterializedRelease(active.releaseRoot, resolve(paths.dataDir, "releases"));
+                if (verified.releaseId !== active.releaseId || verified.contentDigest !== active.contentDigest || verified.packageVersion !== active.packageVersion) {
+                    throw new Error("completely verified release differs from the approved active record");
+                }
+                await certifyMaterializedRelease(verified, paths.dataDir);
+                return verified;
+            });
+            await markStartupPhase(environment, "durable-validation-complete");
+            await markStartupPhase(environment, "replacement-supervisor-start");
+            await ensureSupervisor(retained, environment);
+            await markStartupPhase(environment, "replacement-supervisor-ready");
+            return await launchUi(retained, environment, sessionArgs);
+        }
+    }
+    // Concurrency: an installation being replaced is not a reason to refuse a launch. While
+    // npm is rewriting the package tree the candidate cannot be read consistently, so a
+    // launch that cannot take the installed payload starts the retained active release
+    // instead and leaves activation to the launch that follows the replacement.
+    let candidate;
+    try {
+        candidate = await materializeRelease(options.packageRoot, paths.dataDir);
+    }
+    catch (error) {
+        const fallback = await launchRetainedActive(state, paths, environment, sessionArgs, output);
+        if (fallback === null)
+            throw error;
+        return fallback;
+    }
+    // Concurrency: an update may have begun while this launch was reading the installed payload.
+    const afterMaterialization = await launchDuringUpdate();
+    if (afterMaterialization !== null)
+        return afterMaterialization;
+    await stateStore.recordCandidate(candidate);
+    state = await stateStore.read();
+    if (!state.references.active) {
+        const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
+        await stateStore.approve(candidate.releaseId, diagnosticsPath);
+        await stateStore.activate(candidate.releaseId);
+        state = await stateStore.read();
+    }
+    else if (!activeIsLaunchable && candidate.releaseId !== activeId
+        && state.releases[candidate.releaseId]?.approval !== "approved") {
+        // Invariant: the active reference points at a copy that cannot launch, so reusing it
+        // is off the table — but an unapproved candidate would lose the selection
+        // below to that same broken active (`start-active`). Approving the healed
+        // candidate here lets ordinary cohort selection activate it, while a live
+        // busy cohort still wins the endpoint checks and keeps its sessions.
+        const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
+        await stateStore.approve(candidate.releaseId, diagnosticsPath);
+        state = await stateStore.read();
+    }
+    // Protocol: the candidate's own endpoint decides whether this launch attaches or starts a supervisor.
+    // A cohort other than this one is not in the way: it listens somewhere else.
+    endpointPaths = resolveCohortEndpoint(paths, candidate.releaseId, environment);
+    endpoint = await readEndpointMetadata(endpointPaths.endpointMetadataPath);
+    if (endpoint === null) {
+        const legacy = await readEndpointMetadata(paths.endpointMetadataPath);
+        if (legacy !== null) {
+            endpoint = legacy;
+            endpointPaths = { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath };
+        }
+    }
+    probe = endpoint ? await probeOwnership(endpoint) : "dead";
+    let decision = selectCohortLaunch(candidate, state, endpoint, probe);
+    if (decision.action === "blocked") {
+        await stateStore.blockPending(decision.reason, endpoint?.ownership.liveInstanceIds ?? []);
+        output.write(`${PRODUCT_TEXT.diagnostic(`startup is blocked to preserve uncertain live ownership: ${decision.reason}`)}\n`);
+        return 1;
+    }
+    if (decision.action === "clean-stale-owner" && endpoint) {
+        const diagnostics = await cleanupProvenIdleOwner(endpoint);
+        await writeFile(resolve(paths.dataDir, `cleanup-${Date.now()}.json`), JSON.stringify(diagnostics, null, 2));
+        if (!diagnostics.terminated)
+            throw new Error(`could not safely clean stale ${PRODUCT_TEXT.displayName} supervisor ${endpoint.pid}`);
+        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
+        decision = selectCohortLaunch(candidate, await stateStore.read(), null, "dead");
+    }
+    else if (endpoint && probe === "dead") {
+        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
+    }
+    if (decision.action === "launch-retained-ui") {
+        const retained = await verifyMaterializedRelease(decision.releaseRoot, undefined, resolve(paths.dataDir, "releases"));
+        if (decision.recordPending && endpoint) {
+            await stateStore.blockPending("candidate activation deferred by live non-resumable instances", endpoint.ownership.nonResumableInstanceIds);
+        }
+        const code = await launchUi(retained, environment, sessionArgs);
+        if (decision.recordPending)
+            await activatePendingAfterBlockerExit(candidate, stateStore, paths, environment);
+        return code;
+    }
+    if (decision.action === "replace-idle-cohort" && endpoint) {
+        const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
+        await stateStore.approve(candidate.releaseId, diagnosticsPath);
+        const released = await requestIdleOwnershipRelease(endpoint, candidate.releaseId, 2_000);
+        if (!released) {
+            await stateStore.blockPending("idle supervisor did not verify ownership release", endpoint.ownership.liveInstanceIds);
+            output.write(`${PRODUCT_TEXT.diagnostic("could not verify idle cohort ownership release; the retained release remains selected.")}\n`);
+            return 1;
+        }
+        if (!await releaseVerifiedIdleOwner(endpoint, paths.dataDir)) {
+            await stateStore.blockPending("idle supervisor acknowledged release but did not terminate", endpoint.ownership.liveInstanceIds);
+            output.write(`${PRODUCT_TEXT.diagnostic("could not complete bounded idle cohort shutdown; the candidate remains pending.")}\n`);
+            return 1;
+        }
+        await removeEndpointArtifacts(endpointPaths.endpointMetadataPath, endpointPaths.endpoint);
+        await stateStore.activate(candidate.releaseId);
+        decision = { action: "activate-candidate", releaseId: candidate.releaseId, releaseRoot: candidate.releaseRoot, reason: "idle cohort released ownership" };
+    }
+    let selected;
+    if (decision.action === "activate-candidate") {
+        const current = await stateStore.read();
+        if (current.releases[candidate.releaseId]?.approval !== "approved") {
+            const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
+            await stateStore.approve(candidate.releaseId, diagnosticsPath);
+        }
+        if ((await stateStore.read()).references.active !== candidate.releaseId)
+            await stateStore.activate(candidate.releaseId);
+        selected = candidate;
+    }
+    else {
+        selected = await readMaterializedRelease(decision.releaseRoot);
+    }
+    await ensureSupervisor(selected, environment);
+    return await launchUi(selected, environment, sessionArgs);
+}
+/**
+ * Start the retained active cohort when the installed payload cannot be taken. The
+ * release already carries certified evidence, so this reuses it rather than
+ * certifying anything new, and reports no selection when there is nothing safe
+ * to fall back to.
+ */
+async function launchRetainedActive(state, paths, environment, sessionArgs, output) {
+    const activeId = state.references.active;
+    const active = activeId === null ? undefined : state.releases[activeId];
+    if (!active || active.approval !== "approved")
+        return null;
+    try {
+        const retained = await readCertifiedReleaseManifest(active, resolve(paths.dataDir, "releases"));
+        await ensureSupervisor(retained, environment);
+        output.write(`${PRODUCT_TEXT.diagnostic(`installation is being replaced; starting the retained release ${retained.packageVersion}`)}\n`);
+        return await launchUi(retained, environment, sessionArgs);
+    }
+    catch {
+        return null;
+    }
+}
+async function readInstalledVersion(packageRoot) {
+    const manifest = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
+    if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+        throw new Error(PRODUCT_TEXT.diagnostic("package metadata has no version"));
+    }
+    return manifest.version;
+}
+export async function certifyMaterializedRelease(release, dataDir, verification = {}) {
+    if (!consumeMaterializationProof(release)) {
+        await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"), verification);
+    }
+    return await recordParentCertifiedRelease(release, dataDir);
+}
+/** Persist current-format evidence after an authenticated parent has certified the exact release. */
+export async function recordParentCertifiedRelease(release, dataDir) {
+    const path = resolve(dataDir, `certification-${release.releaseId}.json`);
+    const restartSeal = await createRestartSeal(release, dataDir);
+    await chmod(path, 0o600).catch(() => { });
+    await writeFile(path, JSON.stringify(releaseCertificationDocument(release, restartSeal), null, 2), { mode: 0o600 });
+    await chmod(path, 0o400);
+    return path;
+}
+/** Reuse a verified owner, or join the winner if another launch starts the same cohort first. */
+export async function ensureSupervisor(release, environment) {
+    const paths = resolveCohortEndpoint(resolveProductPaths(environment), release.releaseId, environment);
+    const metadata = await readEndpointMetadata(paths.endpointMetadataPath);
+    if (metadata) {
+        const probe = await probeOwnership(metadata);
+        if (probe !== "dead") {
+            if (probe === "live-verified" && endpointMatchesRelease(metadata, release))
+                return;
+            throw new Error(PRODUCT_TEXT.diagnostic(`refused duplicate supervisor startup: existing ownership is ${probe}`));
+        }
+    }
+    const startup = await startSupervisor(release, environment);
+    await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000, startup);
+}
+function endpointMatchesRelease(metadata, release) {
+    return metadata.releaseId === release.releaseId && metadata.releaseRoot === release.releaseRoot
+        && metadata.contentDigest === release.contentDigest;
+}
+export async function startSupervisor(release, environment) {
+    const entry = await resolveReleaseEntryPoint(release, "bin/supervisor.js");
+    const paths = resolveProductPaths(environment);
+    const attempt = await createSupervisorStartupAttempt(paths.runtimeDir, release.releaseId);
+    const child = spawn(process.execPath, [entry, "--startup-attempt", attempt.attemptId], {
+        detached: true,
+        env: releaseEnvironment(environment, release),
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    const childOutcome = new Promise(resolvePromise => {
+        child.once("close", (exitCode, signal) => resolvePromise({ exitCode, signal }));
+    });
+    await new Promise((resolvePromise, rejectPromise) => {
+        child.once("spawn", resolvePromise);
+        child.once("error", rejectPromise);
+    });
+    child.unref();
+    return { ...attempt, childOutcome };
+}
+async function launchUi(release, environment, sessionArgs) {
+    await markStartupPhase(environment, "bootstrap-selected");
+    const entry = await resolveReleaseEntryPoint(release, "bin/guardian.js");
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [entry, ...sessionArgs], {
+            env: releaseEnvironment(environment, release, readLaunchContext(environment, "profile").launchProfile),
+            stdio: "inherit",
+            windowsHide: false,
+        });
+        child.once("error", rejectPromise);
+        child.once("close", (code, signal) => resolvePromise(restoreAfterOwnedExit(readLaunchContext(environment).launchProfile === "a1", code, signal)));
+    });
+}
+/**
+ * Hand a release the key set its own build reads. A retained pre-cutover release is
+ * still startable this way, which is what lets a launch fall back to the previous
+ * version instead of failing while an installation is being replaced.
+ */
+export function releaseEnvironment(environment, release, profile) {
+    return withLaunchContext(environment, {
+        releaseId: release.releaseId,
+        releaseLayers: (release.dependencyLayers ?? []).map(layer => layer.layerId).join(","),
+        releaseRoot: release.releaseRoot,
+        releaseDigest: release.contentDigest,
+        ...(profile === undefined ? {} : { launchProfile: profile }),
+    }, process.platform, launchContractTarget(release));
+}
+export async function waitForVerifiedEndpoint(path, release, timeoutMs, startup) {
+    const deadline = Date.now() + timeoutMs;
+    let childOutcome = null;
+    let collision = null;
+    void startup?.childOutcome.then(outcome => { childOutcome = outcome; });
+    while (Date.now() < deadline) {
+        const metadata = await readEndpointMetadata(path);
+        if (metadata && endpointMatchesRelease(metadata, release) && await probeOwnership(metadata) === "live-verified") {
+            if (startup)
+                await rm(startup.resultPath, { force: true });
+            return;
+        }
+        if (startup) {
+            const result = await readSupervisorStartupResult(startup.resultPath, startup.attemptId, startup.releaseId);
+            if (result?.outcome === "failure") {
+                const error = Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor startup failed at ${result.stage}: ${result.message}`)), {
+                    code: result.code ?? "SUPERVISOR_STARTUP_FAILED",
+                });
+                if (result.code !== "EADDRINUSE")
+                    throw error;
+                // Concurrency: the winning process may not have published its authenticated metadata yet.
+                collision = error;
+            }
+        }
+        if (childOutcome && !collision)
+            throw new Error(PRODUCT_TEXT.diagnostic(`supervisor exited before readiness: ${JSON.stringify(childOutcome)}`));
+        await new Promise(resolvePromise => setTimeout(resolvePromise, 40));
+    }
+    if (collision)
+        throw collision;
+    throw new Error(PRODUCT_TEXT.diagnostic(`supervisor did not publish verified endpoint metadata within ${timeoutMs}ms`));
+}
+async function activatePendingAfterBlockerExit(candidate, stateStore, paths, environment) {
+    const deadline = Date.now() + 2_000;
+    let endpoint = null;
+    while (Date.now() < deadline) {
+        endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
+        if (!endpoint || endpoint.ownership.liveInstanceIds.length === 0)
+            break;
+        await new Promise(resolvePromise => setTimeout(resolvePromise, 40));
+    }
+    if (!endpoint || endpoint.ownership.liveInstanceIds.length > 0 || await probeOwnership(endpoint) !== "live-verified")
+        return;
+    const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
+    await stateStore.approve(candidate.releaseId, diagnosticsPath);
+    if (!await requestIdleOwnershipRelease(endpoint, candidate.releaseId, 2_000))
+        return;
+    if (!await releaseVerifiedIdleOwner(endpoint, paths.dataDir))
+        return;
+    await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
+    await stateStore.activate(candidate.releaseId);
+    await ensureSupervisor(candidate, environment);
+}
+export async function releaseVerifiedIdleOwner(metadata, dataDir, operations = {}) {
+    try {
+        await (operations.waitForExit ?? waitForProcessExit)(metadata.pid, 3_000);
+        return true;
+    }
+    catch {
+        // Security: the authenticated idle-release handshake authorizes bounded cleanup of
+        // this exact boot when a native handle outlives graceful shutdown.
+        const diagnostics = await (operations.cleanup ?? cleanupProvenIdleOwner)(metadata);
+        await writeFile(resolve(dataDir, `cleanup-${Date.now()}.json`), JSON.stringify(diagnostics, null, 2));
+        return diagnostics.terminated;
+    }
+}
+async function requestIdleOwnershipRelease(metadata, candidateReleaseId, timeoutMs) {
+    return await new Promise(resolvePromise => {
+        const socket = connect(metadata.endpoint);
+        const decoder = new LineFrameDecoder();
+        let settled = false;
+        const finish = (released) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolvePromise(released);
+        };
+        socket.once("error", () => finish(false));
+        socket.once("connect", () => socket.write(encodeFrame({ type: "release-idle-ownership", bootNonce: metadata.bootNonce, candidateReleaseId })));
+        socket.on("data", chunk => {
+            try {
+                const message = decoder.push(chunk)[0];
+                if (message?.type === "release-ownership-result")
+                    finish(message.released === true);
+            }
+            catch {
+                finish(false);
+            }
+        });
+        setTimeout(() => finish(false), timeoutMs).unref();
+    });
+}
+export async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!processIsAlive(pid))
+            return;
+        await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
+    }
+    throw new Error(PRODUCT_TEXT.diagnostic(`supervisor ${pid} did not release process ownership within ${timeoutMs}ms`));
+}

package/dist/foundation/release/cohort-state.d.ts

@@ -0,0 +1,157 @@
+import type { MaterializedRelease } from "./release-store.js";
+export declare const RELEASE_COHORT_SCHEMA: string;
+export type ReleaseApproval = "candidate" | "approved" | "rejected";
+export interface ReleaseRecord {
+    readonly releaseId: string;
+    readonly releaseRoot: string;
+    readonly packageVersion: string;
+    readonly contentDigest: string;
+    readonly launchContract?: string;
+    readonly approval: ReleaseApproval;
+    readonly materializedAt: string;
+    readonly certifiedAt: string | null;
+    readonly diagnosticsPath: string | null;
+}
+export interface ReleaseReferences {
+    readonly active: string | null;
+    readonly pending: string | null;
+    readonly approved: string | null;
+    readonly rollback: string | null;
+    readonly retention: readonly string[];
+}
+export type ExternalReleaseHoldAuthority = "agent" | "migration";
+/** A current hold supplied by an authority that must participate in every reconciliation. */
+export interface ExternalReleaseHold {
+    readonly authority: ExternalReleaseHoldAuthority;
+    readonly releaseId: string;
+}
+export interface ActiveReleaseTransactionReference {
+    readonly status: "active" | "completed" | "rolled-back" | "failed";
+    readonly priorActiveReleaseId: string | null;
+}
+export type ReleaseCleanupStage = "detached" | "trash";
+export interface ReleaseCleanupDisposition {
+    readonly release: ReleaseRecord;
+    readonly stage: ReleaseCleanupStage;
+    readonly trashPath: string | null;
+    readonly attempts: number;
+    readonly lastAttemptAt: string | null;
+    readonly lastError: string | null;
+}
+export interface ReleaseCleanupDiagnostic {
+    readonly releaseId: string;
+    readonly stage: string;
+    readonly attemptedAt: string;
+    readonly error: string;
+}
+export type ReleaseCleanupWorkerStatus = "scheduled" | "running" | "completed" | "blocked" | "continued" | "failed" | "skipped";
+export interface ReleaseCleanupWorkerRun {
+    readonly runId: string;
+    readonly status: ReleaseCleanupWorkerStatus;
+    readonly scheduledAt: string;
+    readonly startedAt: string | null;
+    readonly completedAt: string | null;
+    readonly pid: number | null;
+    readonly batches: number;
+    readonly attempted: number;
+    readonly completed: number;
+    readonly remaining: number;
+    readonly error: string | null;
+}
+export interface ReleaseCleanupWorkerSummary {
+    readonly batches: number;
+    readonly attempted: number;
+    readonly completed: number;
+    readonly remaining: number;
+}
+export interface ReleaseCleanupState {
+    readonly pending: Readonly<Record<string, ReleaseCleanupDisposition>>;
+    readonly diagnostics: readonly ReleaseCleanupDiagnostic[];
+    readonly workerRuns: readonly ReleaseCleanupWorkerRun[];
+}
+export interface CohortState {
+    readonly schema: typeof RELEASE_COHORT_SCHEMA;
+    readonly revision: number;
+    readonly releases: Readonly<Record<string, ReleaseRecord>>;
+    readonly references: ReleaseReferences;
+    readonly cleanup: ReleaseCleanupState;
+    readonly activation: {
+        readonly state: "idle" | "pending" | "draining" | "blocked" | "failed";
+        readonly reason: string | null;
+        readonly blockerGenerationIds: readonly string[];
+        readonly updatedAt: string;
+    };
+}
+export interface EndpointOwnership {
+    readonly state: "idle" | "busy" | "draining" | "released" | "blocked";
+    readonly liveInstanceIds: readonly string[];
+    readonly nonResumableInstanceIds: readonly string[];
+    readonly uncertainInstanceIds: readonly string[];
+}
+export interface SupervisorEndpointMetadata {
+    readonly schema: string;
+    readonly supervisorId: string;
+    readonly endpoint: string;
+    readonly pid: number;
+    readonly pidStartIdentity: string;
+    readonly bootNonce: string;
+    readonly startedAt: string;
+    readonly releaseId: string;
+    readonly releaseRoot: string;
+    readonly contentDigest: string;
+    readonly ownership: EndpointOwnership;
+    readonly envelope: string;
+    readonly envelopeRevision: number;
+    readonly requiredFeatures: readonly string[];
+    readonly optionalFeatures: readonly string[];
+    readonly contractDigest: string;
+}
+export interface ProtectedReleaseInputs {
+    readonly liveReleaseIds?: readonly string[];
+    readonly externalHolds?: readonly ExternalReleaseHold[];
+    readonly transaction?: ActiveReleaseTransactionReference | null;
+}
+export interface ProtectedReleasePlan {
+    readonly protectedReleaseIds: readonly string[];
+    readonly retainedReleaseIds: readonly string[];
+    readonly collectibleReleaseIds: readonly string[];
+}
+export interface OrphanReleaseDisposition {
+    readonly release: ReleaseRecord;
+    readonly stage: ReleaseCleanupStage;
+    readonly trashPath?: string | null;
+}
+export interface ReleaseRetentionReconciliation {
+    readonly state: CohortState;
+    readonly plan: ProtectedReleasePlan;
+    readonly detachedReleaseIds: readonly string[];
+}
+/**
+ * Derive protection exclusively from current selectors and ownership authorities.
+ * The historical retention snapshot is deliberately not an input to this plan.
+ */
+export declare function planProtectedReleases(state: CohortState, inputs?: ProtectedReleaseInputs): ProtectedReleasePlan;
+/** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
+export declare class CohortStateStore {
+    readonly path: string;
+    constructor(dataDir: string);
+    read(): Promise<CohortState>;
+    update(operation: (current: CohortState) => CohortState | Promise<CohortState>): Promise<CohortState>;
+    recordCandidate(release: MaterializedRelease): Promise<CohortState>;
+    approve(releaseId: string, diagnosticsPath: string): Promise<CohortState>;
+    activate(releaseId: string): Promise<CohortState>;
+    blockPending(reason: string, blockerGenerationIds: readonly string[]): Promise<CohortState>;
+    rollback(ownershipReleased: boolean): Promise<CohortState>;
+    setRetention(releaseIds: readonly string[]): Promise<CohortState>;
+    /** Atomically replace legacy retention history and detach every currently collectible record. */
+    reconcileRetention(resolveInputs: (current: CohortState) => ProtectedReleaseInputs | Promise<ProtectedReleaseInputs>, orphans?: readonly OrphanReleaseDisposition[]): Promise<ReleaseRetentionReconciliation>;
+    markCleanupTrash(releaseId: string, trashPath: string): Promise<CohortState>;
+    recordCleanupFailure(releaseId: string, stage: string, error: unknown): Promise<CohortState>;
+    completeCleanup(releaseId: string): Promise<CohortState>;
+    recordCleanupWorkerScheduled(runId: string): Promise<CohortState>;
+    recordCleanupWorkerStarted(runId: string, pid: number): Promise<CohortState>;
+    recordCleanupWorkerProgress(runId: string, summary: ReleaseCleanupWorkerSummary): Promise<CohortState>;
+    recordCleanupWorkerFinished(runId: string, status: Exclude<ReleaseCleanupWorkerStatus, "scheduled" | "running">, summary: ReleaseCleanupWorkerSummary, error?: unknown): Promise<CohortState>;
+    removeUnreferencedRelease(releaseId: string, externalReferences: readonly string[]): Promise<CohortState>;
+}
+export declare function emptyState(): CohortState;