@timurproko/a1 0.1.1-dev.1 → 0.1.1-dev.11

package/dist/src/foundation/process-containment/index.js

@@ -0,0 +1,5 @@
+export * from "./artifact.js";
+export * from "./contracts.js";
+export * from "./linux-process-inspector.js";
+export * from "./native-guardian-containment.js";
+export * from "./windows-process-inspector.js";

package/dist/src/foundation/process-containment/linux-process-inspector.d.ts

@@ -0,0 +1,6 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+export declare class LinuxNativeProcessInspector implements NativeProcessInspector {
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

package/dist/src/foundation/process-containment/linux-process-inspector.js

@@ -0,0 +1,26 @@
+import { readFile } from "node:fs/promises";
+export class LinuxNativeProcessInspector {
+    async observe(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new TypeError("inspected PID must be a positive safe integer");
+        let stat;
+        try {
+            stat = await readFile(`/proc/${pid}/stat`, "utf8");
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+        const commandEnd = stat.lastIndexOf(")");
+        const fields = commandEnd >= 0 ? stat.slice(commandEnd + 1).trim().split(/\s+/) : [];
+        const startTicks = fields[19];
+        if (!startTicks || !/^\d+$/.test(startTicks))
+            throw new Error("process stat has no valid start-time field");
+        return { pid, startIdentity: `linux-proc-start:${startTicks}` };
+    }
+    async matches(identity) {
+        const observed = await this.observe(identity.pid);
+        return observed !== null && observed.startIdentity === identity.startIdentity;
+    }
+}

package/dist/src/foundation/process-containment/native-guardian-containment.d.ts

@@ -0,0 +1,16 @@
+import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+import type { ContainedProcessHandle, ContainedSpawnOptions, ProcessContainment } from "./contracts.js";
+export declare class NativeGuardianContainment implements ProcessContainment {
+    #private;
+    readonly instanceId: string;
+    readonly helperPath: string;
+    readonly statusPath: string;
+    constructor(instanceId: string, helperPath: string, statusPath: string);
+    get identity(): ProcessContainmentIdentity;
+    spawn(executable: string, arguments_: readonly string[], options: ContainedSpawnOptions): Promise<ContainedProcessHandle>;
+    contains(identity: NativeProcessIdentity): Promise<boolean>;
+    stop(force: boolean): Promise<void>;
+    waitForEmpty(timeoutMs: number): Promise<boolean>;
+    close(): Promise<void>;
+}
+export declare function resolveProcessGuardianPath(releaseRoot: string, environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, architecture?: string): string;

package/dist/src/foundation/process-containment/native-guardian-containment.js

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export class NativeGuardianContainment {
+    instanceId;
+    helperPath;
+    statusPath;
+    #identity;
+    #helper = null;
+    #rootIdentity = null;
+    #outcome = null;
+    constructor(instanceId, helperPath, statusPath) {
+        this.instanceId = instanceId;
+        this.helperPath = helperPath;
+        this.statusPath = statusPath;
+        this.#identity = { provider: "native-guardian-pending", token: instanceId };
+    }
+    get identity() {
+        return this.#identity;
+    }
+    async spawn(executable, arguments_, options) {
+        if (this.#helper)
+            throw new Error("process containment already has a root runtime");
+        await mkdir(dirname(this.statusPath), { recursive: true, mode: 0o700 });
+        await rm(this.statusPath, { force: true });
+        const helper = spawn(this.helperPath, [
+            "--parent-pid", String(process.pid),
+            "--instance", this.instanceId,
+            "--status-file", this.statusPath,
+            "--", executable, ...arguments_,
+        ], {
+            cwd: options.cwd,
+            env: { ...options.environment, ...(options.terminalType ? { TERM: options.terminalType } : {}) },
+            shell: false,
+            stdio: "inherit",
+            windowsHide: false,
+        });
+        this.#helper = helper;
+        this.#outcome = helperOutcome(helper);
+        const status = await waitForReadyStatus(this.statusPath, this.#outcome, 5_000);
+        this.#rootIdentity = { pid: status.pid, startIdentity: status.startIdentity };
+        this.#identity = { provider: status.containmentProvider, token: status.containmentToken };
+        return { identity: this.#rootIdentity, outcome: this.#outcome };
+    }
+    async contains(identity) {
+        return this.#rootIdentity !== null
+            && identity.pid === this.#rootIdentity.pid
+            && identity.startIdentity === this.#rootIdentity.startIdentity;
+    }
+    async stop(force) {
+        const root = this.#rootIdentity;
+        if (!root)
+            return;
+        try {
+            process.kill(root.pid, force ? "SIGKILL" : "SIGTERM");
+        }
+        catch { }
+    }
+    async waitForEmpty(timeoutMs) {
+        if (!this.#helper || this.#helper.exitCode !== null || this.#helper.signalCode !== null)
+            return true;
+        return await new Promise(resolvePromise => {
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            timer.unref();
+            const finish = (empty) => {
+                clearTimeout(timer);
+                this.#helper?.off("close", onClose);
+                resolvePromise(empty);
+            };
+            const onClose = () => finish(true);
+            this.#helper?.once("close", onClose);
+        });
+    }
+    async close() {
+        const helper = this.#helper;
+        if (helper && helper.exitCode === null && helper.signalCode === null)
+            helper.kill("SIGKILL");
+        await this.waitForEmpty(1_500);
+        await rm(this.statusPath, { force: true });
+    }
+}
+export function resolveProcessGuardianPath(releaseRoot, environment = process.env, platform = process.platform, architecture = process.arch) {
+    const override = environment[PRODUCT_IDENTITY.environment.processGuardianPath]?.trim();
+    if (override)
+        return resolve(override);
+    const executable = platform === "win32"
+        ? `${PRODUCT_IDENTITY.artifacts.processGuardianExecutable}.exe`
+        : PRODUCT_IDENTITY.artifacts.processGuardianExecutable;
+    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, executable);
+}
+function helperOutcome(helper) {
+    return new Promise(resolvePromise => {
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise(outcome);
+        };
+        helper.once("error", error => settle({ kind: "guardian-error", message: error.message, code: errorCode(error) }));
+        helper.once("close", (code, signal) => {
+            if (signal)
+                settle({ kind: "signaled", signal });
+            else
+                settle({ kind: "exited", exitCode: code ?? 1 });
+        });
+    });
+}
+async function waitForReadyStatus(path, outcome, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let terminalOutcome = null;
+    void outcome.then(value => { terminalOutcome = value; });
+    while (Date.now() < deadline) {
+        try {
+            const value = JSON.parse(await readFile(path, "utf8"));
+            if (isReadyStatus(value))
+                return value;
+            throw new Error("process guardian published invalid ready status");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        if (terminalOutcome)
+            throw new Error(`process guardian exited before readiness: ${JSON.stringify(terminalOutcome)}`);
+        await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
+    }
+    throw new Error(`process guardian did not publish readiness within ${timeoutMs}ms`);
+}
+function isReadyStatus(value) {
+    return Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+        && typeof value.startIdentity === "string" && value.startIdentity.length > 0
+        && typeof value.containmentProvider === "string" && value.containmentProvider.length > 0
+        && typeof value.containmentToken === "string" && value.containmentToken.length > 0;
+}
+function errorCode(error) {
+    return "code" in error && typeof error.code === "string" ? error.code : null;
+}

package/dist/src/foundation/process-containment/windows-process-inspector.d.ts

@@ -0,0 +1,17 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+export interface InspectorCommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface InspectorCommandRunner {
+    run(executable: string, arguments_: readonly string[]): Promise<InspectorCommandResult>;
+}
+export declare class WindowsNativeProcessInspector implements NativeProcessInspector {
+    readonly helperPath: string;
+    private readonly runner;
+    constructor(helperPath: string, runner?: InspectorCommandRunner);
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

package/dist/src/foundation/process-containment/windows-process-inspector.js

@@ -0,0 +1,53 @@
+import { execFile } from "node:child_process";
+export class WindowsNativeProcessInspector {
+    helperPath;
+    runner;
+    constructor(helperPath, runner = defaultRunner) {
+        this.helperPath = helperPath;
+        this.runner = runner;
+        if (!helperPath || helperPath.includes("\0"))
+            throw new TypeError("process guardian helper path is invalid");
+    }
+    async observe(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new TypeError("inspected PID must be a positive safe integer");
+        const result = await this.runner.run(this.helperPath, ["--inspect-pid", String(pid)]);
+        if (result.exitCode === 3)
+            return null;
+        if (result.exitCode !== 0) {
+            const detail = result.stderr.trim() || `helper exited ${result.exitCode}`;
+            throw Object.assign(new Error(`cannot inspect native process identity: ${detail}`), { code: "PROCESS_INSPECTION_FAILED" });
+        }
+        let value;
+        try {
+            value = JSON.parse(result.stdout);
+        }
+        catch {
+            throw Object.assign(new Error("process guardian returned malformed identity data"), { code: "PROCESS_INSPECTION_INVALID" });
+        }
+        if (!isIdentity(value) || value.pid !== pid || !value.startIdentity.startsWith("windows-filetime:")) {
+            throw Object.assign(new Error("process guardian returned mismatched identity data"), { code: "PROCESS_INSPECTION_INVALID" });
+        }
+        return value;
+    }
+    async matches(identity) {
+        const observed = await this.observe(identity.pid);
+        return observed !== null && observed.startIdentity === identity.startIdentity;
+    }
+}
+const defaultRunner = {
+    async run(executable, arguments_) {
+        return await new Promise(resolvePromise => {
+            execFile(executable, [...arguments_], { windowsHide: true, timeout: 2_000, maxBuffer: 8 * 1_024 }, (error, stdout, stderr) => {
+                const exitCode = error && "code" in error && typeof error.code === "number" ? error.code : error ? 1 : 0;
+                resolvePromise({ exitCode, stdout, stderr });
+            });
+        });
+    },
+};
+function isIdentity(value) {
+    return typeof value === "object" && value !== null
+        && "pid" in value && Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+        && "startIdentity" in value && typeof value.startIdentity === "string"
+        && value.startIdentity.length > 0 && value.startIdentity.length <= 512 && !value.startIdentity.includes("\0");
+}

package/dist/src/foundation/protocol/client.d.ts

@@ -1,7 +1,8 @@
 import { EventEmitter } from "node:events";
-import type { CommandResult, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
+import type { CommandResult, LaunchInstanceStopIntent, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
 interface ClientEvents {
     snapshot: [SupervisorSnapshot];
+    stopIntent: [LaunchInstanceStopIntent];
     disconnect: [];
 }
 export declare class SupervisorClient extends EventEmitter<ClientEvents> {

package/dist/src/foundation/protocol/client.js

@@ -91,6 +91,9 @@ export class SupervisorClient extends EventEmitter {
                                 pending.resolve(message.result);
                             }
                         }
+                        else if (message.type === "stop-launch-instance" && message.instanceId && message.requestId && message.reason) {
+                            this.emit("stopIntent", message);
+                        }
                         else if (message.type === "protocol-error") {
                             fail(new Error(message.message ?? "protocol error"));
                         }

package/dist/src/foundation/protocol/messages.d.ts

@@ -1,7 +1,7 @@
-import type { CommandResult, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
+import type { CommandResult, LaunchInstanceStopIntent, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
 export declare const CONTROL_ENVELOPE: string;
 export declare const CONTROL_ENVELOPE_REVISION: 1;
-export declare const REQUIRED_CONTROL_FEATURES: readonly ["handshake.features.v1", "snapshot.revision.v1", "commands.request-identity.v1", "generation.lifecycle.v1", "terminal.foreground-lease.v1"];
+export declare const REQUIRED_CONTROL_FEATURES: readonly ["handshake.features.v1", "snapshot.revision.v1", "commands.request-identity.v1", "generation.lifecycle.v1", "launch.instance-lifecycle.v1"];
 export declare const OPTIONAL_CONTROL_FEATURES: readonly ["messages.unknown-additive-ignore.v1", "snapshot.resynchronize.v1"];
 export type ControlFeature = string;
 export declare const GENERATED_CONTRACT_DIGEST: string;
@@ -41,12 +41,12 @@ export type ServerMessage = {
     readonly type: "release-ownership-result";
     readonly released: boolean;
     readonly reason: string;
-    readonly liveGenerationIds: readonly string[];
+    readonly liveInstanceIds: readonly string[];
 } | {
     readonly type: "release-update-result";
     readonly accepted: boolean;
     readonly reason: string;
-    readonly liveGenerationIds: readonly string[];
+    readonly liveInstanceIds: readonly string[];
 } | ({
     readonly type: "server-hello";
     readonly supervisorId: string;
@@ -60,7 +60,7 @@ export type ServerMessage = {
 } | {
     readonly type: "command-result";
     readonly result: CommandResult;
-} | {
+} | LaunchInstanceStopIntent | {
     readonly type: "protocol-error";
     readonly code: string;
     readonly message: string;

package/dist/src/foundation/protocol/messages.js

@@ -7,7 +7,7 @@ export const REQUIRED_CONTROL_FEATURES = [
     "snapshot.revision.v1",
     "commands.request-identity.v1",
     "generation.lifecycle.v1",
-    "terminal.foreground-lease.v1",
+    "launch.instance-lifecycle.v1",
 ];
 export const OPTIONAL_CONTROL_FEATURES = [
     "messages.unknown-additive-ignore.v1",

package/dist/src/foundation/release/bootstrap.d.ts

@@ -2,7 +2,7 @@ import { type OwnershipProbe } from "./cohort-selection.js";
 import { type SupervisorEndpointMetadata } from "./cohort-state.js";
 import { type LaunchProfileId } from "../lifecycle/index.js";
 import { cleanupProvenIdleOwner } from "./process-cleanup.js";
-import { type MaterializedRelease } from "./release-store.js";
+import { type MaterializedRelease, type VerifyMaterializedReleaseOptions } from "./release-store.js";
 export interface BootstrapOptions {
     readonly packageRoot: string;
     readonly launchIntent?: {
@@ -15,7 +15,7 @@ export interface BootstrapOptions {
     readonly output?: Pick<NodeJS.WriteStream, "write">;
 }
 export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
-export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string): Promise<string>;
+export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;
 export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<void>;
 export declare function releaseEnvironment(environment: NodeJS.ProcessEnv, release: MaterializedRelease): NodeJS.ProcessEnv;
 export declare function waitForVerifiedEndpoint(path: string, release: MaterializedRelease, timeoutMs: number): Promise<void>;

package/dist/src/foundation/release/bootstrap.js

@@ -8,7 +8,7 @@ import { CohortStateStore } from "./cohort-state.js";
 import { assertLaunchProfileId, resolveProductPaths } from "../lifecycle/index.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
-import { materializeRelease, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
+import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export async function runBootstrap(options) {
     const environment = { ...(options.environment ?? process.env) };
@@ -18,21 +18,44 @@ export async function runBootstrap(options) {
     const output = options.output ?? process.stderr;
     const paths = resolveProductPaths(environment);
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
-    const candidate = await materializeRelease(options.packageRoot, paths.dataDir);
     const stateStore = new CohortStateStore(paths.dataDir);
-    await stateStore.recordCandidate(candidate);
     let state = await stateStore.read();
+    let endpoint = await readEndpointMetadata(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];
+    if (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);
+        }
+        if (endpoint === null || probe === "dead") {
+            if (endpoint)
+                await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
+            const retained = await readMaterializedRelease(active.releaseRoot);
+            await startSupervisor(retained, environment);
+            await waitForVerifiedEndpoint(paths.endpointMetadataPath, retained, 8_000);
+            return await launchUi(retained, environment);
+        }
+    }
+    const candidate = await materializeRelease(options.packageRoot, paths.dataDir);
+    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();
     }
-    const endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-    const probe = endpoint ? await probeOwnership(endpoint) : "dead";
+    endpoint = await readEndpointMetadata(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.liveGenerationIds ?? []);
+        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;
     }
@@ -50,7 +73,7 @@ export async function runBootstrap(options) {
     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 generations", endpoint.ownership.nonResumableGenerationIds);
+            await stateStore.blockPending("candidate activation deferred by live non-resumable instances", endpoint.ownership.nonResumableInstanceIds);
         }
         const code = await launchUi(retained, environment);
         if (decision.recordPending)
@@ -62,12 +85,12 @@ export async function runBootstrap(options) {
         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.liveGenerationIds);
+            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.liveGenerationIds);
+            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;
         }
@@ -93,8 +116,17 @@ export async function runBootstrap(options) {
     await waitForVerifiedEndpoint(paths.endpointMetadataPath, selected, 8_000);
     return await launchUi(selected, environment);
 }
-export async function certifyMaterializedRelease(release, dataDir) {
-    await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"));
+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);
+    }
     const path = resolve(dataDir, `certification-${release.releaseId}.json`);
     await writeFile(path, JSON.stringify({
         schema: PRODUCT_IDENTITY.evidence.releaseCertificationSchema,
@@ -106,7 +138,7 @@ export async function certifyMaterializedRelease(release, dataDir) {
     return path;
 }
 export async function startSupervisor(release, environment) {
-    const entry = await resolveReleaseEntryPoint(release, "bin/a1-supervisor.js");
+    const entry = await resolveReleaseEntryPoint(release, "bin/supervisor.js");
     const child = spawn(process.execPath, [entry], {
         detached: true,
         env: releaseEnvironment(environment, release),
@@ -120,7 +152,7 @@ export async function startSupervisor(release, environment) {
     child.unref();
 }
 async function launchUi(release, environment) {
-    const entry = await resolveReleaseEntryPoint(release, "bin/a1-ui.js");
+    const entry = await resolveReleaseEntryPoint(release, "bin/guardian.js");
     return await new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(process.execPath, [entry], {
             env: releaseEnvironment(environment, release),
@@ -152,13 +184,29 @@ export async function waitForVerifiedEndpoint(path, release, timeoutMs) {
 export async function readEndpointMetadata(path) {
     try {
         const value = JSON.parse(await readFile(path, "utf8"));
+        const ownership = value.ownership;
+        const liveInstanceIds = Array.isArray(ownership?.liveInstanceIds)
+            ? ownership.liveInstanceIds
+            : Array.isArray(ownership?.liveGenerationIds) ? ownership.liveGenerationIds : null;
+        const nonResumableInstanceIds = Array.isArray(ownership?.nonResumableInstanceIds)
+            ? ownership.nonResumableInstanceIds
+            : Array.isArray(ownership?.nonResumableGenerationIds) ? ownership.nonResumableGenerationIds : null;
+        const uncertainInstanceIds = Array.isArray(ownership?.uncertainInstanceIds) ? ownership.uncertainInstanceIds : [];
         if (!value || value.schema !== PRODUCT_IDENTITY.protocol.supervisorSchema || typeof value.supervisorId !== "string" || typeof value.endpoint !== "string" || !Number.isSafeInteger(value.pid)
             || typeof value.pidStartIdentity !== "string" || typeof value.bootNonce !== "string" || typeof value.releaseId !== "string"
-            || typeof value.releaseRoot !== "string" || typeof value.contentDigest !== "string" || !value.ownership
-            || !Array.isArray(value.ownership.liveGenerationIds) || !Array.isArray(value.ownership.nonResumableGenerationIds)) {
+            || typeof value.releaseRoot !== "string" || typeof value.contentDigest !== "string" || !ownership
+            || !isStringArray(liveInstanceIds) || !isStringArray(nonResumableInstanceIds) || !isStringArray(uncertainInstanceIds)) {
             return null;
         }
-        return value;
+        return {
+            ...value,
+            ownership: {
+                ...ownership,
+                liveInstanceIds,
+                nonResumableInstanceIds,
+                uncertainInstanceIds,
+            },
+        };
     }
     catch {
         return null;
@@ -211,11 +259,11 @@ async function activatePendingAfterBlockerExit(candidate, stateStore, paths, env
     let endpoint = null;
     while (Date.now() < deadline) {
         endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-        if (!endpoint || endpoint.ownership.liveGenerationIds.length === 0)
+        if (!endpoint || endpoint.ownership.liveInstanceIds.length === 0)
             break;
         await new Promise(resolvePromise => setTimeout(resolvePromise, 40));
     }
-    if (!endpoint || endpoint.ownership.liveGenerationIds.length > 0 || await probeOwnership(endpoint) !== "live-verified")
+    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);
@@ -268,6 +316,9 @@ async function requestIdleOwnershipRelease(metadata, candidateReleaseId, timeout
         setTimeout(() => finish(false), timeoutMs).unref();
     });
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === "string" && item.length > 0);
+}
 export async function waitForProcessExit(pid, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {

package/dist/src/foundation/release/cohort-selection.js

@@ -10,7 +10,7 @@ export function selectCohortLaunch(candidate, state, endpoint, probe) {
                 pid: endpoint.pid,
             };
         }
-        if (endpoint.releaseId !== candidate.releaseId && endpoint.ownership.liveGenerationIds.length === 0) {
+        if (endpoint.releaseId !== candidate.releaseId && endpoint.ownership.liveInstanceIds.length === 0) {
             return {
                 action: "replace-idle-cohort",
                 releaseId: candidate.releaseId,
@@ -30,12 +30,12 @@ export function selectCohortLaunch(candidate, state, endpoint, probe) {
         };
     }
     if (endpoint && probe === "unresponsive") {
-        if (endpoint.ownership.liveGenerationIds.length > 0 || endpoint.ownership.nonResumableGenerationIds.length > 0) {
+        if (endpoint.ownership.liveInstanceIds.length > 0 || endpoint.ownership.nonResumableInstanceIds.length > 0) {
             return {
                 action: "blocked",
                 releaseId: endpoint.releaseId,
                 releaseRoot: endpoint.releaseRoot,
-                reason: "ownership of live generations is uncertain; preserving the unresponsive supervisor",
+                reason: "ownership of live launch instances is uncertain; preserving the unresponsive supervisor",
                 pid: endpoint.pid,
             };
         }

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

@@ -32,8 +32,9 @@ export interface CohortState {
 }
 export interface EndpointOwnership {
     readonly state: "idle" | "busy" | "draining" | "released" | "blocked";
-    readonly liveGenerationIds: readonly string[];
-    readonly nonResumableGenerationIds: readonly string[];
+    readonly liveInstanceIds: readonly string[];
+    readonly nonResumableInstanceIds: readonly string[];
+    readonly uncertainInstanceIds: readonly string[];
 }
 export interface SupervisorEndpointMetadata {
     readonly schema: string;

package/dist/src/foundation/release/concurrency.d.ts

@@ -0,0 +1 @@
+export declare function mapWithConcurrency<Value, Result>(values: readonly Value[], concurrency: number, operation: (value: Value, index: number) => Promise<Result>): Promise<Result[]>;

package/dist/src/foundation/release/concurrency.js

@@ -0,0 +1,17 @@
+export async function mapWithConcurrency(values, concurrency, operation) {
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1)
+        throw new RangeError("concurrency must be a positive safe integer");
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        while (true) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= values.length)
+                return;
+            results[index] = await operation(values[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, worker));
+    return results;
+}

package/dist/src/foundation/release/process-cleanup.d.ts

@@ -9,6 +9,6 @@ export declare function processIsAlive(pid: number): boolean;
 export declare function cleanupProvenIdleOwner(metadata: SupervisorEndpointMetadata, graceMs?: number): Promise<CleanupDiagnostics>;
 export declare function cleanupVerifiedOwner(metadata: SupervisorEndpointMetadata, options?: {
     readonly graceMs?: number;
-    readonly allowLiveGenerations?: boolean;
+    readonly allowLiveInstances?: boolean;
     readonly reason?: "stale-idle-owner" | "explicit-update" | "legacy-mutable-install";
 }): Promise<CleanupDiagnostics>;

package/dist/src/foundation/release/process-cleanup.js

@@ -11,11 +11,11 @@ export function processIsAlive(pid) {
     }
 }
 export async function cleanupProvenIdleOwner(metadata, graceMs = 1_500) {
-    return await cleanupVerifiedOwner(metadata, { graceMs, allowLiveGenerations: false });
+    return await cleanupVerifiedOwner(metadata, { graceMs, allowLiveInstances: false });
 }
 export async function cleanupVerifiedOwner(metadata, options = {}) {
     const graceMs = options.graceMs ?? 1_500;
-    if (!options.allowLiveGenerations && (metadata.ownership.liveGenerationIds.length > 0 || metadata.ownership.nonResumableGenerationIds.length > 0)) {
+    if (!options.allowLiveInstances && (metadata.ownership.liveInstanceIds.length > 0 || metadata.ownership.nonResumableInstanceIds.length > 0)) {
         throw new Error("refusing to terminate an owner with recorded live generations");
     }
     const started = Date.now();