@timurproko/a1 0.2.7-dev.1249 → 0.2.7-dev.1255

package/dist/foundation/lifecycle/launch-instance.d.ts

@@ -1,46 +0,0 @@
-import type { LaunchProfileId, NativeProcessIdentity } from "./model.js";
-export type LaunchInstanceId = string;
-export type LaunchInstanceState = "requested" | "active" | "stopping" | "completed" | "interrupted";
-export type LaunchInstanceShutdownPolicy = "terminate-tree-on-close";
-export type LaunchInstanceStopReason = "owner-disconnect" | "supervisor-disconnect" | "user-request" | "update";
-export interface ProcessContainmentIdentity {
-    readonly provider: string;
-    readonly token: string;
-}
-export type LaunchInstanceOutcome = {
-    readonly kind: "exited";
-    readonly exitCode: number;
-} | {
-    readonly kind: "signaled";
-    readonly signal: string;
-} | {
-    readonly kind: "stopped";
-    readonly reason: LaunchInstanceStopReason;
-} | {
-    readonly kind: "spawn-error" | "guardian-error" | "cleanup-error";
-    readonly message: string;
-    readonly code: string | null;
-} | {
-    readonly kind: "interrupted";
-    readonly reason: "owner-disconnect" | "supervisor-disconnect" | "guardian-exit" | "legacy-migration";
-    readonly message: string;
-};
-export interface LaunchInstance {
-    readonly id: LaunchInstanceId;
-    readonly ownerClientId: string;
-    readonly profileId: LaunchProfileId;
-    readonly state: LaunchInstanceState;
-    readonly shutdownPolicy: LaunchInstanceShutdownPolicy;
-    readonly guardianIdentity: NativeProcessIdentity;
-    readonly rootIdentity: NativeProcessIdentity | null;
-    readonly containmentIdentity: ProcessContainmentIdentity | null;
-    readonly createdAt: string;
-    readonly activatedAt: string | null;
-    readonly stoppingAt: string | null;
-    readonly completedAt: string | null;
-    readonly outcome: LaunchInstanceOutcome | null;
-}
-export declare function assertLaunchInstance(instance: LaunchInstance): void;
-export declare function assertLaunchInstanceTransition(previous: LaunchInstance, next: LaunchInstance): void;
-export declare function assertProcessContainmentIdentity(identity: ProcessContainmentIdentity): void;
-export declare function assertLaunchInstanceOutcome(outcome: LaunchInstanceOutcome): void;

package/dist/foundation/lifecycle/launch-instance.js

