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

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

@@ -0,0 +1,27 @@
+import { readFile } from "node:fs/promises";
+/** Verifies Linux process identity from the PID and kernel start-time field in procfs. */
+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/foundation/process-containment/native-guardian-containment.d.ts

@@ -0,0 +1,17 @@
+import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+import type { ContainedProcessHandle, ContainedSpawnOptions, ProcessContainment } from "./contracts.js";
+/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
+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/foundation/process-containment/native-guardian-containment.js

@@ -0,0 +1,140 @@
+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";
+/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
+export class NativeGuardianContainment {
+    #identity;
+    #helper = null;
+    #rootIdentity = null;
+    #outcome = null;
+    instanceId;
+    helperPath;
+    statusPath;
+    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/foundation/process-containment/windows-process-inspector.d.ts

@@ -0,0 +1,19 @@
+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>;
+}
+/** Verifies Windows process identity through the bounded process-guardian inspection command. */
+export declare class WindowsNativeProcessInspector implements NativeProcessInspector {
+    readonly helperPath: string;
+    private readonly runner;
+    private readonly identityPrefix;
+    constructor(helperPath: string, runner?: InspectorCommandRunner, identityPrefix?: string);
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

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

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+/** Verifies Windows process identity through the bounded process-guardian inspection command. */
+export class WindowsNativeProcessInspector {
+    helperPath;
+    runner;
+    identityPrefix;
+    constructor(helperPath, runner = defaultRunner, identityPrefix = "windows-filetime:") {
+        this.helperPath = helperPath;
+        this.runner = runner;
+        this.identityPrefix = identityPrefix;
+        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(this.identityPrefix)) {
+            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/foundation/protocol/client.d.ts

@@ -0,0 +1,18 @@
+import { EventEmitter } from "node:events";
+import type { CommandResult, LaunchInstanceStopIntent, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
+interface ClientEvents {
+    snapshot: [SupervisorSnapshot];
+    stopIntent: [LaunchInstanceStopIntent];
+    disconnect: [];
+}
+/** Maintains one negotiated supervisor connection and rejects all pending commands on disconnect. */
+export declare class SupervisorClient extends EventEmitter<ClientEvents> {
+    #private;
+    readonly clientId: `${string}-${string}-${string}-${string}-${string}`;
+    readonly releaseId?: string;
+    constructor(releaseId?: string);
+    connect(endpoint: string, timeoutMs?: number): Promise<SupervisorSnapshot>;
+    command(command: SupervisorCommand): Promise<CommandResult>;
+    close(): void;
+}
+export {};

package/dist/foundation/protocol/client.js

@@ -0,0 +1,130 @@
+import { EventEmitter } from "node:events";
+import { connect } from "node:net";
+import { randomUUID } from "node:crypto";
+import { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, encodeFrame, LineFrameDecoder, localControlHello, negotiateControlFeatures } from "./messages.js";
+/** Maintains one negotiated supervisor connection and rejects all pending commands on disconnect. */
+export class SupervisorClient extends EventEmitter {
+    clientId = randomUUID();
+    releaseId;
+    constructor(releaseId) {
+        super();
+        if (releaseId !== undefined)
+            this.releaseId = releaseId;
+    }
+    #socket = null;
+    #pending = new Map();
+    async connect(endpoint, timeoutMs = 5_000) {
+        if (this.#socket)
+            throw new Error("client is already connected");
+        const deadline = Date.now() + timeoutMs;
+        let lastError = null;
+        while (Date.now() < deadline) {
+            try {
+                return await this.#connectOnce(endpoint, Math.max(1, deadline - Date.now()));
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (!isTransientEndpointError(lastError))
+                    throw lastError;
+                await new Promise(resolve => setTimeout(resolve, Math.min(40, Math.max(1, deadline - Date.now()))));
+            }
+        }
+        throw new Error(`supervisor endpoint ${endpoint} remained unavailable for ${timeoutMs}ms`, { cause: lastError ?? undefined });
+    }
+    #connectOnce(endpoint, timeoutMs) {
+        const socket = connect(endpoint);
+        this.#socket = socket;
+        socket.setNoDelay(true);
+        const decoder = new LineFrameDecoder();
+        return new Promise((resolve, reject) => {
+            let welcomed = false;
+            const timeout = setTimeout(() => {
+                const error = transientError(`supervisor connection timed out after ${timeoutMs}ms`, "ETIMEDOUT");
+                fail(error);
+                socket.destroy();
+            }, timeoutMs);
+            const fail = (error) => {
+                clearTimeout(timeout);
+                if (!welcomed)
+                    reject(error);
+            };
+            socket.once("error", fail);
+            socket.on("close", () => {
+                if (this.#socket === socket)
+                    this.#socket = null;
+                if (!welcomed) {
+                    fail(transientError("supervisor disconnected before completing its handshake", "ECONNRESET"));
+                    return;
+                }
+                for (const pending of this.#pending.values())
+                    pending.reject(new Error("supervisor disconnected"));
+                this.#pending.clear();
+                this.emit("disconnect");
+            });
+            socket.on("data", chunk => {
+                try {
+                    for (const value of decoder.push(chunk)) {
+                        const message = value;
+                        if (message.type === "server-hello" && message.snapshot) {
+                            const hello = message;
+                            if (hello.envelope !== CONTROL_ENVELOPE || hello.envelopeRevision !== CONTROL_ENVELOPE_REVISION || !Array.isArray(hello.requiredFeatures) || !Array.isArray(hello.optionalFeatures) || typeof hello.contractDigest !== "string") {
+                                fail(new Error("supervisor returned an invalid control handshake"));
+                                socket.destroy();
+                                continue;
+                            }
+                            const negotiation = negotiateControlFeatures(localControlHello(this.releaseId), hello);
+                            if (!negotiation.ok) {
+                                fail(new Error(negotiation.diagnostic));
+                                socket.destroy();
+                                continue;
+                            }
+                            welcomed = true;
+                            clearTimeout(timeout);
+                            resolve(message.snapshot);
+                        }
+                        else if (message.type === "snapshot" && message.snapshot) {
+                            this.emit("snapshot", message.snapshot);
+                        }
+                        else if (message.type === "command-result" && message.result) {
+                            const pending = this.#pending.get(message.result.requestId);
+                            if (pending) {
+                                this.#pending.delete(message.result.requestId);
+                                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"));
+                        }
+                    }
+                }
+                catch (error) {
+                    fail(error instanceof Error ? error : new Error(String(error)));
+                    socket.destroy();
+                }
+            });
+            socket.once("connect", () => socket.write(encodeFrame({ type: "client-hello", clientId: this.clientId, ...localControlHello(this.releaseId) })));
+        });
+    }
+    command(command) {
+        if (!this.#socket)
+            return Promise.reject(new Error("supervisor is not connected"));
+        return new Promise((resolve, reject) => {
+            this.#pending.set(command.requestId, { resolve, reject });
+            this.#socket?.write(encodeFrame({ type: "command", command }));
+        });
+    }
+    close() {
+        this.#socket?.end();
+        this.#socket = null;
+    }
+}
+function isTransientEndpointError(error) {
+    const code = "code" in error ? String(error.code) : "";
+    return ["ENOENT", "ECONNREFUSED", "ECONNRESET", "EPIPE", "ETIMEDOUT"].includes(code);
+}
+function transientError(message, code) {
+    return Object.assign(new Error(message), { code });
+}

package/dist/foundation/protocol/index.d.ts

@@ -0,0 +1,3 @@
+export { SupervisorClient } from "./client.js";
+export { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, GENERATED_CONTRACT_DIGEST, LineFrameDecoder, MAX_CONTROL_FRAME_BYTES, OPTIONAL_CONTROL_FEATURES, REQUIRED_CONTROL_FEATURES, encodeFrame, isCommandMessage, isControlHello, localControlHello, negotiateControlFeatures, } from "./messages.js";
+export type { ClientMessage, ControlFeature, ControlHello, ControlNegotiation, ServerMessage } from "./messages.js";

package/dist/foundation/protocol/index.js

@@ -0,0 +1,2 @@
+export { SupervisorClient } from "./client.js";
+export { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, GENERATED_CONTRACT_DIGEST, LineFrameDecoder, MAX_CONTROL_FRAME_BYTES, OPTIONAL_CONTROL_FEATURES, REQUIRED_CONTROL_FEATURES, encodeFrame, isCommandMessage, isControlHello, localControlHello, negotiateControlFeatures, } from "./messages.js";

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

@@ -0,0 +1,90 @@
+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", "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;
+export declare const MAX_CONTROL_FRAME_BYTES: number;
+export interface ControlHello {
+    readonly envelope: typeof CONTROL_ENVELOPE;
+    readonly envelopeRevision: typeof CONTROL_ENVELOPE_REVISION;
+    readonly requiredFeatures: readonly ControlFeature[];
+    readonly optionalFeatures: readonly ControlFeature[];
+    readonly contractDigest: string;
+    readonly releaseId?: string;
+}
+export type ClientMessage = {
+    readonly type: "identity-probe";
+} | {
+    readonly type: "release-idle-ownership";
+    readonly bootNonce: string;
+    readonly candidateReleaseId: string;
+} | {
+    readonly type: "release-update-ownership";
+    readonly bootNonce: string;
+    readonly targetVersion: string;
+} | ({
+    readonly type: "client-hello";
+    readonly clientId: string;
+} & ControlHello) | {
+    readonly type: "command";
+    readonly command: SupervisorCommand;
+};
+export type ServerMessage = {
+    readonly type: "identity";
+    readonly supervisorId: string;
+    readonly bootNonce: string;
+    readonly pidStartIdentity: string;
+    readonly releaseId: string;
+} | {
+    readonly type: "release-ownership-result";
+    readonly released: boolean;
+    readonly reason: string;
+    readonly liveInstanceIds: readonly string[];
+} | {
+    readonly type: "release-update-result";
+    readonly accepted: boolean;
+    readonly reason: string;
+    readonly liveInstanceIds: readonly string[];
+} | ({
+    readonly type: "server-hello";
+    readonly supervisorId: string;
+    readonly bootNonce: string;
+    readonly pidStartIdentity: string;
+    readonly negotiatedFeatures: readonly string[];
+    readonly snapshot: SupervisorSnapshot;
+} & ControlHello) | {
+    readonly type: "snapshot";
+    readonly snapshot: SupervisorSnapshot;
+} | {
+    readonly type: "command-result";
+    readonly result: CommandResult;
+} | LaunchInstanceStopIntent | {
+    readonly type: "protocol-error";
+    readonly code: string;
+    readonly message: string;
+    readonly diagnostics?: unknown;
+};
+export interface ControlNegotiation {
+    readonly ok: boolean;
+    readonly negotiatedFeatures: readonly string[];
+    readonly missingFromClient: readonly string[];
+    readonly missingFromServer: readonly string[];
+    readonly diagnostic: string;
+}
+export declare function localControlHello(releaseId?: string): ControlHello;
+export declare function negotiateControlFeatures(client: ControlHello, server?: ControlHello): ControlNegotiation;
+export declare function encodeFrame(message: ClientMessage | ServerMessage | Readonly<Record<string, unknown>>): string;
+/** Incrementally decodes size-bounded newline-delimited control frames from arbitrary chunks. */
+export declare class LineFrameDecoder {
+    #private;
+    push(chunk: Buffer | string): unknown[];
+}
+export declare function isControlHello(value: unknown): value is {
+    readonly type: "client-hello";
+    readonly clientId: string;
+} & ControlHello;
+export declare function isCommandMessage(value: unknown): value is Extract<ClientMessage, {
+    type: "command";
+}>;

package/dist/foundation/protocol/messages.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export const CONTROL_ENVELOPE = PRODUCT_IDENTITY.protocol.controlEnvelope;
+export const CONTROL_ENVELOPE_REVISION = 1;
+export const REQUIRED_CONTROL_FEATURES = [
+    "handshake.features.v1",
+    "snapshot.revision.v1",
+    "commands.request-identity.v1",
+    "generation.lifecycle.v1",
+    "launch.instance-lifecycle.v1",
+];
+export const OPTIONAL_CONTROL_FEATURES = [
+    "messages.unknown-additive-ignore.v1",
+    "snapshot.resynchronize.v1",
+];
+export const GENERATED_CONTRACT_DIGEST = createHash("sha256").update(JSON.stringify({
+    envelope: CONTROL_ENVELOPE,
+    revision: CONTROL_ENVELOPE_REVISION,
+    required: [...REQUIRED_CONTROL_FEATURES].sort(),
+    optional: [...OPTIONAL_CONTROL_FEATURES].sort(),
+})).digest("hex");
+export const MAX_CONTROL_FRAME_BYTES = 4 * 1024 * 1024;
+export function localControlHello(releaseId) {
+    return {
+        envelope: CONTROL_ENVELOPE,
+        envelopeRevision: CONTROL_ENVELOPE_REVISION,
+        requiredFeatures: REQUIRED_CONTROL_FEATURES,
+        optionalFeatures: OPTIONAL_CONTROL_FEATURES,
+        contractDigest: GENERATED_CONTRACT_DIGEST,
+        ...(releaseId ? { releaseId } : {}),
+    };
+}
+export function negotiateControlFeatures(client, server = localControlHello()) {
+    if (client.envelope !== server.envelope || client.envelopeRevision !== server.envelopeRevision) {
+        return {
+            ok: false,
+            negotiatedFeatures: [],
+            missingFromClient: [],
+            missingFromServer: [],
+            diagnostic: `control envelope mismatch: client ${client.envelope}/${client.envelopeRevision}; server ${server.envelope}/${server.envelopeRevision}`,
+        };
+    }
+    const clientFeatures = new Set([...client.requiredFeatures, ...client.optionalFeatures]);
+    const serverFeatures = new Set([...server.requiredFeatures, ...server.optionalFeatures]);
+    const missingFromClient = server.requiredFeatures.filter(feature => !clientFeatures.has(feature));
+    const missingFromServer = client.requiredFeatures.filter(feature => !serverFeatures.has(feature));
+    const negotiatedFeatures = [...clientFeatures].filter(feature => serverFeatures.has(feature)).sort();
+    return {
+        ok: missingFromClient.length === 0 && missingFromServer.length === 0,
+        negotiatedFeatures,
+        missingFromClient,
+        missingFromServer,
+        diagnostic: missingFromClient.length === 0 && missingFromServer.length === 0
+            ? `control features negotiated (${negotiatedFeatures.join(", ")}); contract client=${client.contractDigest} server=${server.contractDigest}`
+            : `required control features unavailable; client missing [${missingFromClient.join(", ")}], server missing [${missingFromServer.join(", ")}]; contract client=${client.contractDigest} server=${server.contractDigest}`,
+    };
+}
+export function encodeFrame(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+/** Incrementally decodes size-bounded newline-delimited control frames from arbitrary chunks. */
+export class LineFrameDecoder {
+    #buffer = "";
+    push(chunk) {
+        this.#buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        if (Buffer.byteLength(this.#buffer, "utf8") > MAX_CONTROL_FRAME_BYTES) {
+            this.#buffer = "";
+            throw new Error("control frame exceeds maximum size");
+        }
+        const messages = [];
+        let newline = this.#buffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = this.#buffer.slice(0, newline);
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (line.length > 0)
+                messages.push(JSON.parse(line));
+            newline = this.#buffer.indexOf("\n");
+        }
+        return messages;
+    }
+}
+export function isControlHello(value) {
+    if (!isRecord(value) || value.type !== "client-hello" || typeof value.clientId !== "string")
+        return false;
+    return value.envelope === CONTROL_ENVELOPE
+        && value.envelopeRevision === CONTROL_ENVELOPE_REVISION
+        && isStringArray(value.requiredFeatures)
+        && isStringArray(value.optionalFeatures)
+        && typeof value.contractDigest === "string"
+        && (value.releaseId === undefined || typeof value.releaseId === "string");
+}
+export function isCommandMessage(value) {
+    return isRecord(value) && value.type === "command" && isRecord(value.command) && typeof value.command.type === "string";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === "string" && item.length > 0);
+}

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

@@ -0,0 +1,51 @@
+import { type SupervisorEndpointMetadata } from "./cohort-state.js";
+import { resolveProductPaths, type SessionSelection, type LaunchProfileId, type SupervisorStartupAttemptIdentity } from "../lifecycle/index.js";
+import { cleanupProvenIdleOwner } from "./process-cleanup.js";
+import { type MaterializedRelease, type VerifyMaterializedReleaseOptions } from "./release-store.js";
+export interface BootstrapOptions {
+    readonly packageRoot: string;
+    readonly launchIntent?: {
+        readonly kind: "interactive";
+        readonly profileId: LaunchProfileId;
+        readonly sessionSelection?: SessionSelection;
+    };
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly output?: Pick<NodeJS.WriteStream, "write">;
+    /**
+     * Whether a materialized release copy is fit to launch. The active release
+     * is normally reused while its version matches the installation, but a copy
+     * can be broken in ways a version cannot see — materialized from a tree a
+     * blocked postinstall never finished repairing. The probe is injected from
+     * the bin entry because deciding it requires inspecting dependency
+     * resolution, which stays out of production code. Absent means every
+     * release is fit.
+     */
+    readonly releaseIsLaunchable?: (releaseRoot: string) => boolean;
+    /** Test seam for bounded maintenance scheduled after stale endpoint sweeping. */
+    readonly scheduleMaintenance?: (dataDir: string, paths: ReturnType<typeof resolveProductPaths>) => Promise<void>;
+}
+export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
+export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;
+/** Persist current-format evidence after an authenticated parent has certified the exact release. */
+export declare function recordParentCertifiedRelease(release: MaterializedRelease, dataDir: string): Promise<string>;
+export interface SupervisorStartupAttempt extends SupervisorStartupAttemptIdentity {
+    readonly childOutcome: Promise<{
+        readonly exitCode: number | null;
+        readonly signal: NodeJS.Signals | null;
+    }>;
+}
+/** Reuse a verified owner, or join the winner if another launch starts the same cohort first. */
+export declare function ensureSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<void>;
+export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<SupervisorStartupAttempt>;
+/**
+ * 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 declare function releaseEnvironment(environment: NodeJS.ProcessEnv, release: MaterializedRelease, profile?: LaunchProfileId): NodeJS.ProcessEnv;
+export declare function waitForVerifiedEndpoint(path: string, release: MaterializedRelease, timeoutMs: number, startup?: SupervisorStartupAttempt): Promise<void>;
+export declare function releaseVerifiedIdleOwner(metadata: SupervisorEndpointMetadata, dataDir: string, operations?: {
+    readonly waitForExit?: typeof waitForProcessExit;
+    readonly cleanup?: typeof cleanupProvenIdleOwner;
+}): Promise<boolean>;
+export declare function waitForProcessExit(pid: number, timeoutMs: number): Promise<void>;