@timurproko/a1 0.1.8-dev.218 → 0.1.8-dev.224

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

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { PRODUCT_PACKAGE_NAME, createReleaseIdentity, digestManifestFiles, discoverReleasePayload, releaseFileIdentity, resolveWithin, } from "./release.js";
+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 { dependencyReference, materializeDependencyLayer, readCertifiedDependencyLayer, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 const RELEASE_FILE_IO_CONCURRENCY = 32;
 const certificationReady = new WeakSet();
 export const RELEASE_MANIFEST_FILENAME = PRODUCT_IDENTITY.manifest.releaseFilename;
@@ -13,15 +14,32 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
     });
     const storeRoot = resolve(dataDir, "releases");
     await mkdir(storeRoot, { recursive: true, mode: 0o700 });
-    options.onProgress?.({ phase: "copying", fileCount: payload.paths.length });
+    const dependencyPaths = payload.paths.filter(path => path.startsWith("node_modules/"));
+    const productPaths = payload.paths.filter(path => !path.startsWith("node_modules/"));
+    const selectedDependencies = await selectPublishedDependencyRuntimePayload(payload.packageRoot, dependencyPaths);
+    options.onRuntimeInventory?.(selectedDependencies.inventory);
+    const layerOperations = [];
+    const layer = await materializeDependencyLayer(payload.packageRoot, dataDir, selectedDependencies.paths, {
+        inventory: selectedDependencies.inventory,
+        cachedFiles: payload.cachedFiles,
+        onOperation: event => layerOperations.push(event),
+        ...(options.writeCandidateFile === undefined ? {} : { writeCandidateFile: options.writeCandidateFile }),
+    });
+    const layerReferences = layer === null ? [] : [dependencyReference(layer)];
+    options.onProgress?.({
+        phase: "copying",
+        fileCount: productPaths.length + (layer?.reused === false ? layer.files.length : 0),
+    });
+    for (const event of layerOperations)
+        options.onOperation?.(event);
     const candidate = resolveWithin(storeRoot, `.candidate-${randomUUID()}`);
     await mkdir(candidate, { recursive: false, mode: 0o700 });
     try {
-        const directories = [...new Set(payload.paths.map(path => dirname(resolveWithin(candidate, path))))];
+        const directories = [...new Set(productPaths.map(path => dirname(resolveWithin(candidate, path))))];
         await mapWithConcurrency(directories, RELEASE_FILE_IO_CONCURRENCY, async (directory) => {
             await mkdir(directory, { recursive: true, mode: 0o700 });
         });
-        const files = await mapWithConcurrency(payload.paths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
+        const files = await mapWithConcurrency(productPaths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
             const source = resolveWithin(payload.packageRoot, path);
             const destination = resolveWithin(candidate, path);
             const metadata = await lstat(source);
@@ -41,7 +59,12 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
             options.onOperation?.({ operation: "candidate-write", path, bytes: bytes.length });
             return releaseFileIdentity(path, bytes, (metadata.mode & 0o111) !== 0);
         });
-        const identity = createReleaseIdentity(payload.packageRoot, payload.packageVersion, files);
+        const identity = createReleaseIdentity(payload.packageRoot, payload.packageVersion, files, layerReferences);
+        if (layer !== null) {
+            const binding = resolveWithin(candidate, "node_modules");
+            const target = resolveWithin(layer.layerRoot, "node_modules");
+            await symlink(target, binding, process.platform === "win32" ? "junction" : "dir");
+        }
         const releaseRoot = resolveWithin(storeRoot, identity.releaseId);
         if (await lstat(releaseRoot).catch(() => null)) {
             await rm(candidate, { recursive: true, force: true });
@@ -84,7 +107,8 @@ export async function readMaterializedRelease(releaseRoot) {
  */
 export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
     const canonical = await realpath(record.releaseRoot);
-    assertContained(await realpath(selectedStoreRoot), canonical, "release root is outside the selected release store");
+    const canonicalStoreRoot = await realpath(selectedStoreRoot);
+    assertContained(canonicalStoreRoot, canonical, "release root is outside the selected release store");
     const manifest = JSON.parse(await readFile(resolveWithin(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
     validateManifest(manifest);
     if (manifest.releaseId !== record.releaseId || manifest.contentDigest !== record.contentDigest
@@ -93,12 +117,13 @@ export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
     }
     if (canonical.split(sep).at(-1) !== manifest.releaseId)
         throw new Error(`release directory does not match identity ${manifest.releaseId}`);
+    await verifyReleaseDependencies(canonical, canonicalStoreRoot, manifest.dependencyLayers ?? [], false);
     return { ...manifest, releaseRoot: canonical };
 }
 export async function verifyMaterializedRelease(releaseRoot, expected, selectedStoreRoot, options = {}) {
     const canonical = await realpath(releaseRoot);
-    if (selectedStoreRoot)
-        assertContained(await realpath(selectedStoreRoot), canonical, "release root is outside the selected release store");
+    const canonicalStoreRoot = selectedStoreRoot ? await realpath(selectedStoreRoot) : await realpath(dirname(canonical));
+    assertContained(canonicalStoreRoot, canonical, "release root is outside the selected release store");
     const manifestPath = resolveWithin(canonical, RELEASE_MANIFEST_FILENAME);
     const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
     validateManifest(manifest);
@@ -111,9 +136,10 @@ export async function verifyMaterializedRelease(releaseRoot, expected, selectedS
     await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
         await verifyFile(canonical, file, options);
     });
-    const recomputed = digestManifestFiles(manifest.files);
+    const recomputed = createReleaseIdentity(manifest.packageRoot, manifest.packageVersion, manifest.files, manifest.dependencyLayers ?? []).contentDigest;
     if (recomputed !== manifest.contentDigest)
         throw new Error(`release content digest mismatch for ${manifest.releaseId}`);
+    await verifyReleaseDependencies(canonical, canonicalStoreRoot, manifest.dependencyLayers ?? [], true, options);
     return { ...manifest, releaseRoot: canonical };
 }
 export async function assertImmutableExecutionRoot(release, dataDir) {
@@ -135,6 +161,25 @@ export async function resolveReleaseEntryPoint(release, entryPoint) {
     assertContained(release.releaseRoot, canonical, "entry point resolves outside the selected release root");
     return canonical;
 }
+async function verifyReleaseDependencies(releaseRoot, storeRoot, references, fullVerification, options = {}) {
+    if (references.length === 0)
+        return;
+    if (references.length !== 1)
+        throw new Error("release currently supports exactly one dependency layer");
+    const dataDir = dirname(storeRoot);
+    const reference = references[0];
+    const layer = fullVerification
+        ? await verifyDependencyLayer(dataDir, reference, event => options.onOperation?.({ operation: event.operation, path: event.path, bytes: event.bytes }))
+        : await readCertifiedDependencyLayer(dataDir, reference.layerId, reference);
+    const binding = resolveWithin(releaseRoot, reference.binding);
+    const metadata = await lstat(binding);
+    if (!metadata.isSymbolicLink())
+        throw new Error(`release dependency binding is not managed: ${binding}`);
+    const target = await realpath(binding);
+    const expected = await realpath(resolveWithin(layer.layerRoot, "node_modules"));
+    if (target !== expected)
+        throw new Error(`release dependency binding targets unexpected content: ${target}`);
+}
 async function verifyFile(root, file, options) {
     const path = resolveWithin(root, file.path);
     const metadata = await lstat(path).catch(() => null);
@@ -159,6 +204,11 @@ function validateManifest(value) {
         throw new Error(PRODUCT_TEXT.diagnostic("release identity is invalid"));
     if (!Array.isArray(value.files) || value.files.length === 0)
         throw new Error("release manifest contains no files");
+    if (value.dependencyLayers !== undefined && (!Array.isArray(value.dependencyLayers) || value.dependencyLayers.length === 0
+        || value.dependencyLayers.some(layer => !/^dependencies-[a-f0-9]{32}$/.test(layer.layerId)
+            || !/^[a-f0-9]{64}$/.test(layer.contentDigest) || layer.binding !== "node_modules"))) {
+        throw new Error("release dependency-layer references are invalid");
+    }
     for (const file of value.files) {
         if (typeof file.path !== "string" || file.path.length === 0 || file.path.includes("\\") || file.path.startsWith("/") || file.path.split("/").includes("..")) {
             throw new Error(`invalid release manifest path: ${String(file.path)}`);

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

@@ -1,3 +1,4 @@
+import type { DependencyLayerReference } from "./dependency-layer.js";
 export declare const PRODUCT_PACKAGE_NAME: string;
 export interface ReleaseFileIdentity {
     readonly path: string;
@@ -12,6 +13,8 @@ export interface ReleaseIdentity {
     readonly releaseId: string;
     readonly packageRoot: string;
     readonly files: readonly ReleaseFileIdentity[];
+    /** Absent for legacy full-copy releases. */
+    readonly dependencyLayers?: readonly DependencyLayerReference[];
 }
 export interface DiscoveredReleasePayload {
     readonly packageRoot: string;
@@ -31,7 +34,7 @@ export declare function discoverReleasePayload(packageRoot: string, options?: Di
  * content.
  */
 export declare function deriveReleaseIdentity(packageRoot: string): Promise<ReleaseIdentity>;
-export declare function createReleaseIdentity(packageRoot: string, packageVersion: string, files: readonly ReleaseFileIdentity[]): ReleaseIdentity;
+export declare function createReleaseIdentity(packageRoot: string, packageVersion: string, files: readonly ReleaseFileIdentity[], dependencyLayers?: readonly DependencyLayerReference[]): ReleaseIdentity;
 export declare function releaseFileIdentity(path: string, bytes: Uint8Array, executable: boolean): ReleaseFileIdentity;
 export declare function digestManifestFiles(files: readonly ReleaseFileIdentity[]): string;
 export declare function resolveWithin(root: string, candidate: string): string;

package/dist/foundation/release/release.js

@@ -51,8 +51,14 @@ export async function deriveReleaseIdentity(packageRoot) {
     });
     return createReleaseIdentity(payload.packageRoot, payload.packageVersion, files);
 }
-export function createReleaseIdentity(packageRoot, packageVersion, files) {
-    const contentDigest = digestManifestFiles(files);
+export function createReleaseIdentity(packageRoot, packageVersion, files, dependencyLayers = []) {
+    const productDigest = digestManifestFiles(files);
+    const contentDigest = dependencyLayers.length === 0
+        ? productDigest
+        : createHash("sha256")
+            .update(`product\0${productDigest}\n`)
+            .update(dependencyLayers.map(layer => `${layer.layerId}\0${layer.contentDigest}\0${layer.binding}\n`).join(""))
+            .digest("hex");
     return {
         packageName: PRODUCT_PACKAGE_NAME,
         packageVersion,
@@ -60,6 +66,7 @@ export function createReleaseIdentity(packageRoot, packageVersion, files) {
         releaseId: `${packageVersion}-${contentDigest.slice(0, 20)}`,
         packageRoot,
         files: [...files].sort(compareReleaseFiles),
+        ...(dependencyLayers.length === 0 ? {} : { dependencyLayers: [...dependencyLayers] }),
     };
 }
 export function releaseFileIdentity(path, bytes, executable) {

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

@@ -18,7 +18,7 @@ export interface UpdateOutput {
     stdout(message: string): void;
     stderr(message: string): void;
 }
-export type UpdateMeasuredPhase = "package-version" | "target-resolution" | "global-root" | "ownership-release" | "npm-install" | "materialized" | "certified" | "active-reference-committed" | "supervisor-verified" | "transaction-complete";
+export type UpdateMeasuredPhase = "package-version" | "target-resolution" | "global-root" | "ownership-release" | "npm-install" | "materialized" | "certified" | "active-reference-committed" | "warmup" | "supervisor-verified" | "transaction-complete";
 export interface UpdatePhaseTimingEvent {
     readonly phase: UpdateMeasuredPhase;
     readonly durationMs: number;
@@ -28,6 +28,12 @@ export interface UpdatePerformanceEvidence {
     readonly sourceReads: number;
     readonly candidateWrites: number;
     readonly verificationReads: number;
+    readonly layerWrites?: number;
+    readonly layerReusedFiles?: number;
+    readonly layerReusedBytes?: number;
+    readonly payloadExcludedFiles?: number;
+    readonly payloadExcludedBytes?: number;
+    readonly warmupDurationMs?: number;
     readonly postNpmDurationMs: number;
 }
 export interface SelfUpdateOptions {
@@ -41,6 +47,8 @@ export interface SelfUpdateOptions {
     runner?: UpdateProcessRunner;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
+    /** Test or embedding seam for post-activation release maintenance. */
+    maintenance?: () => Promise<void>;
     progress?: boolean;
     onPhaseTiming?: (event: UpdatePhaseTimingEvent) => void;
     now?: () => number;
@@ -61,7 +69,7 @@ export interface UpdateLifecycleCoordinator {
         priorActiveVersion: string | null;
     }>;
     verifyPackageUnlocked(packageRoot: string): Promise<void>;
-    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void): Promise<void>;
+    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void, onWarmup?: (state: "started" | "completed") => void): Promise<void>;
 }
 export interface UpdateTransactionJournal {
     readonly path: string;

package/dist/foundation/release/update.js

@@ -11,6 +11,8 @@ import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { CohortStateStore } from "./cohort-state.js";
 import { cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
 import { materializeRelease, readMaterializedRelease } from "./release-store.js";
+import { scheduleReleaseCleanup } from "./release-gc.js";
+import { warmMaterializedRelease } from "./warmup.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
 const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
@@ -138,7 +140,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                 throw new Error(PRODUCT_TEXT.diagnostic(`package remains locked after verified shutdown: ${errorMessage(error)}`));
             }
         },
-        async activateInstalled(packageRoot, targetVersion, phase, onMaterializing) {
+        async activateInstalled(packageRoot, targetVersion, phase, onMaterializing, onWarmup) {
             let total = 0;
             let completed = 0;
             const candidate = await materializeRelease(packageRoot, paths.dataDir, {
@@ -147,7 +149,7 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                     onMaterializing?.({ completed, total });
                 },
                 onOperation: event => {
-                    if (event.operation !== "candidate-write")
+                    if (event.operation !== "candidate-write" && event.operation !== "layer-write")
                         return;
                     completed += 1;
                     onMaterializing?.({ completed, total });
@@ -162,6 +164,9 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             await phase("certified");
             await stateStore.activate(candidate.releaseId);
             await phase("active-reference-committed");
+            onWarmup?.("started");
+            await warmMaterializedRelease(candidate, environment);
+            onWarmup?.("completed");
             await startSupervisor(candidate, environment);
             await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000);
         },
@@ -364,6 +369,9 @@ export async function runSelfUpdate(options) {
     const paths = resolveProductPaths(environment);
     const lifecycle = options.lifecycle ?? createUpdateLifecycleCoordinator(environment, fileSystem, output);
     const transactionStore = options.transactionStore ?? new UpdateTransactionStore(paths.dataDir);
+    const maintenance = options.maintenance ?? (options.lifecycle
+        ? async () => { }
+        : async () => await scheduleReleaseCleanup(paths.dataDir, paths));
     let transaction = await transactionStore.read();
     try {
         if (await lifecycle.targetIsActive(targetVersion)) {
@@ -371,6 +379,7 @@ export async function runSelfUpdate(options) {
                 await transactionStore.advance("supervisor-verified");
                 await transactionStore.finish("completed");
             }
+            await maintenance();
             await transactionStore.clearCompleted();
             output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
             return 0;
@@ -432,11 +441,24 @@ export async function runSelfUpdate(options) {
             const span = MATERIALIZE_PROGRESS.to - MATERIALIZE_PROGRESS.from;
             const done = total > 0 ? Math.min(1, completed / total) : 0;
             progress.set(MATERIALIZE_PROGRESS.from + span * done);
+        }, state => {
+            if (state === "started") {
+                activationPhaseStartedAt = now();
+                progress.set(98, 99);
+            }
+            else {
+                options.onPhaseTiming?.({ phase: "warmup", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
+                activationPhaseStartedAt = now();
+                progress.set(99);
+            }
         });
         options.onPhaseTiming?.({ phase: "supervisor-verified", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
         const transactionStartedAt = now();
         await transactionStore.advance("supervisor-verified");
         await transactionStore.finish("completed");
+        // Invariant: successful output follows the durable cleanup disposition. Slow recursive
+        // removal belongs to the detached worker started by this maintenance coordinator.
+        await maintenance();
         await transactionStore.clearCompleted();
         options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
         progress.finish();
@@ -461,8 +483,9 @@ export function assertUpdatePerformanceBudget(evidence, maximumPostNpmDurationMs
         failures.push("fixture contains no payload files");
     if (evidence.sourceReads !== evidence.fileCount)
         failures.push(`source payload read count is ${evidence.sourceReads} for ${evidence.fileCount} files`);
-    if (evidence.candidateWrites !== evidence.fileCount)
-        failures.push(`candidate payload write count is ${evidence.candidateWrites} for ${evidence.fileCount} files`);
+    const totalWrites = evidence.candidateWrites + (evidence.layerWrites ?? 0);
+    if (totalWrites !== evidence.fileCount)
+        failures.push(`runtime payload write count is ${totalWrites} for ${evidence.fileCount} files`);
     if (evidence.verificationReads > 0)
         failures.push(`fresh certification reread ${evidence.verificationReads} candidate files`);
     if (evidence.postNpmDurationMs > maximumPostNpmDurationMs)

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

@@ -0,0 +1,3 @@
+import type { MaterializedRelease } from "./release-store.js";
+/** Import the exact immutable startup graph in a terminal-free bounded child process. */
+export declare function warmMaterializedRelease(release: MaterializedRelease, environment: NodeJS.ProcessEnv, timeoutMs?: number): Promise<void>;

package/dist/foundation/release/warmup.js

@@ -0,0 +1,35 @@
+import { spawn } from "node:child_process";
+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) {
+    const entry = resolve(release.releaseRoot, "bin", "warmup.js");
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [entry], {
+            env: { ...releaseEnvironment(environment, release), [PRODUCT_IDENTITY.environment.immutableWarmup]: "1" },
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                rejectPromise(error);
+            else
+                resolvePromise();
+        };
+        child.once("error", error => finish(error));
+        child.once("close", (code, signal) => finish(code === 0
+            ? undefined
+            : new Error(`immutable startup warmup exited with ${code === null ? signal ?? "unknown status" : `status ${code}`}`)));
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(new Error(`immutable startup warmup exceeded ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+    });
+}

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

@@ -0,0 +1 @@
+export * from "./startup-runtime.js";

package/dist/foundation/startup/index.js

@@ -0,0 +1 @@
+export * from "./startup-runtime.js";

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

@@ -0,0 +1,36 @@
+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 interface StartupPerformanceEvidence {
+    readonly profileId: "a1" | "pi";
+    readonly launchKind: "post-update" | "warm";
+    readonly events: readonly StartupTraceEvent[];
+}
+export interface StartupTraceEvent {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.startupTraceSchema;
+    readonly traceId: string;
+    readonly phase: StartupPhase;
+    readonly elapsedMs: number;
+    readonly processId: number;
+    readonly profileId: string;
+    readonly releaseId: string | null;
+    readonly dependencyLayerIds: readonly string[];
+    readonly nodeVersion: string;
+    readonly fileReadOperations: number;
+}
+/** Initialize opt-in startup tracing from a caller-provided evidence path. */
+export declare function initializeStartupTrace(environment: NodeJS.ProcessEnv, profileId: string, startedAtMs?: number): void;
+/** Append one redacted phase event; ordinary launches without trace context perform no I/O. */
+export declare function markStartupPhase(environment: NodeJS.ProcessEnv, phase: StartupPhase): Promise<void>;
+export declare function assertImmutableWarmupEnvironment(environment: NodeJS.ProcessEnv): void;
+/** Enable the compile cache directly from launch environment without loading profile services. */
+export declare function enableEnvironmentCompileCache(environment: NodeJS.ProcessEnv): string | null;
+/** Enable Node's supported persistent compile cache in an immutable-identity namespace. */
+export declare function enableStartupCompileCache(dataDir: string, releaseId: string | null, dependencyLayerIds: readonly string[]): string | null;
+export declare function startupCompileCachePath(dataDir: string, releaseId: string | null, dependencyLayerIds: readonly string[]): string;
+/** Retain current compile namespaces plus a bounded number of recent fallbacks. */
+export declare function collectCompileCaches(dataDir: string, protectedPaths: readonly string[], keepRecent?: number): Promise<void>;
+export declare function assertStartupPerformanceBudget(evidence: StartupPerformanceEvidence, budgets?: {
+    readonly postUpdateMs: number;
+    readonly warmMs: number;
+}): void;
+export declare function parseStartupTrace(source: string): readonly StartupTraceEvent[];

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

@@ -0,0 +1,140 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, mkdir, readdir, rm } from "node:fs/promises";
+import { constants as moduleConstants, enableCompileCache } from "node:module";
+import { dirname, resolve } from "node:path";
+import { homedir, platform } from "node:os";
+import { performance } from "node:perf_hooks";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/** Initialize opt-in startup tracing from a caller-provided evidence path. */
+export function initializeStartupTrace(environment, profileId, startedAtMs = performance.timeOrigin + performance.now()) {
+    const configured = environment[PRODUCT_IDENTITY.environment.startupTrace];
+    if (!configured || parseContext(configured) !== null)
+        return;
+    const context = {
+        path: resolve(configured),
+        traceId: randomUUID(),
+        startedAtMs,
+        profileId,
+        releaseId: environment[PRODUCT_IDENTITY.environment.releaseId] ?? null,
+        dependencyLayerIds: parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers]),
+    };
+    environment[PRODUCT_IDENTITY.environment.startupTrace] = JSON.stringify(context);
+}
+/** Append one redacted phase event; ordinary launches without trace context perform no I/O. */
+export async function markStartupPhase(environment, phase) {
+    const context = parseContext(environment[PRODUCT_IDENTITY.environment.startupTrace]);
+    if (context === null)
+        return;
+    const event = {
+        schema: PRODUCT_IDENTITY.evidence.startupTraceSchema,
+        traceId: context.traceId,
+        phase,
+        elapsedMs: Math.max(0, performance.timeOrigin + performance.now() - context.startedAtMs),
+        processId: process.pid,
+        profileId: context.profileId,
+        releaseId: environment[PRODUCT_IDENTITY.environment.releaseId] ?? context.releaseId,
+        dependencyLayerIds: parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers]).length > 0
+            ? parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers])
+            : context.dependencyLayerIds,
+        nodeVersion: process.version,
+        fileReadOperations: process.resourceUsage().fsRead,
+    };
+    await mkdir(dirname(context.path), { recursive: true, mode: 0o700 });
+    await appendFile(context.path, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+export function assertImmutableWarmupEnvironment(environment) {
+    if (environment[PRODUCT_IDENTITY.environment.immutableWarmup] !== "1") {
+        throw new Error("warmup entry is private to verified update activation");
+    }
+}
+/** Enable the compile cache directly from launch environment without loading profile services. */
+export function enableEnvironmentCompileCache(environment) {
+    const home = environment.HOME ?? environment.USERPROFILE ?? homedir();
+    const dataDir = resolve(environment[PRODUCT_IDENTITY.environment.dataDir]
+        ?? (platform() === "win32"
+            ? resolve(environment.LOCALAPPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : resolve(environment.XDG_DATA_HOME ?? resolve(home, ".local", "share"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    return enableStartupCompileCache(dataDir, environment[PRODUCT_IDENTITY.environment.releaseId] ?? null, parseLayerIds(environment[PRODUCT_IDENTITY.environment.releaseLayers]));
+}
+/** Enable Node's supported persistent compile cache in an immutable-identity namespace. */
+export function enableStartupCompileCache(dataDir, releaseId, dependencyLayerIds) {
+    try {
+        const path = startupCompileCachePath(dataDir, releaseId, dependencyLayerIds);
+        const result = enableCompileCache(path);
+        return result.status === moduleConstants.compileCacheStatus.FAILED ? null : result.directory ?? path;
+    }
+    catch {
+        return null;
+    }
+}
+export function startupCompileCachePath(dataDir, releaseId, dependencyLayerIds) {
+    const layers = createHash("sha256").update(dependencyLayerIds.join("\0")).digest("hex").slice(0, 20);
+    const content = dependencyLayerIds.length > 0
+        ? `layers-${layers}`
+        : `release-${(releaseId ?? "mutable").replace(/[^0-9A-Za-z.+_-]/g, "_")}`;
+    // Performance: stable layer paths share compiled dependency entries across product releases;
+    // Node's own cache key still isolates each release-specific module path and source bytes.
+    return resolve(dataDir, "cache", "compile", `${process.versions.modules ?? "node"}-${process.version.replace(/[^0-9A-Za-z.-]/g, "_")}-${content}`);
+}
+/** Retain current compile namespaces plus a bounded number of recent fallbacks. */
+export async function collectCompileCaches(dataDir, protectedPaths, keepRecent = 2) {
+    const root = resolve(dataDir, "cache", "compile");
+    const protectedSet = new Set(protectedPaths.map(path => resolve(path)));
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const candidates = await Promise.all(entries.filter(entry => entry.isDirectory()).map(async (entry) => {
+        const path = resolve(root, entry.name);
+        const metadata = await import("node:fs/promises").then(fs => fs.stat(path));
+        return { path, mtimeMs: metadata.mtimeMs };
+    }));
+    const retainedRecent = new Set(candidates.filter(item => !protectedSet.has(item.path))
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .slice(0, keepRecent)
+        .map(item => item.path));
+    for (const candidate of candidates) {
+        if (!protectedSet.has(candidate.path) && !retainedRecent.has(candidate.path))
+            await rm(candidate.path, { recursive: true, force: true });
+    }
+}
+export function assertStartupPerformanceBudget(evidence, budgets = { postUpdateMs: 5_000, warmMs: 3_000 }) {
+    const events = [...evidence.events].sort((left, right) => left.elapsedMs - right.elapsedMs);
+    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;
+    if (ready.elapsedMs <= budget)
+        return;
+    const intervals = events.map((event, index) => ({
+        phase: event.phase,
+        durationMs: event.elapsedMs - (events[index - 1]?.elapsedMs ?? 0),
+    })).sort((left, right) => right.durationMs - left.durationMs);
+    throw new Error(`startup budget failed for ${evidence.profileId} ${evidence.launchKind}: ${Math.round(ready.elapsedMs)}ms exceeds ${budget}ms; dominant phases: ${intervals.slice(0, 3).map(item => `${item.phase} ${Math.round(item.durationMs)}ms`).join(", ")}`);
+}
+export function parseStartupTrace(source) {
+    const events = source.split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));
+    for (const event of events) {
+        if (event.schema !== PRODUCT_IDENTITY.evidence.startupTraceSchema || typeof event.traceId !== "string"
+            || typeof event.phase !== "string" || !Number.isFinite(event.elapsedMs) || !Array.isArray(event.dependencyLayerIds)) {
+            throw new Error("startup trace contains an invalid event");
+        }
+    }
+    return events.sort((left, right) => left.elapsedMs - right.elapsedMs);
+}
+function parseContext(value) {
+    if (!value?.startsWith("{"))
+        return null;
+    try {
+        const context = JSON.parse(value);
+        if (typeof context.path !== "string" || typeof context.traceId !== "string" || !Number.isFinite(context.startedAtMs)
+            || typeof context.profileId !== "string" || !Array.isArray(context.dependencyLayerIds))
+            return null;
+        return context;
+    }
+    catch {
+        return null;
+    }
+}
+function parseLayerIds(value) {
+    if (!value)
+        return [];
+    return [...new Set(value.split(",").filter(id => /^dependencies-[a-f0-9]{32}$/.test(id)))].sort();
+}

package/dist/integrations/pi/engine/runtime-integration.js

@@ -1,5 +1,6 @@
 import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, resolveModelScopeWithDiagnostics, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { resolvePiProjectTrustPreflight, } from "./project-trust-preflight.js";
+import { markStartupPhase } from "../../../foundation/startup/index.js";
 /**
  * Mirrors pinned Pi's CLI startup: resolve the `models` patterns from settings
  * into a scoped model list, keep the resolver's warnings (e.g. "No models match
@@ -41,7 +42,10 @@ export async function createPiRuntimeServicesAfterTrust(options) {
         ...(options.projectTrustPrompt === undefined ? {} : { prompt: options.projectTrustPrompt }),
     });
     const settingsManager = createSettingsManager(options.cwd, options.agentDir, trust.trusted);
+    await markStartupPhase(process.env, "settings-loaded");
     const services = await createServices({ cwd: options.cwd, agentDir: options.agentDir, settingsManager });
+    await markStartupPhase(process.env, "pi-services");
+    await markStartupPhase(process.env, "resource-discovery");
     return { services, trust };
 }
 export async function createPiRuntimeIntegration(options) {
@@ -66,6 +70,7 @@ export async function createPiRuntimeIntegration(options) {
             ...(modelScope.thinkingLevel && !hasExistingSession ? { thinkingLevel: modelScope.thinkingLevel } : {}),
             ...(modelScope.scopedModels.length > 0 ? { scopedModels: [...modelScope.scopedModels] } : {}),
         });
+        await markStartupPhase(process.env, "session-created");
         return {
             ...created,
             services,

package/dist/native/darwin-arm64/manifest.json

@@ -5,11 +5,11 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-09-02T18:03:00.638Z",
+  "builtAt": "2026-09-03T16:39:37.425Z",
   "artifact": {
     "filename": "process-guardian",
-    "sha256": "d9159fe44b7eab5ce46ebdc4da5c4bc90f090d211ed52856ffa1d5bff362e430",
-    "size": 356784
+    "sha256": "7524bf568992517f50ed53196c861c5edeba0d7275633bb4735ab45bd5963a28",
+    "size": 356368
   },
   "provenance": {
     "language": "Rust",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-02T18:03:04.391Z",
+  "builtAt": "2026-09-03T16:39:27.399Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "ee8a00eaaf79c707459bbbfb52518e9739314967049fbe5fa625f36ce33db9ee",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-02T18:03:45.052Z",
+  "builtAt": "2026-09-03T16:40:47.022Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "261e3a4a54d967849c35479b09cac3d4dc2e20c3e5099050380137539b7b19c2",
+    "sha256": "2fe463dcdeaedfbc9df817ac61e973f27500e9527d05bd781553da89d6767926",
     "size": 177664
   },
   "provenance": {

package/dist/product-identity.d.ts

@@ -1,10 +1,10 @@
-declare const ENVIRONMENT_KEYS: readonly ["certificationTarball", "configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "fixture", "fixtureInput", "fixtureToken", "inputAcknowledgement", "internalPackaging", "launchProfile", "nativePi", "paneId", "piParityIntentionalMutation", "piPortRoot", "piSourceLedgerPath", "piSourceScanRoot", "probeTrace", "processGuardianPath", "profileHome", "protocolVersion", "releaseDigest", "releaseId", "releaseRoot", "releaseRunnerLabel", "runtimeDir", "structuredFlowLimits", "terminalArgumentsJson", "terminalExecutable", "terminalSessionId"];
+declare const ENVIRONMENT_KEYS: readonly ["certificationTarball", "configDir", "dataDir", "databasePath", "developmentInstanceId", "developmentRoot", "endpoint", "fixture", "fixtureInput", "fixtureToken", "inputAcknowledgement", "immutableWarmup", "internalPackaging", "launchProfile", "nativePi", "paneId", "piParityIntentionalMutation", "piPortRoot", "piSourceLedgerPath", "piSourceScanRoot", "probeTrace", "processGuardianPath", "profileHome", "protocolVersion", "releaseDigest", "releaseId", "releaseLayers", "releaseRoot", "releaseRunnerLabel", "runtimeDir", "structuredFlowLimits", "startupTrace", "terminalArgumentsJson", "terminalExecutable", "terminalSessionId"];
 declare const FILESYSTEM_KEYS: readonly ["slug", "windowsDirectory", "unixDirectory", "temporaryPrefix"];
 declare const STATE_KEYS: readonly ["windowsControlDirectory", "unixControlDirectory", "developmentDirectory", "piAgentProfile", "piVanillaProfile"];
 declare const ENDPOINT_KEYS: readonly ["windowsPipeStem", "unixSocketFilename", "metadataFilename", "supervisorLogFilename", "databaseFilename"];
 declare const MANIFEST_KEYS: readonly ["releaseFilename", "packageFilename"];
 declare const PROTOCOL_KEYS: readonly ["namespace", "controlEnvelope", "supervisorSchema", "nativeHostSchema", "structuredAgentSchema", "controlStoreSchema", "releaseCohortSchema", "updateJournalSchema"];
-declare const EVIDENCE_KEYS: readonly ["nativeSpikeSchema", "terminalProvenanceSchema", "terminalProofSchema", "stableReleaseSchema", "previewReleaseSchema", "releaseCertificationSchema", "previewPlatformVerdictSchema", "piSourceLedgerSchema", "piComponentParitySchema", "piEventFrameParitySchema"];
+declare const EVIDENCE_KEYS: readonly ["nativeSpikeSchema", "terminalProvenanceSchema", "terminalProofSchema", "stableReleaseSchema", "previewReleaseSchema", "releaseCertificationSchema", "previewPlatformVerdictSchema", "piSourceLedgerSchema", "piComponentParitySchema", "piEventFrameParitySchema", "startupTraceSchema", "dependencyLayerSchema", "dependencyLayerCertificationSchema", "runtimePayloadSchema"];
 declare const ARTIFACT_KEYS: readonly ["cliEntry", "supervisorEntry", "guardianEntry", "uiEntry", "nativeExecutable", "nativeCrate", "processGuardianExecutable", "releaseTarballStem", "diagnosticStem"];
 type StringRecord<Keys extends readonly string[]> = {
     readonly [Key in Keys[number]]: string;