@timurproko/a1 0.1.8-dev.226 → 0.1.8-dev.259

package/dist/foundation/release/dependency-layer.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, posix, relative, resolve, sep } from "node:path";
 import { mapWithConcurrency } from "./concurrency.js";
+import { assertImmutableFileMode, immutablePlatformPolicy } from "./immutable-platform.js";
 import { digestManifestFiles, releaseFileIdentity, resolveWithin } from "./release.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 const LAYER_IO_CONCURRENCY = 32;
@@ -278,7 +279,8 @@ export async function readCertifiedDependencyLayer(dataDir, layerId, expected) {
     const manifest = JSON.parse(await readFile(resolve(layerRoot, DEPENDENCY_LAYER_MANIFEST), "utf8"));
     validateLayerManifest(manifest);
     const certification = JSON.parse(await readFile(certificationPath(dataDir, layerId), "utf8"));
-    if (certification.schema !== PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema || certification.layerId !== manifest.layerId || certification.contentDigest !== manifest.contentDigest) {
+    if (certification.schema !== PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema || certification.layerId !== manifest.layerId || certification.contentDigest !== manifest.contentDigest
+        || certification.platform !== process.platform || certification.platformPolicy !== immutablePlatformPolicy()) {
         throw new Error(`dependency layer certification differs from manifest: ${layerId}`);
     }
     if (expected && (expected.layerId !== manifest.layerId || expected.contentDigest !== manifest.contentDigest)) {
@@ -300,6 +302,7 @@ export async function verifyDependencyLayer(dataDir, reference, onOperation) {
         const metadata = await lstat(path);
         if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size !== file.bytes)
             throw new Error(`dependency layer file mismatch: ${file.path}`);
+        assertImmutableFileMode(metadata, path);
         const bytes = await readFile(path);
         onOperation?.({ operation: "verification-read", path: file.path, bytes: bytes.length });
         const actual = releaseFileIdentity(file.path, bytes, file.executable);
@@ -338,16 +341,14 @@ async function writeLayerCertification(dataDir, identity) {
         schema: PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema,
         layerId: identity.layerId,
         contentDigest: identity.contentDigest,
+        platform: process.platform,
+        platformPolicy: immutablePlatformPolicy(),
         certifiedAt: new Date().toISOString(),
-    }, null, 2), { flag: "wx", mode: 0o600 });
-    try {
-        await rename(temporary, path);
-    }
-    catch (error) {
-        if (!await lstat(path).catch(() => null))
-            throw error;
-        await rm(temporary, { force: true });
-    }
+    }, null, 2), { flag: "wx", mode: 0o400 });
+    await chmod(path, 0o600).catch(() => { });
+    await rm(path, { force: true });
+    await rename(temporary, path);
+    await chmod(path, 0o400);
 }
 function validateLayerManifest(value) {
     if (value.schema !== DEPENDENCY_LAYER_SCHEMA || !/^dependencies-[a-f0-9]{32}$/.test(value.layerId)

package/dist/foundation/release/immutable-platform.d.ts

@@ -0,0 +1,6 @@
+import type { Stats } from "node:fs";
+export type ImmutablePlatformPolicy = "windows-readonly-content-v1" | "posix-readonly-content-v1";
+/** Name the platform protection established while complete payload verification owns every file. */
+export declare function immutablePlatformPolicy(platform?: NodeJS.Platform): ImmutablePlatformPolicy | null;
+/** Refuse certification when a payload file is writable after immutable materialization. */
+export declare function assertImmutableFileMode(metadata: Pick<Stats, "mode">, path: string): void;

package/dist/foundation/release/immutable-platform.js

@@ -0,0 +1,13 @@
+/** Name the platform protection established while complete payload verification owns every file. */
+export function immutablePlatformPolicy(platform = process.platform) {
+    if (platform === "win32")
+        return "windows-readonly-content-v1";
+    if (platform === "linux" || platform === "darwin")
+        return "posix-readonly-content-v1";
+    return null;
+}
+/** Refuse certification when a payload file is writable after immutable materialization. */
+export function assertImmutableFileMode(metadata, path) {
+    if ((metadata.mode & 0o222) !== 0)
+        throw new Error(`immutable payload file is writable: ${path}`);
+}

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

@@ -7,6 +7,7 @@ export * from "./process-cleanup.js";
 export * from "./release.js";
 export * from "./release-gc.js";
 export * from "./release-store.js";
+export * from "./restart-certification.js";
 export * from "./stable-release.js";
 export * from "./update.js";
 export * from "./update-transaction.js";

package/dist/foundation/release/index.js

@@ -7,6 +7,7 @@ export * from "./process-cleanup.js";
 export * from "./release.js";
 export * from "./release-gc.js";
 export * from "./release-store.js";
+export * from "./restart-certification.js";
 export * from "./stable-release.js";
 export * from "./update.js";
 export * from "./update-transaction.js";

package/dist/foundation/release/release-store.d.ts

@@ -32,7 +32,7 @@ export interface CertifiedReleaseRecord {
 export declare function materializeRelease(packageRoot: string, dataDir: string, options?: MaterializeReleaseOptions): Promise<MaterializedRelease>;
 /** Consume proof that this exact object was freshly materialized or fully verified in this process. */
 export declare function consumeMaterializationProof(release: MaterializedRelease): boolean;
-export declare function readMaterializedRelease(releaseRoot: string): Promise<MaterializedRelease>;
+export declare function readMaterializedRelease(releaseRoot: string, selectedStoreRoot?: string): Promise<MaterializedRelease>;
 /**
  * Load metadata for a release whose bytes were already certified by the
  * current parent process or an authenticated live supervisor. Callers must

package/dist/foundation/release/release-store.js

@@ -4,6 +4,7 @@ import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { PRODUCT_PACKAGE_NAME, createReleaseIdentity, discoverReleasePayload, releaseFileIdentity, resolveWithin, } from "./release.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { mapWithConcurrency } from "./concurrency.js";
+import { assertImmutableFileMode } from "./immutable-platform.js";
 import { dependencyReference, materializeDependencyLayer, readCertifiedDependencyLayer, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 const RELEASE_FILE_IO_CONCURRENCY = 32;
 const certificationReady = new WeakSet();
@@ -94,10 +95,10 @@ export function consumeMaterializationProof(release) {
     certificationReady.delete(release);
     return true;
 }
-export async function readMaterializedRelease(releaseRoot) {
+export async function readMaterializedRelease(releaseRoot, selectedStoreRoot) {
     const canonical = await realpath(releaseRoot);
     const manifest = JSON.parse(await readFile(resolve(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
-    return await verifyMaterializedRelease(canonical, manifest);
+    return certificationReadyRelease(await verifyMaterializedRelease(canonical, manifest, selectedStoreRoot));
 }
 /**
  * Load metadata for a release whose bytes were already certified by the
@@ -187,6 +188,7 @@ async function verifyFile(root, file, options) {
         throw new Error(`release candidate is incomplete: ${file.path}`);
     if (metadata.size !== file.bytes)
         throw new Error(`release file size mismatch: ${file.path}`);
+    assertImmutableFileMode(metadata, path);
     const bytes = await readFile(path);
     options.onOperation?.({ operation: "verification-read", path: file.path, bytes: bytes.length });
     const digest = createHash("sha256").update(bytes).digest("hex");

package/dist/foundation/release/restart-certification.d.ts

@@ -0,0 +1,67 @@
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { type DependencyLayerReference } from "./dependency-layer.js";
+import { type ImmutablePlatformPolicy } from "./immutable-platform.js";
+import { type ReleaseFileIdentity } from "./release.js";
+import { type CertifiedReleaseRecord, type MaterializedRelease } from "./release-store.js";
+declare const RESTART_SEAL_VERSION = 1;
+type EvidenceKind = "directory" | "file" | "binding";
+interface PathEvidence {
+    readonly path: string;
+    readonly kind: EvidenceKind;
+    readonly device: string;
+    readonly inode: string;
+    readonly mode: number;
+    readonly size: string;
+    readonly modifiedNs: string;
+    readonly changedNs: string;
+    readonly bornNs: string;
+}
+interface LayerRestartEvidence extends DependencyLayerReference {
+    readonly layerRoot: PathEvidence;
+    readonly manifest: PathEvidence;
+    readonly certification: PathEvidence;
+    readonly bindingEvidence: PathEvidence;
+    readonly bindingTarget: string;
+}
+interface RestartSealCore {
+    readonly version: typeof RESTART_SEAL_VERSION;
+    readonly platform: NodeJS.Platform;
+    readonly platformPolicy: ImmutablePlatformPolicy;
+    readonly releaseId: string;
+    readonly packageVersion: string;
+    readonly contentDigest: string;
+    readonly packageRoot: string;
+    readonly releaseRoot: PathEvidence;
+    readonly manifest: PathEvidence;
+    readonly launchEntries: readonly ReleaseFileIdentity[];
+    readonly launchEntryEvidence: readonly PathEvidence[];
+    readonly dependencyLayers: readonly LayerRestartEvidence[];
+    readonly certifiedAt: string;
+}
+export interface RestartSeal extends RestartSealCore {
+    readonly sealDigest: string;
+}
+interface ReleaseCertificationDocument {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.releaseCertificationSchema;
+    readonly releaseId: string;
+    readonly contentDigest: string;
+    readonly verifiedAt: string;
+    readonly checks: readonly {
+        readonly id: string;
+        readonly passed: boolean;
+    }[];
+    readonly restartSeal: RestartSeal | null;
+}
+export interface RestartValidationEvent {
+    readonly operation: "restart-evidence-read";
+    readonly path: string;
+}
+/** Build compact restart authority after complete content verification established read-only payload files. */
+export declare function createRestartSeal(release: MaterializedRelease, dataDir: string): Promise<RestartSeal | null>;
+/** Recover an approved release from durable bounded evidence without traversing its payload. */
+export declare function readRestartCertifiedRelease(record: CertifiedReleaseRecord & {
+    readonly diagnosticsPath?: string | null;
+}, dataDir: string, onEvent?: (event: RestartValidationEvent) => void): Promise<MaterializedRelease>;
+export declare function releaseCertificationDocument(release: MaterializedRelease, restartSeal: RestartSeal | null, verifiedAt?: string): ReleaseCertificationDocument;
+export declare function restartSealDigest(core: RestartSealCore): string;
+export {};

package/dist/foundation/release/restart-certification.js

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { DEPENDENCY_LAYER_MANIFEST, dependencyLayerCertificationPath } from "./dependency-layer.js";
+import { immutablePlatformPolicy } from "./immutable-platform.js";
+import { PRODUCT_PACKAGE_NAME } from "./release.js";
+import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+const RESTART_SEAL_VERSION = 1;
+const REQUIRED_LAUNCH_ENTRIES = ["bin/supervisor.js", "bin/guardian.js"];
+/** Build compact restart authority after complete content verification established read-only payload files. */
+export async function createRestartSeal(release, dataDir) {
+    const policy = immutablePlatformPolicy();
+    if (policy === null)
+        return null;
+    const canonicalData = await realpath(dataDir);
+    const releasesRoot = await realpath(resolve(canonicalData, "releases"));
+    const releaseRoot = await realpath(release.releaseRoot);
+    assertDirectChild(releasesRoot, releaseRoot, release.releaseId, "release");
+    const manifestPath = resolve(releaseRoot, RELEASE_MANIFEST_FILENAME);
+    const launchEntries = REQUIRED_LAUNCH_ENTRIES.map(path => release.files.find(candidate => candidate.path === path));
+    if (launchEntries.some(file => file === undefined))
+        return null;
+    const certifiedLaunchEntries = launchEntries;
+    const layersRoot = release.dependencyLayers?.length ? await realpath(resolve(canonicalData, "dependency-layers")) : null;
+    const dependencyLayers = await Promise.all((release.dependencyLayers ?? []).map(async (reference) => {
+        if (layersRoot === null)
+            throw new Error("restart certification has no dependency-layer root");
+        const layerRoot = await realpath(resolve(layersRoot, reference.layerId));
+        assertDirectChild(layersRoot, layerRoot, reference.layerId, "dependency layer");
+        const bindingPath = resolve(releaseRoot, reference.binding);
+        const bindingTarget = await realpath(bindingPath);
+        const expectedTarget = await realpath(resolve(layerRoot, "node_modules"));
+        if (bindingTarget !== expectedTarget)
+            throw new Error(`restart certification dependency binding targets unexpected content: ${bindingPath}`);
+        return {
+            ...reference,
+            layerRoot: await pathEvidence(layerRoot, "directory"),
+            manifest: await pathEvidence(resolve(layerRoot, DEPENDENCY_LAYER_MANIFEST), "file"),
+            certification: await pathEvidence(dependencyLayerCertificationPath(canonicalData, reference.layerId), "file"),
+            bindingEvidence: await pathEvidence(bindingPath, "binding", true),
+            bindingTarget,
+        };
+    }));
+    const core = {
+        version: RESTART_SEAL_VERSION,
+        platform: process.platform,
+        platformPolicy: policy,
+        releaseId: release.releaseId,
+        packageVersion: release.packageVersion,
+        contentDigest: release.contentDigest,
+        packageRoot: release.packageRoot,
+        releaseRoot: await pathEvidence(releaseRoot, "directory"),
+        manifest: await pathEvidence(manifestPath, "file"),
+        launchEntries: certifiedLaunchEntries,
+        launchEntryEvidence: await Promise.all(certifiedLaunchEntries.map(file => pathEvidence(resolve(releaseRoot, file.path), "file"))),
+        dependencyLayers,
+        certifiedAt: new Date().toISOString(),
+    };
+    return { ...core, sealDigest: restartSealDigest(core) };
+}
+/** Recover an approved release from durable bounded evidence without traversing its payload. */
+export async function readRestartCertifiedRelease(record, dataDir, onEvent) {
+    const transaction = await new UpdateTransactionStore(dataDir).read();
+    if (transaction?.status === "active")
+        throw new Error("restart certification is unavailable during an active update transaction");
+    const certificationPath = resolve(dataDir, `certification-${record.releaseId}.json`);
+    if (record.diagnosticsPath !== undefined && record.diagnosticsPath !== certificationPath) {
+        throw new Error("restart certification path differs from the approved release record");
+    }
+    const certificationMetadata = await lstat(certificationPath);
+    onEvent?.({ operation: "restart-evidence-read", path: certificationPath });
+    if (!certificationMetadata.isFile() || certificationMetadata.isSymbolicLink() || (certificationMetadata.mode & 0o222) !== 0) {
+        throw new Error("restart certification is not an immutable regular file");
+    }
+    const certification = await readJson(certificationPath, onEvent);
+    if (certification.schema !== PRODUCT_IDENTITY.evidence.releaseCertificationSchema
+        || certification.releaseId !== record.releaseId || certification.contentDigest !== record.contentDigest
+        || !certification.checks.some(check => check.id === "immutable-content" && check.passed)) {
+        throw new Error("restart certification differs from the approved release record");
+    }
+    const seal = normalizeRestartSeal(certification.restartSeal);
+    if (seal.platform !== process.platform || seal.platformPolicy !== immutablePlatformPolicy()) {
+        throw new Error("restart certification platform immutability evidence is unsupported");
+    }
+    if (seal.releaseId !== record.releaseId || seal.contentDigest !== record.contentDigest
+        || resolve(seal.releaseRoot.path) !== resolve(record.releaseRoot)
+        || (record.packageVersion !== undefined && seal.packageVersion !== record.packageVersion)) {
+        throw new Error("restart seal differs from the approved release identity");
+    }
+    const { sealDigest, ...core } = seal;
+    if (restartSealDigest(core) !== sealDigest)
+        throw new Error("restart seal digest is invalid");
+    const canonicalData = await observedRealpath(dataDir, onEvent);
+    const releasesRoot = await observedRealpath(resolve(canonicalData, "releases"), onEvent);
+    const releaseRoot = await observedRealpath(seal.releaseRoot.path, onEvent);
+    assertDirectChild(releasesRoot, releaseRoot, seal.releaseId, "release");
+    await assertPathEvidence(seal.releaseRoot, onEvent);
+    await assertPathEvidence(seal.manifest, onEvent);
+    for (let index = 0; index < seal.launchEntries.length; index += 1) {
+        const file = seal.launchEntries[index];
+        if (!REQUIRED_LAUNCH_ENTRIES.includes(file.path)) {
+            throw new Error(`restart seal contains an unexpected launch entry: ${file.path}`);
+        }
+        const evidence = seal.launchEntryEvidence[index];
+        if (!evidence || evidence.path !== resolve(releaseRoot, file.path) || file.bytes !== Number(evidence.size)) {
+            throw new Error(`restart launch entry evidence differs: ${file.path}`);
+        }
+        await assertPathEvidence(evidence, onEvent);
+    }
+    if (seal.launchEntries.length !== REQUIRED_LAUNCH_ENTRIES.length)
+        throw new Error("restart seal launch entries are incomplete");
+    const layersRoot = seal.dependencyLayers.length ? await observedRealpath(resolve(canonicalData, "dependency-layers"), onEvent) : null;
+    for (const layer of seal.dependencyLayers) {
+        if (layersRoot === null)
+            throw new Error("restart seal has no dependency-layer root");
+        const layerRoot = await observedRealpath(layer.layerRoot.path, onEvent);
+        assertDirectChild(layersRoot, layerRoot, layer.layerId, "dependency layer");
+        await assertPathEvidence(layer.layerRoot, onEvent);
+        await assertPathEvidence(layer.manifest, onEvent);
+        await assertPathEvidence(layer.certification, onEvent);
+        await assertPathEvidence(layer.bindingEvidence, onEvent, true);
+        const bindingTarget = await observedRealpath(layer.bindingEvidence.path, onEvent);
+        const expectedTarget = await observedRealpath(resolve(layerRoot, "node_modules"), onEvent);
+        if (bindingTarget !== layer.bindingTarget || bindingTarget !== expectedTarget) {
+            throw new Error(`restart dependency binding targets unexpected content: ${layer.bindingEvidence.path}`);
+        }
+    }
+    return {
+        packageName: PRODUCT_PACKAGE_NAME,
+        packageVersion: seal.packageVersion,
+        contentDigest: seal.contentDigest,
+        releaseId: seal.releaseId,
+        packageRoot: seal.packageRoot,
+        files: seal.launchEntries,
+        ...(seal.dependencyLayers.length === 0 ? {} : {
+            dependencyLayers: seal.dependencyLayers.map(({ layerId, contentDigest, binding }) => ({ layerId, contentDigest, binding })),
+        }),
+        releaseRoot,
+    };
+}
+export function releaseCertificationDocument(release, restartSeal, verifiedAt = new Date().toISOString()) {
+    return {
+        schema: PRODUCT_IDENTITY.evidence.releaseCertificationSchema,
+        releaseId: release.releaseId,
+        contentDigest: release.contentDigest,
+        verifiedAt,
+        checks: [{ id: "immutable-content", passed: true }],
+        restartSeal,
+    };
+}
+export function restartSealDigest(core) {
+    return createHash("sha256").update(JSON.stringify(core)).digest("hex");
+}
+async function assertPathEvidence(evidence, onEvent, symbolic = false) {
+    const actual = await pathEvidence(evidence.path, evidence.kind, symbolic, onEvent);
+    if (JSON.stringify(actual) !== JSON.stringify(evidence))
+        throw new Error(`restart path evidence changed: ${evidence.path}`);
+}
+async function pathEvidence(path, kind, symbolic = false, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    const metadata = symbolic ? await lstat(path, { bigint: true }) : await stat(path, { bigint: true });
+    if ((kind === "directory") !== metadata.isDirectory())
+        throw new Error(`restart evidence kind changed: ${path}`);
+    if (kind === "file" && !metadata.isFile())
+        throw new Error(`restart evidence file changed: ${path}`);
+    if (kind === "binding" && !metadata.isSymbolicLink())
+        throw new Error(`restart evidence binding changed: ${path}`);
+    if (kind === "file" && (metadata.mode & 146n) !== 0n)
+        throw new Error(`restart evidence file is writable: ${path}`);
+    return {
+        path: resolve(path),
+        kind,
+        device: metadata.dev.toString(),
+        inode: metadata.ino.toString(),
+        mode: Number(metadata.mode),
+        size: metadata.size.toString(),
+        modifiedNs: metadata.mtimeNs.toString(),
+        changedNs: metadata.ctimeNs.toString(),
+        bornNs: metadata.birthtimeNs.toString(),
+    };
+}
+function normalizeRestartSeal(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("release certification has no durable restart seal");
+    const seal = value;
+    if (seal.version !== RESTART_SEAL_VERSION || typeof seal.platform !== "string" || typeof seal.platformPolicy !== "string"
+        || typeof seal.releaseId !== "string" || typeof seal.packageVersion !== "string" || typeof seal.contentDigest !== "string"
+        || typeof seal.packageRoot !== "string" || typeof seal.certifiedAt !== "string" || typeof seal.sealDigest !== "string"
+        || !seal.releaseRoot || !seal.manifest || !Array.isArray(seal.launchEntries) || !Array.isArray(seal.launchEntryEvidence)
+        || !Array.isArray(seal.dependencyLayers)) {
+        throw new Error("durable restart seal is invalid");
+    }
+    return seal;
+}
+async function readJson(path, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    return JSON.parse(await readFile(path, "utf8"));
+}
+async function observedRealpath(path, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    return await realpath(path);
+}
+function assertDirectChild(parent, child, expectedName, kind) {
+    const fromParent = relative(parent, child);
+    if (isAbsolute(fromParent) || fromParent === ".." || fromParent.startsWith(`..${sep}`) || fromParent.includes(sep)
+        || basename(child) !== expectedName) {
+        throw new Error(`restart ${kind} is outside its managed store: ${child}`);
+    }
+}

package/dist/foundation/release/update.js

@@ -167,8 +167,8 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             onWarmup?.("started");
             await warmMaterializedRelease(candidate, environment);
             onWarmup?.("completed");
-            await startSupervisor(candidate, environment);
-            await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000);
+            const startup = await startSupervisor(candidate, environment);
+            await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000, startup);
         },
     };
 }