@@ -1,134 +0,0 @@
-import { assertLaunchProfileId, assertNativeProcessIdentity } from "./model.js";
-const ALLOWED_TRANSITIONS = {
-    requested: ["active", "completed", "interrupted"],
-    active: ["stopping", "completed", "interrupted"],
-    stopping: ["completed", "interrupted"],
-    completed: [],
-    interrupted: [],
-};
-export function assertLaunchInstance(instance) {
-    assertIdentifier(instance.id, "launch instance identity");
-    assertIdentifier(instance.ownerClientId, "launch instance owner identity");
-    assertLaunchProfileId(instance.profileId);
-    if (!(instance.state in ALLOWED_TRANSITIONS))
-        throw new TypeError(`invalid launch instance state: ${String(instance.state)}`);
-    if (instance.shutdownPolicy !== "terminate-tree-on-close")
-        throw new TypeError("launch instance shutdown policy must terminate its process tree on close");
-    assertNativeProcessIdentity(instance.guardianIdentity);
-    if (instance.rootIdentity !== null)
-        assertNativeProcessIdentity(instance.rootIdentity);
-    if (instance.containmentIdentity !== null)
-        assertProcessContainmentIdentity(instance.containmentIdentity);
-    assertTimestamp(instance.createdAt, "launch instance creation time");
-    assertOptionalTimestamp(instance.activatedAt, "launch instance activation time");
-    assertOptionalTimestamp(instance.stoppingAt, "launch instance stopping time");
-    assertOptionalTimestamp(instance.completedAt, "launch instance completion time");
-    if (instance.outcome !== null)
-        assertLaunchInstanceOutcome(instance.outcome);
-    if (instance.state === "requested") {
-        if (instance.rootIdentity !== null || instance.containmentIdentity !== null || instance.activatedAt !== null) {
-            throw new TypeError("requested launch instance cannot have active runtime ownership");
-        }
-        if (instance.stoppingAt !== null || instance.completedAt !== null || instance.outcome !== null) {
-            throw new TypeError("requested launch instance cannot have stopping or terminal state");
-        }
-        return;
-    }
-    if (instance.state === "active" || instance.state === "stopping") {
-        if (instance.rootIdentity === null || instance.containmentIdentity === null || instance.activatedAt === null) {
-            throw new TypeError(`${instance.state} launch instance requires root and containment ownership`);
-        }
-        if (instance.completedAt !== null || instance.outcome !== null)
-            throw new TypeError(`${instance.state} launch instance cannot have a terminal outcome`);
-        if (instance.state === "active" && instance.stoppingAt !== null)
-            throw new TypeError("active launch instance cannot have a stopping time");
-        if (instance.state === "stopping" && instance.stoppingAt === null)
-            throw new TypeError("stopping launch instance requires a stopping time");
-        return;
-    }
-    if (instance.completedAt === null || instance.outcome === null)
-        throw new TypeError("terminal launch instance requires completion time and outcome");
-    if (instance.state === "completed" && instance.outcome.kind === "interrupted")
-        throw new TypeError("completed launch instance cannot carry an interrupted outcome");
-    if (instance.state === "interrupted" && instance.outcome.kind !== "interrupted" && instance.outcome.kind !== "cleanup-error") {
-        throw new TypeError("interrupted launch instance requires an interrupted or cleanup-error outcome");
-    }
-}
-export function assertLaunchInstanceTransition(previous, next) {
-    assertLaunchInstance(previous);
-    assertLaunchInstance(next);
-    if (previous.id !== next.id || previous.ownerClientId !== next.ownerClientId || previous.profileId !== next.profileId) {
-        throw new TypeError("launch instance identity and ownership are immutable");
-    }
-    if (previous.shutdownPolicy !== next.shutdownPolicy
-        || !sameProcessIdentity(previous.guardianIdentity, next.guardianIdentity)
-        || previous.createdAt !== next.createdAt) {
-        throw new TypeError("launch instance guardian, policy, and creation identity are immutable");
-    }
-    const allowedTransitions = ALLOWED_TRANSITIONS[previous.state];
-    if (!allowedTransitions.includes(next.state)) {
-        throw new TypeError(`invalid launch instance transition: ${previous.state} -> ${next.state}`);
-    }
-    if (previous.rootIdentity !== null && !sameProcessIdentity(previous.rootIdentity, next.rootIdentity)) {
-        throw new TypeError("launch instance root identity is immutable after activation");
-    }
-    if (previous.containmentIdentity !== null && !sameContainmentIdentity(previous.containmentIdentity, next.containmentIdentity)) {
-        throw new TypeError("launch instance containment identity is immutable after activation");
-    }
-}
-export function assertProcessContainmentIdentity(identity) {
-    assertIdentifier(identity.provider, "process containment provider");
-    assertIdentifier(identity.token, "process containment token");
-}
-export function assertLaunchInstanceOutcome(outcome) {
-    if (outcome.kind === "exited") {
-        if (!Number.isSafeInteger(outcome.exitCode))
-            throw new TypeError("launch instance exit code must be a safe integer");
-        return;
-    }
-    if (outcome.kind === "signaled") {
-        assertIdentifier(outcome.signal, "launch instance signal");
-        return;
-    }
-    if (outcome.kind === "stopped") {
-        if (!["owner-disconnect", "supervisor-disconnect", "user-request", "update"].includes(outcome.reason)) {
-            throw new TypeError("invalid launch instance stop reason");
-        }
-        return;
-    }
-    if (outcome.kind === "interrupted") {
-        if (!["owner-disconnect", "supervisor-disconnect", "guardian-exit", "legacy-migration"].includes(outcome.reason)) {
-            throw new TypeError("invalid launch instance interruption reason");
-        }
-        assertDiagnostic(outcome.message, "launch instance interruption message");
-        return;
-    }
-    if (outcome.kind !== "spawn-error" && outcome.kind !== "guardian-error" && outcome.kind !== "cleanup-error") {
-        throw new TypeError(`invalid launch instance outcome: ${String(outcome.kind)}`);
-    }
-    assertDiagnostic(outcome.message, "launch instance failure message");
-    if (outcome.code !== null)
-        assertIdentifier(outcome.code, "launch instance failure code");
-}
-function sameProcessIdentity(left, right) {
-    return right !== null && left.pid === right.pid && left.startIdentity === right.startIdentity;
-}
-function sameContainmentIdentity(left, right) {
-    return right !== null && left.provider === right.provider && left.token === right.token;
-}
-function assertIdentifier(value, name) {
-    if (!value || value.length > 512 || value.includes("\0"))
-        throw new TypeError(`${name} must be non-empty, bounded, and contain no null byte`);
-}
-function assertDiagnostic(value, name) {
-    if (!value || value.length > 4_096 || value.includes("\0"))
-        throw new TypeError(`${name} must be non-empty, bounded, and contain no null byte`);
-}
-function assertTimestamp(value, name) {
-    if (!value || !Number.isFinite(Date.parse(value)))
-        throw new TypeError(`${name} must be a valid timestamp`);
-}
-function assertOptionalTimestamp(value, name) {
-    if (value !== null)
-        assertTimestamp(value, name);
-}

