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

package/dist/foundation/release/warmup.js

@@ -0,0 +1,47 @@
+import { spawn } from "node:child_process";
+import { resolveReleaseEntryPoint } from "./release-store.js";
+import { releaseEnvironment } from "./bootstrap.js";
+import { launchContractTarget, launchEnvironmentKeys } from "../launch-context/index.js";
+const WARMUP_DIAGNOSTIC_LIMIT = 2_000;
+/** Summarize the child's own failure text without letting an unbounded graph error escape. */
+function warmupDiagnostics(text) {
+    const lines = text.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
+    return lines.length === 0 ? "" : `: ${lines.slice(0, 4).join(" | ").slice(0, WARMUP_DIAGNOSTIC_LIMIT)}`;
+}
+/** Import the exact immutable startup graph in a terminal-free bounded child process. */
+export async function warmMaterializedRelease(release, environment, timeoutMs = 30_000) {
+    const entry = await resolveReleaseEntryPoint(release, "bin/warmup.js");
+    await new Promise((resolvePromise, rejectPromise) => {
+        // Rationale: the child still gets no terminal, but a discarded failure reason leaves an
+        // update reporting only an exit status. Its own diagnostics are read and bounded so the
+        // transaction journal records why the graph could not be imported.
+        const child = spawn(process.execPath, [entry], {
+            env: { ...releaseEnvironment(environment, release), [launchEnvironmentKeys(launchContractTarget(release)).immutableWarmup]: "1" },
+            stdio: ["ignore", "ignore", "pipe"],
+            windowsHide: true,
+        });
+        let diagnostics = "";
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", chunk => { diagnostics = `${diagnostics}${chunk}`.slice(-WARMUP_DIAGNOSTIC_LIMIT); });
+        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}`}${warmupDiagnostics(diagnostics)}`)));
+        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,4 @@
+export { assertStartupPerformanceBudget, evaluateStartupPerformanceBudget, formatStartupBudgetViolation, resolveStartupBudgetMs } from "./startup-budget.js";
+export type { StartupBudgetViolation, StartupPerformanceEvidence } from "./startup-budget.js";
+export { assertImmutableWarmupEnvironment, collectCompileCaches, enableEnvironmentCompileCache, enableStartupCompileCache, initializeStartupTrace, markStartupPhase, parseStartupTrace, startupCompileCachePath, } from "./startup-runtime.js";
+export type { StartupPhase, StartupTraceEvent } from "./startup-runtime.js";

package/dist/foundation/startup/index.js

@@ -0,0 +1,2 @@
+export { assertStartupPerformanceBudget, evaluateStartupPerformanceBudget, formatStartupBudgetViolation, resolveStartupBudgetMs } from "./startup-budget.js";
+export { assertImmutableWarmupEnvironment, collectCompileCaches, enableEnvironmentCompileCache, enableStartupCompileCache, initializeStartupTrace, markStartupPhase, parseStartupTrace, startupCompileCachePath, } from "./startup-runtime.js";

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

@@ -0,0 +1,46 @@
+import type { StartupTraceEvent } from "./startup-runtime.js";
+export interface StartupPerformanceEvidence {
+    readonly profileId: "a1" | "pi";
+    readonly launchKind: "post-update" | "no-live-supervisor" | "warm";
+    readonly events: readonly StartupTraceEvent[];
+    readonly moduleGraph?: {
+        readonly loadedFiles: number;
+        readonly evaluatedBytes: number;
+        readonly groups: readonly {
+            readonly group: string;
+            readonly files: number;
+            readonly evaluatedBytes: number;
+        }[];
+    };
+}
+export interface StartupBudgetViolation {
+    readonly profileId: "a1" | "pi";
+    readonly launchKind: "post-update" | "no-live-supervisor" | "warm";
+    readonly elapsedMs: number;
+    readonly budgetMs: number;
+    readonly dominantPhases: readonly {
+        readonly phase: string;
+        readonly durationMs: number;
+    }[];
+    readonly moduleGraph?: StartupPerformanceEvidence["moduleGraph"];
+}
+/** Resolve the declared budget for one launch kind so measurement and reporting never restate the numbers. */
+export declare function resolveStartupBudgetMs(launchKind: StartupPerformanceEvidence["launchKind"], budgets?: {
+    readonly postUpdateMs: number;
+    readonly noSupervisorMs: number;
+    readonly warmMs: number;
+}): number;
+/** Compare measured startup evidence with its budget without deciding whether the channel enforces it. */
+export declare function evaluateStartupPerformanceBudget(evidence: StartupPerformanceEvidence, budgets?: {
+    readonly postUpdateMs: number;
+    readonly noSupervisorMs: number;
+    readonly warmMs: number;
+}): StartupBudgetViolation | null;
+/** Render one budget violation as the single message used by failures, evidence, and run summaries. */
+export declare function formatStartupBudgetViolation(violation: StartupBudgetViolation): string;
+/** Enforce the startup budget in a channel that fails on an overrun. */
+export declare function assertStartupPerformanceBudget(evidence: StartupPerformanceEvidence, budgets?: {
+    readonly postUpdateMs: number;
+    readonly noSupervisorMs: number;
+    readonly warmMs: number;
+}): void;

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