@@ -555,8 +555,8 @@ async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
     const paths = resolveProductPaths(environment);
     // Invariant: rollback re-points the active reference and starts the prior cohort on its own endpoint;
     // a cohort that survived the update keeps serving the work it already had.
-    await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, release.releaseId, environment).endpointMetadataPath, release, 8_000);
+    const startup = await startSupervisor(release, environment);
+    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, release.releaseId, environment).endpointMetadataPath, release, 8_000, startup);
     return "rolled back";
 }
 function phaseBefore(current, target) {

package/dist/foundation/release/warmup.js

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { releaseEnvironment } from "./bootstrap.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 /** Import the exact immutable startup graph in a terminal-free bounded child process. */
-export async function warmMaterializedRelease(release, environment, timeoutMs = 15_000) {
+export async function warmMaterializedRelease(release, environment, timeoutMs = 30_000) {
     const entry = resolve(release.releaseRoot, "bin", "warmup.js");
     await new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(process.execPath, [entry], {

package/dist/foundation/startup/startup-runtime.d.ts

@@ -1,8 +1,8 @@
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-export type StartupPhase = "command-invoked" | "bootstrap-start" | "bootstrap-selected" | "guardian-start" | "guardian-connected" | "ui-entry" | "ui-modules-loaded" | "pi-services" | "resource-discovery" | "session-created" | "settings-loaded" | "first-input-ready-render";
+export type StartupPhase = "command-invoked" | "bootstrap-start" | "bootstrap-selected" | "durable-validation-start" | "durable-validation-complete" | "replacement-supervisor-start" | "replacement-supervisor-ready" | "guardian-start" | "guardian-connected" | "ui-entry" | "ui-modules-loaded" | "pi-services" | "resource-discovery" | "session-created" | "settings-loaded" | "first-input-ready-render";
 export interface StartupPerformanceEvidence {
     readonly profileId: "a1" | "pi";
-    readonly launchKind: "post-update" | "warm";
+    readonly launchKind: "post-update" | "no-live-supervisor" | "warm";
     readonly events: readonly StartupTraceEvent[];
 }
 export interface StartupTraceEvent {

package/dist/foundation/startup/startup-runtime.js

@@ -100,7 +100,7 @@ export function assertStartupPerformanceBudget(evidence, budgets = { postUpdateM
     const ready = events.findLast(event => event.phase === "first-input-ready-render");
     if (!ready)
         throw new Error(`startup budget failed for ${evidence.profileId}: first input-ready render was not recorded`);
-    const budget = evidence.launchKind === "post-update" ? budgets.postUpdateMs : budgets.warmMs;
+    const budget = evidence.launchKind === "warm" ? budgets.warmMs : budgets.postUpdateMs;
     if (ready.elapsedMs <= budget)
         return;
     const intervals = events.map((event, index) => ({

package/dist/foundation/supervision/main.d.ts

@@ -1 +1 @@
-export declare function runSupervisor(): Promise<void>;
+export declare function runSupervisor(arguments_?: readonly string[]): Promise<void>;

package/dist/foundation/supervision/main.js

@@ -2,11 +2,12 @@ import { randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
 import { assertImmutableExecutionRoot, CohortStateStore, readCertifiedReleaseManifest } from "../release/index.js";
+import { publishSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath } from "../lifecycle/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
 import { SupervisorServer } from "./server.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
-export async function runSupervisor() {
+export async function runSupervisor(arguments_ = []) {
     const productPaths = resolveProductPaths();
     mkdirSync(productPaths.runtimeDir, { recursive: true, mode: 0o700 });
     mkdirSync(productPaths.endpointsDir, { recursive: true, mode: 0o700 });
@@ -15,33 +16,62 @@ export async function runSupervisor() {
     const releaseRoot = process.env[PRODUCT_IDENTITY.environment.releaseRoot];
     const releaseId = process.env[PRODUCT_IDENTITY.environment.releaseId];
     const contentDigest = process.env[PRODUCT_IDENTITY.environment.releaseDigest];
-    if (!releaseRoot || !releaseId || !contentDigest)
-        throw new Error(PRODUCT_TEXT.diagnostic("supervisor must be launched from a verified immutable release"));
-    const release = await readCertifiedReleaseManifest({ releaseRoot, releaseId, contentDigest }, resolve(paths.dataDir, "releases"));
-    await assertImmutableExecutionRoot(release, paths.dataDir);
-    // Protocol: one endpoint per cohort: a superseded cohort keeps serving what it already has while the
-    // installed release listens on its own address.
-    paths = { ...productPaths, ...resolveCohortEndpoint(productPaths, release.releaseId) };
-    const bootNonce = randomUUID();
-    const store = new ControlStore(paths.databasePath, bootNonce);
-    const cohortState = new CohortStateStore(paths.dataDir);
-    const server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => (await cohortState.read()).references.active);
-    await server.listen();
-    log(`supervisor ${server.id} listening at ${paths.endpoint} (pid ${process.pid})`);
-    let closing = false;
-    const close = async (signal) => {
-        if (closing)
-            return;
-        closing = true;
-        log(`received ${signal}; stopping supervised process tree`);
-        await server.close(true);
-        process.exitCode = 0;
-    };
-    process.on("SIGINT", () => void close("SIGINT"));
-    process.on("SIGTERM", () => void close("SIGTERM"));
-    process.on("uncaughtException", error => {
-        log(`uncaught exception: ${error.stack ?? error.message}`);
-        process.exitCode = 1;
-    });
-    process.on("unhandledRejection", error => log(`unhandled rejection: ${String(error)}`));
+    const attemptId = startupAttempt(arguments_);
+    const resultPath = attemptId ? supervisorStartupResultPath(productPaths.runtimeDir, attemptId) : null;
+    let stage = "release-environment";
+    let server = null;
+    try {
+        if (!releaseRoot || !releaseId || !contentDigest)
+            throw new Error(PRODUCT_TEXT.diagnostic("supervisor must be launched from a verified immutable release"));
+        stage = "release-certification";
+        const release = await readCertifiedReleaseManifest({ releaseRoot, releaseId, contentDigest }, resolve(paths.dataDir, "releases"));
+        stage = "immutable-root";
+        await assertImmutableExecutionRoot(release, paths.dataDir);
+        // Protocol: one endpoint per cohort: a superseded cohort keeps serving what it already has while the
+        // installed release listens on its own address.
+        paths = { ...productPaths, ...resolveCohortEndpoint(productPaths, release.releaseId) };
+        stage = "storage";
+        const bootNonce = randomUUID();
+        const store = new ControlStore(paths.databasePath, bootNonce);
+        const cohortState = new CohortStateStore(paths.dataDir);
+        server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => (await cohortState.read()).references.active);
+        stage = "endpoint-listen";
+        await server.listen();
+        if (resultPath && attemptId)
+            await publishSupervisorStartupResult(resultPath, supervisorStartupReady(attemptId, release.releaseId));
+        log(`supervisor ${server.id} listening at ${paths.endpoint} (pid ${process.pid})`);
+        let closing = false;
+        const close = async (signal) => {
+            if (closing)
+                return;
+            closing = true;
+            log(`received ${signal}; stopping supervised process tree`);
+            await server?.close(true);
+            process.exitCode = 0;
+        };
+        process.on("SIGINT", () => void close("SIGINT"));
+        process.on("SIGTERM", () => void close("SIGTERM"));
+        process.on("uncaughtException", error => {
+            log(`uncaught exception: ${error.stack ?? error.message}`);
+            process.exitCode = 1;
+        });
+        process.on("unhandledRejection", error => log(`unhandled rejection: ${String(error)}`));
+    }
+    catch (error) {
+        await server?.close(true).catch(() => undefined);
+        const message = error instanceof Error ? error.stack ?? error.message : String(error);
+        log(`startup failure at ${stage}: ${message}`);
+        if (resultPath && attemptId && releaseId) {
+            await publishSupervisorStartupResult(resultPath, supervisorStartupFailure(error, attemptId, releaseId, stage)).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+function startupAttempt(arguments_) {
+    if (arguments_.length === 0)
+        return null;
+    if (arguments_.length !== 2 || arguments_[0] !== "--startup-attempt" || !arguments_[1]) {
+        throw new Error(PRODUCT_TEXT.diagnostic("supervisor startup arguments are invalid"));
+    }
+    return arguments_[1];
 }

package/dist/foundation/supervision/server.js

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { createConnection, createServer } from "node:net";
 import { platform } from "node:os";
+import { dirname } from "node:path";
 import { assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
 import { encodeFrame, isCommandMessage, isControlHello, LineFrameDecoder, localControlHello, MAX_CONTROL_FRAME_BYTES, negotiateControlFeatures } from "../protocol/index.js";
 import { processIsAlive } from "../release/index.js";
@@ -71,6 +72,8 @@ export class SupervisorServer {
         await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
         await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
         if (platform() !== "win32") {
+            if (this.paths.endpointDirectory)
+                await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
             if (await endpointIsLive(this.paths.endpoint))
                 throw new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`));
             await rm(this.paths.endpoint, { force: true });
@@ -489,6 +492,16 @@ function sameContainmentIdentity(left, right) {
 function isMessageType(value, type) {
     return typeof value === "object" && value !== null && "type" in value && value.type === type;
 }
+async function ensureManagedEndpointDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const metadata = await lstat(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error(`managed endpoint path is not a directory: ${path}`);
+    const currentUser = process.getuid?.();
+    if (currentUser !== undefined && metadata.uid !== currentUser)
+        throw new Error(`managed endpoint directory has another owner: ${path}`);
+    await chmod(path, 0o700);
+}
 async function endpointIsLive(endpoint) {
     return await new Promise(resolve => {
         const socket = createConnection(endpoint);