package/dist/foundation/lifecycle/native-claim-gate.d.ts

@@ -1,5 +0,0 @@
-export interface ClaimGateHandle {
-    release(): void;
-}
-/** No PID-file fallback: only the platform descriptor can prove upgraded-writer exclusion. */
-export declare function tryAcquireClaimGate(path: string): ClaimGateHandle | null;

package/dist/foundation/lifecycle/native-claim-gate.js

@@ -1,41 +0,0 @@
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-let backend;
-/** No PID-file fallback: only the platform descriptor can prove upgraded-writer exclusion. */
-export function tryAcquireClaimGate(path) {
-    if (backend === undefined) {
-        const require = createRequire(import.meta.url);
-        // Security: resolve only this release's addon, never a binary supplied by tool cwd.
-        const own = resolve(fileURLToPath(new URL("../../../", import.meta.url)), "dist", "native", `${process.platform}-${process.arch}`, `${PRODUCT_IDENTITY.artifacts.terminalHostAddon}.node`);
-        const override = process.env[PRODUCT_IDENTITY.environment.developmentInstanceId]
-            ? process.env[PRODUCT_IDENTITY.environment.terminalHostPath] : undefined;
-        for (const candidate of override ? [override, own] : [own]) {
-            if (!existsSync(candidate))
-                continue;
-            try {
-                const loaded = require(candidate);
-                if (typeof loaded.SessionLock?.tryAcquireGate === "function") {
-                    backend = loaded.SessionLock;
-                    break;
-                }
-            }
-            catch { /* Compatibility: an unusable addon is unavailable, not contended. */ }
-        }
-    }
-    if (backend === undefined)
-        throw Object.assign(new Error("native worktree coordination is unavailable; repair or update this A1 installation and retry"), {
-            code: "worktree-coordination-unavailable",
-        });
-    try {
-        const handle = backend.tryAcquireGate(path);
-        return handle.acquired ? handle : null;
-    }
-    catch (cause) {
-        throw Object.assign(new Error("cannot access the worktree mutation gate; check A1 data-directory permissions and filesystem availability", { cause }), {
-            code: "worktree-coordination-io",
-        });
-    }
-}

package/dist/foundation/lifecycle/supervisor-startup.d.ts