@@ -0,0 +1,42 @@
+const STARTUP_PERFORMANCE_BUDGETS = { postUpdateMs: 2_000, noSupervisorMs: 2_500, warmMs: 2_000 };
+/** Resolve the declared budget for one launch kind so measurement and reporting never restate the numbers. */
+export function resolveStartupBudgetMs(launchKind, budgets = STARTUP_PERFORMANCE_BUDGETS) {
+    return launchKind === "warm" ? budgets.warmMs : launchKind === "no-live-supervisor" ? budgets.noSupervisorMs : budgets.postUpdateMs;
+}
+/** Compare measured startup evidence with its budget without deciding whether the channel enforces it. */
+export function evaluateStartupPerformanceBudget(evidence, budgets = STARTUP_PERFORMANCE_BUDGETS) {
+    const events = [...evidence.events].sort((left, right) => left.elapsedMs - right.elapsedMs);
+    const ready = events.findLast(event => event.phase === "first-input-ready-render");
+    // Invariant: a launch that never became input-ready is a functional failure rather than a
+    // timing observation, so it throws in every enforcement mode instead of being recorded.
+    if (!ready)
+        throw new Error(`startup budget failed for ${evidence.profileId}: first input-ready render was not recorded`);
+    const budgetMs = resolveStartupBudgetMs(evidence.launchKind, budgets);
+    if (ready.elapsedMs <= budgetMs)
+        return null;
+    const intervals = events.map((event, index) => ({
+        phase: event.phase,
+        durationMs: event.elapsedMs - (events[index - 1]?.elapsedMs ?? 0),
+    })).sort((left, right) => right.durationMs - left.durationMs);
+    return {
+        profileId: evidence.profileId,
+        launchKind: evidence.launchKind,
+        elapsedMs: ready.elapsedMs,
+        budgetMs,
+        dominantPhases: intervals.slice(0, 3),
+        ...evidence.moduleGraph === undefined ? {} : { moduleGraph: evidence.moduleGraph },
+    };
+}
+/** Render one budget violation as the single message used by failures, evidence, and run summaries. */
+export function formatStartupBudgetViolation(violation) {
+    const graph = violation.moduleGraph === undefined ? ""
+        : `; module graph: ${violation.moduleGraph.loadedFiles} files, ${violation.moduleGraph.evaluatedBytes} evaluated bytes (${violation.moduleGraph.groups.map(group => `${group.group} ${group.files}/${group.evaluatedBytes}`).join(", ")})`;
+    const phases = violation.dominantPhases.map(item => `${item.phase} ${Math.round(item.durationMs)}ms`).join(", ");
+    return `startup budget failed for ${violation.profileId} ${violation.launchKind}: ${Math.round(violation.elapsedMs)}ms exceeds ${violation.budgetMs}ms; dominant phases: ${phases}${graph}`;
+}
+/** Enforce the startup budget in a channel that fails on an overrun. */
+export function assertStartupPerformanceBudget(evidence, budgets) {
+    const violation = evaluateStartupPerformanceBudget(evidence, budgets);
+    if (violation)
+        throw new Error(formatStartupBudgetViolation(violation));
+}

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