@@ -1,30 +0,0 @@
-declare const STARTUP_SCHEMA = "a1-supervisor-startup-v1";
-export interface SupervisorStartupAttemptIdentity {
-    readonly attemptId: string;
-    readonly releaseId: string;
-    readonly resultPath: string;
-}
-export type SupervisorStartupResult = {
-    readonly schema: typeof STARTUP_SCHEMA;
-    readonly attemptId: string;
-    readonly releaseId: string;
-    readonly outcome: "ready";
-    readonly pid: number;
-} | {
-    readonly schema: typeof STARTUP_SCHEMA;
-    readonly attemptId: string;
-    readonly releaseId: string;
-    readonly outcome: "failure";
-    readonly stage: string;
-    readonly code: string | null;
-    readonly message: string;
-};
-/** Create one unguessable startup result authority under the protected runtime root. */
-export declare function createSupervisorStartupAttempt(runtimeDir: string, releaseId: string): Promise<SupervisorStartupAttemptIdentity>;
-export declare function supervisorStartupResultPath(runtimeDir: string, attemptId: string): string;
-/** Atomically publish the bounded result for one detached supervisor startup attempt. */
-export declare function publishSupervisorStartupResult(path: string, result: SupervisorStartupResult): Promise<void>;
-export declare function readSupervisorStartupResult(path: string, attemptId: string, releaseId: string): Promise<SupervisorStartupResult | null>;
-export declare function supervisorStartupFailure(error: unknown, attemptId: string, releaseId: string, stage: string): SupervisorStartupResult;
-export declare function supervisorStartupReady(attemptId: string, releaseId: string): SupervisorStartupResult;
-export {};

package/dist/foundation/lifecycle/supervisor-startup.js

@@ -1,106 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-const STARTUP_SCHEMA = "a1-supervisor-startup-v1";
-const MAX_RESULT_BYTES = 8 * 1024;
-const MAX_MESSAGE_LENGTH = 1_024;
-const MAX_RETAINED_RESULTS = 16;
-const MAX_RESULT_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
-const ATTEMPT_PATTERN = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
-/** Create one unguessable startup result authority under the protected runtime root. */
-export async function createSupervisorStartupAttempt(runtimeDir, releaseId) {
-    const attemptId = randomUUID();
-    const directory = resolve(runtimeDir, "supervisor-startup");
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    await pruneSupervisorStartupResults(directory);
-    return { attemptId, releaseId, resultPath: supervisorStartupResultPath(runtimeDir, attemptId) };
-}
-export function supervisorStartupResultPath(runtimeDir, attemptId) {
-    if (!ATTEMPT_PATTERN.test(attemptId))
-        throw new TypeError("supervisor startup attempt identity is invalid");
-    return resolve(runtimeDir, "supervisor-startup", `${attemptId}.json`);
-}
-/** Atomically publish the bounded result for one detached supervisor startup attempt. */
-export async function publishSupervisorStartupResult(path, result) {
-    validateSupervisorStartupResult(result, result.attemptId, result.releaseId);
-    const body = `${JSON.stringify(result)}\n`;
-    if (Buffer.byteLength(body) > MAX_RESULT_BYTES)
-        throw new Error("supervisor startup result exceeds its size bound");
-    const temporary = `${path}.${process.pid}.tmp`;
-    await writeFile(temporary, body, { encoding: "utf8", mode: 0o600 });
-    await rename(temporary, path);
-}
-export async function readSupervisorStartupResult(path, attemptId, releaseId) {
-    let metadata;
-    try {
-        metadata = await stat(path);
-    }
-    catch (error) {
-        if (isNodeError(error, "ENOENT"))
-            return null;
-        throw error;
-    }
-    if (!metadata.isFile() || metadata.size > MAX_RESULT_BYTES)
-        throw new Error("supervisor startup result is invalid or oversized");
-    const value = JSON.parse(await readFile(path, "utf8"));
-    return validateSupervisorStartupResult(value, attemptId, releaseId);
-}
-export function supervisorStartupFailure(error, attemptId, releaseId, stage) {
-    const source = error instanceof Error ? error : new Error(String(error));
-    return {
-        schema: STARTUP_SCHEMA,
-        attemptId,
-        releaseId,
-        outcome: "failure",
-        stage: boundedToken(stage, "unknown"),
-        code: "code" in source && typeof source.code === "string" ? boundedToken(source.code, "UNKNOWN") : null,
-        message: sanitizeMessage(source.message),
-    };
-}
-export function supervisorStartupReady(attemptId, releaseId) {
-    return { schema: STARTUP_SCHEMA, attemptId, releaseId, outcome: "ready", pid: process.pid };
-}
-async function pruneSupervisorStartupResults(directory) {
-    const now = Date.now();
-    const entries = await readdir(directory, { withFileTypes: true });
-    const files = (await Promise.all(entries.filter(entry => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => {
-        const path = resolve(directory, entry.name);
-        const metadata = await stat(path).catch(() => null);
-        return metadata ? { path, modified: metadata.mtimeMs } : null;
-    }))).filter((file) => file !== null);
-    files.sort((left, right) => right.modified - left.modified);
-    await Promise.all(files.flatMap((file, index) => index >= MAX_RETAINED_RESULTS - 1 || now - file.modified > MAX_RESULT_AGE_MS
-        ? [rm(file.path, { force: true })]
-        : []));
-}
-function validateSupervisorStartupResult(value, attemptId, releaseId) {
-    if (!value || typeof value !== "object")
-        throw new Error("supervisor startup result is malformed");
-    const result = value;
-    if (result.schema !== STARTUP_SCHEMA || result.attemptId !== attemptId || result.releaseId !== releaseId) {
-        throw new Error("supervisor startup result does not match the selected attempt and release");
-    }
-    if (result.outcome === "ready" && Number.isSafeInteger(result.pid) && Number(result.pid) > 0)
-        return result;
-    if (result.outcome === "failure" && typeof result.stage === "string" && result.stage.length > 0 && result.stage.length <= 128
-        && (result.code === null || typeof result.code === "string") && typeof result.message === "string" && result.message.length <= MAX_MESSAGE_LENGTH) {
-        return result;
-    }
-    throw new Error("supervisor startup result is malformed");
-}
-function sanitizeMessage(message) {
-    let value = message.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/:\/\/[^\s/@:]+:[^\s/@]+@/g, "://<redacted>@");
-    for (const [name, secret] of Object.entries(process.env)) {
-        if (!secret || secret.length < 4 || !/(?:TOKEN|SECRET|PASSWORD|COOKIE|CREDENTIAL|AUTH)/i.test(name))
-            continue;
-        value = value.split(secret).join("<redacted>");
-    }
-    return value.trim().slice(0, MAX_MESSAGE_LENGTH) || "supervisor startup failed";
-}
-function boundedToken(value, fallback) {
-    const normalized = value.replace(/[^A-Za-z0-9_.:-]/g, "-").slice(0, 128);
-    return normalized || fallback;
-}
-function isNodeError(error, code) {
-    return error instanceof Error && "code" in error && error.code === code;
-}

package/dist/foundation/process-containment/addon-containment.d.ts

@@ -1,20 +0,0 @@
-import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
-import { type ProcessGuardianAddon } from "./addon.js";
-import type { ContainedProcessHandle, ContainedSpawnOptions, ProcessContainment } from "./contracts.js";
-/** Owns one native containment object in the launch guardian's Node process. */
-export declare class AddonContainment implements ProcessContainment {
-    #private;
-    readonly instanceId: string;
-    readonly addonPath: string;
-    readonly exitNoticePath: string | null;
-    readonly addon: ProcessGuardianAddon;
-    private readonly platform;
-    constructor(instanceId: string, addonPath: string, exitNoticePath?: string | null, addon?: ProcessGuardianAddon, platform?: NodeJS.Platform);
-    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/addon-containment.js

@@ -1,139 +0,0 @@
-import { constants } from "node:os";
-import { mkdir, rm } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { loadProcessGuardianAddon } from "./addon.js";
-/** Owns one native containment object in the launch guardian's Node process. */
-export class AddonContainment {
-    #identity;
-    #rootIdentity = null;
-    #runtime = null;
-    #outcome = null;
-    #settled = false;
-    instanceId;
-    addonPath;
-    exitNoticePath;
-    addon;
-    platform;
-    constructor(instanceId, addonPath, exitNoticePath = null, addon = loadProcessGuardianAddon(addonPath), platform = process.platform) {
-        this.instanceId = instanceId;
-        this.addonPath = addonPath;
-        this.exitNoticePath = exitNoticePath;
-        this.addon = addon;
-        this.platform = platform;
-        this.#identity = { provider: "native-addon-pending", token: instanceId };
-    }
-    get identity() {
-        return this.#identity;
-    }
-    async spawn(executable, arguments_, options) {
-        if (this.#runtime)
-            throw new Error("process containment already has a root runtime");
-        if (this.exitNoticePath) {
-            await mkdir(dirname(this.exitNoticePath), { recursive: true, mode: 0o700 });
-            await rm(this.exitNoticePath, { force: true });
-        }
-        const runtime = this.addon.spawnContained({
-            executable,
-            arguments: [...arguments_],
-            cwd: options.cwd,
-            environment: {
-                ...options.environment,
-                ...(options.terminalType ? { TERM: options.terminalType } : {}),
-                ...(this.exitNoticePath ? { [PRODUCT_IDENTITY.environment.exitNoticePath]: this.exitNoticePath } : {}),
-            },
-            instanceId: this.instanceId,
-        });
-        assertRuntime(runtime);
-        this.#runtime = runtime;
-        this.#rootIdentity = { pid: runtime.pid, startIdentity: runtime.startIdentity };
-        this.#identity = { provider: runtime.containmentProvider, token: runtime.containmentToken };
-        const outcome = runtime.wait().then(exitCode => outcomeFromExitCode(exitCode, this.platform), error => ({
-            kind: "guardian-error",
-            message: errorMessage(error),
-            code: errorCode(error),
-        })).finally(() => { this.#settled = true; });
-        this.#outcome = outcome;
-        return {
-            identity: this.#rootIdentity,
-            outcome,
-            ...(runtime.processGroup === null ? {} : { processGroup: runtime.processGroup }),
-            ...(runtime.foregroundGroup === null ? {} : { foregroundGroup: runtime.foregroundGroup }),
-        };
-    }
-    async contains(identity) {
-        return this.#rootIdentity !== null
-            && identity.pid === this.#rootIdentity.pid
-            && identity.startIdentity === this.#rootIdentity.startIdentity;
-    }
-    async stop(force) {
-        const runtime = this.#runtime;
-        if (!runtime || this.#settled)
-            return;
-        try {
-            if (force)
-                runtime.terminate(137);
-            else if (this.platform === "win32")
-                process.kill(runtime.pid, "SIGTERM");
-            else
-                runtime.stop();
-        }
-        catch (error) {
-            if (errorCode(error) !== "ESRCH")
-                throw error;
-        }
-    }
-    async waitForEmpty(timeoutMs) {
-        if (this.#settled || !this.#outcome)
-            return true;
-        return await Promise.race([
-            this.#outcome.then(() => true),
-            new Promise(resolvePromise => {
-                const timer = setTimeout(() => resolvePromise(false), timeoutMs);
-                timer.unref();
-            }),
-        ]);
-    }
-    async close() {
-        const runtime = this.#runtime;
-        if (!runtime)
-            return;
-        runtime.close();
-        await this.waitForEmpty(1_500);
-    }
-}
-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);
-    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, `${PRODUCT_IDENTITY.artifacts.processGuardianAddon}.node`);
-}
-function assertRuntime(runtime) {
-    if (!Number.isSafeInteger(runtime.pid) || runtime.pid <= 0
-        || typeof runtime.startIdentity !== "string" || runtime.startIdentity.length === 0
-        || typeof runtime.containmentProvider !== "string" || runtime.containmentProvider.length === 0
-        || typeof runtime.containmentToken !== "string" || runtime.containmentToken.length === 0
-        || (runtime.processGroup !== null && (!Number.isSafeInteger(runtime.processGroup) || runtime.processGroup <= 0))
-        || (runtime.foregroundGroup !== null && (!Number.isSafeInteger(runtime.foregroundGroup) || runtime.foregroundGroup <= 0))) {
-        runtime.close();
-        throw Object.assign(new Error("process guardian addon returned invalid containment identity"), { code: "CONTAINMENT_ARTIFACT_INCOMPATIBLE" });
-    }
-}
-function outcomeFromExitCode(exitCode, platform) {
-    if (!Number.isSafeInteger(exitCode) || exitCode < 0 || exitCode > 255) {
-        return { kind: "guardian-error", message: "process guardian addon returned an invalid exit code", code: "CONTAINMENT_OUTCOME_INVALID" };
-    }
-    if (platform !== "win32" && exitCode >= 128) {
-        const signalNumber = exitCode - 128;
-        const signal = Object.entries(constants.signals).find(([, value]) => value === signalNumber)?.[0];
-        if (signal)
-            return { kind: "signaled", signal };
-    }
-    return { kind: "exited", exitCode };
-}
-function errorCode(error) {
-    return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null;
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/foundation/process-containment/addon-process-inspector.d.ts

@@ -1,11 +0,0 @@
-import type { NativeProcessIdentity } from "../lifecycle/index.js";
-import type { ProcessGuardianAddon } from "./addon.js";
-import type { NativeProcessInspector } from "./contracts.js";
-/** Verifies native process identity through the process-guardian addon's bounded inspection call. */
-export declare class AddonProcessInspector implements NativeProcessInspector {
-    readonly addon: Pick<ProcessGuardianAddon, "inspectProcessStart">;
-    readonly identityPrefix: string;
-    constructor(addon: Pick<ProcessGuardianAddon, "inspectProcessStart">, identityPrefix: string);
-    observe(pid: number): Promise<NativeProcessIdentity | null>;
-    matches(identity: NativeProcessIdentity): Promise<boolean>;
-}

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

@@ -1,36 +0,0 @@
-/** Verifies native process identity through the process-guardian addon's bounded inspection call. */
-export class AddonProcessInspector {
-    addon;
-    identityPrefix;
-    constructor(addon, identityPrefix) {
-        if (!identityPrefix || identityPrefix.includes("\0"))
-            throw new TypeError("process identity prefix is invalid");
-        this.addon = addon;
-        this.identityPrefix = identityPrefix;
-    }
-    async observe(pid) {
-        if (!Number.isSafeInteger(pid) || pid <= 0)
-            throw new TypeError("inspected PID must be a positive safe integer");
-        let startIdentity;
-        try {
-            startIdentity = this.addon.inspectProcessStart(pid);
-        }
-        catch (error) {
-            throw Object.assign(new Error(`cannot inspect native process identity: ${errorMessage(error)}`), { code: "PROCESS_INSPECTION_FAILED" });
-        }
-        if (startIdentity === null)
-            return null;
-        if (typeof startIdentity !== "string" || startIdentity.length === 0 || startIdentity.length > 512
-            || startIdentity.includes("\0") || !startIdentity.startsWith(this.identityPrefix)) {
-            throw Object.assign(new Error("process guardian returned mismatched identity data"), { code: "PROCESS_INSPECTION_INVALID" });
-        }
-        return { pid, startIdentity };
-    }
-    async matches(identity) {
-        const observed = await this.observe(identity.pid);
-        return observed !== null && observed.startIdentity === identity.startIdentity;
-    }
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/foundation/process-containment/addon.d.ts

@@ -1,47 +0,0 @@
-export interface ProcessGuardianVersion {
-    readonly crateVersion: string;
-    readonly protocolVersion: 2;
-    readonly target: string;
-}
-export interface ProcessGuardianRuntime {
-    readonly pid: number;
-    readonly startIdentity: string;
-    readonly containmentProvider: string;
-    readonly containmentToken: string;
-    readonly processGroup: number | null;
-    readonly foregroundGroup: number | null;
-    wait(): Promise<number>;
-    terminate(code: number): void;
-    stop(): void;
-    close(): void;
-}
-export interface SpawnContainedOptions {
-    readonly executable: string;
-    readonly arguments: readonly string[];
-    readonly cwd: string;
-    readonly environment: Readonly<Record<string, string>>;
-    readonly instanceId: string;
-}
-export interface ProcessGuardianAddon {
-    version(): ProcessGuardianVersion;
-    inspectProcessStart(pid: number): string | null;
-    /** Additive capability; older retained addons remain usable for containment, not recovery gates. */
-    tryAcquireProcessGate?(path: string): {
-        readonly acquired: boolean;
-        release(): void;
-    };
-    captureTerminalModes(): string;
-    restoreTerminalModes(encoded: string): void;
-    deliverExitNotice(path: string, encodedModes: string): void;
-    spawnContained(options: SpawnContainedOptions): ProcessGuardianRuntime;
-    spawnWatcher(options: {
-        readonly executable: string;
-        readonly arguments: readonly string[];
-    }): number;
-    waitForProcessExit(pid: number): Promise<void>;
-    stopProcessGroup(processGroup: number): void;
-    restoreForegroundGroup(processGroup: number): void;
-    ignoreConsoleControl(): void;
-}
-/** Loads one verified Node-API guardian instance per exact addon path. */
-export declare function loadProcessGuardianAddon(path: string): ProcessGuardianAddon;