@@ -0,0 +1,34 @@
+export const STARTUP_DESCRIPTOR = Object.freeze({
+  "schema": "a1-startup-descriptor-v1",
+  "entries": [
+    "dist/features/launch/runtime-selection.js",
+    "dist/foundation/lifecycle/session-selection.js",
+    "dist/features/owned-ui/project-trust-prompt.js",
+    "dist/features/owned-ui/session-fork-prompt.js",
+    "dist/features/owned-ui/run.js",
+    "dist/composition/owned-ui.js"
+  ],
+  "generatedArtifact": {
+    "path": "dist/integrations/pi/startup-public.js",
+    "sha256": "8782a192051008e2d99edaa7abc2eb47bd37a8b8ebda1b7fbd62a74f990e6d48"
+  },
+  "dependencyLayerIdentity": {
+    "source": "A1_RELEASE_LAYERS",
+    "encoding": "ordered-comma-separated-layer-ids-v1"
+  },
+  "compileCacheNamespace": {
+    "strategy": "node-abi-version-and-ordered-layer-sha256-v1"
+  },
+  "identity": "24b9db93df1ea18ef3fc7f669a9f45587750eb50c6de2ed7f57541c26c42ff0e"
+});
+
+export function loadDeclaredStartupGraph() {
+  return Promise.all([
+    import("../../features/launch/runtime-selection.js"),
+    import("../../foundation/lifecycle/session-selection.js"),
+    import("../../features/owned-ui/project-trust-prompt.js"),
+    import("../../features/owned-ui/session-fork-prompt.js"),
+    import("../../features/owned-ui/run.js"),
+    import("../../composition/owned-ui.js"),
+  ]);
+}

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

@@ -0,0 +1,27 @@
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+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 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 parseStartupTrace(source: string): readonly StartupTraceEvent[];

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

@@ -0,0 +1,128 @@
+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";
+import { readLaunchContext } from "../launch-context/index.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 launch = readLaunchContext(environment);
+    const context = {
+        path: resolve(configured),
+        traceId: randomUUID(),
+        startedAtMs,
+        profileId,
+        releaseId: launch.releaseId ?? null,
+        dependencyLayerIds: parseLayerIds(launch.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 elapsedMs = Math.max(0, performance.timeOrigin + performance.now() - context.startedAtMs);
+    const launch = readLaunchContext(environment);
+    const dependencyLayerIds = parseLayerIds(launch.releaseLayers);
+    const event = {
+        schema: PRODUCT_IDENTITY.evidence.startupTraceSchema,
+        traceId: context.traceId,
+        phase,
+        elapsedMs,
+        processId: process.pid,
+        profileId: context.profileId,
+        releaseId: launch.releaseId ?? context.releaseId,
+        dependencyLayerIds: dependencyLayerIds.length > 0 ? dependencyLayerIds : 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) {
+    readLaunchContext(environment, "warmup");
+}
+/** 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)));
+    const launch = readLaunchContext(environment);
+    return enableStartupCompileCache(dataDir, launch.releaseId ?? null, parseLayerIds(launch.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 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/foundation/storage/control-store.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseSync } from "node:sqlite";
+import type { LaunchInstance, LaunchInstanceId, LaunchInstanceOutcome, NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+/** Owns WAL-backed control persistence and reconciles prior-boot records before current use. */
+export declare class ControlStore {
+    #private;
+    readonly database: DatabaseSync;
+    readonly bootNonce: string | null;
+    constructor(path: string, bootNonce?: string | null);
+    migrate(): void;
+    createLaunchInstance(instance: LaunchInstance): void;
+    activateLaunchInstance(instanceId: LaunchInstanceId, ownerClientId: string, rootIdentity: NativeProcessIdentity, containmentIdentity: ProcessContainmentIdentity, activatedAt: string): boolean;
+    beginLaunchInstanceStop(instanceId: LaunchInstanceId, ownerClientId: string, stoppingAt: string): boolean;
+    completeLaunchInstance(instanceId: LaunchInstanceId, ownerClientId: string, terminalState: "completed" | "interrupted", outcome: LaunchInstanceOutcome, completedAt: string): boolean;
+    loadActiveLaunchInstances(): LaunchInstance[];
+    loadLaunchInstance(instanceId: LaunchInstanceId): LaunchInstance | null;
+    reconcilePriorBootLaunchInstances(bootNonce: string, reconciledAt?: string): number;
+    close(): void;
+}