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

package/bin/cli.js

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 
+const commandStartedAtMs = performance.timeOrigin + performance.now();
 const packageRoot = new URL("..", import.meta.url);
+const startup = await import("../dist/foundation/startup/index.js");
+const startupProfile = process.argv[2] === "pi" ? "pi" : "a1";
+startup.initializeStartupTrace(process.env, startupProfile, commandStartedAtMs);
+startup.enableEnvironmentCompileCache(process.env);
+await startup.markStartupPhase(process.env, "command-invoked");
 const { fileURLToPath } = await import("node:url");
 const { readFile } = await import("node:fs/promises");
 const { cliCapabilities, dispatchCli } = await import("../dist/cli/index.js");

package/bin/guardian.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 
+const startup = await import("../dist/foundation/startup/index.js");
+startup.enableEnvironmentCompileCache(process.env);
+await startup.markStartupPhase(process.env, "guardian-start");
 const { fileURLToPath } = await import("node:url");
 const { resolve } = await import("node:path");
 const { runLaunchGuardian } = await import("../dist/foundation/launch-guardian/index.js");

package/bin/release-cleanup.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runReleaseCleanupWorker } = await import("../dist/foundation/release/index.js");
+
+runReleaseCleanupWorker().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/bin/ui.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 
+const startup = await import("../dist/foundation/startup/index.js");
+startup.enableEnvironmentCompileCache(process.env);
+await startup.markStartupPhase(process.env, "ui-entry");
 const { assertSinglePiTuiModuleAtLaunch } = await import("./module-identity.js");
 const { fileURLToPath } = await import("node:url");
 
@@ -27,6 +30,7 @@ runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
       import("../dist/features/owned-ui/index.js"),
       import("../dist/composition/index.js"),
     ]);
+    await startup.markStartupPhase(process.env, "ui-modules-loaded");
     const { application, settings } = await composeOwnedUi({
       cwd: process.cwd(),
       profileId,

package/bin/warmup.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+const startup = await import("../dist/foundation/startup/index.js");
+startup.assertImmutableWarmupEnvironment(process.env);
+startup.enableEnvironmentCompileCache(process.env);
+
+// Security: this entry imports but never composes, so it creates no terminal, profile/session
+// path, trust callback, executable resource loader, extension runner, or network client.
+const [composition, engine, components, runtime] = await Promise.all([
+  import("../dist/composition/index.js"),
+  import("../dist/integrations/pi/engine/index.js"),
+  import("../dist/integrations/pi/components/index.js"),
+  import("../dist/integrations/pi/tui-runtime/index.js"),
+]);
+if (typeof composition.composeOwnedUi !== "function" || typeof engine.createPiEngineAdapter !== "function"
+  || typeof components.applyConfiguredPiTheme !== "function" || typeof runtime.createPiTerminalBridge !== "function") {
+  throw new Error("immutable startup graph is incomplete");
+}

package/dist/features/owned-ui/run.js

@@ -1,3 +1,4 @@
+import { markStartupPhase } from "../../foundation/startup/index.js";
 export async function runOwnedUi(options) {
     const { application, settings } = options;
     try {
@@ -5,6 +6,7 @@ export async function runOwnedUi(options) {
             await settings.load();
         application.start();
         await application.flush();
+        await markStartupPhase(process.env, "first-input-ready-render");
         if (!application.disposed)
             await application.waitUntilStopped();
         return 0;

package/dist/foundation/launch-guardian/main.js

@@ -5,6 +5,7 @@ import { assertLaunchProfileId } from "../lifecycle/index.js";
 import { closeVerifiedContainment, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
 import { SupervisorClient } from "../protocol/index.js";
 import { resolveCohortEndpoint, resolveProductPaths } from "../supervision/index.js";
+import { markStartupPhase } from "../startup/index.js";
 export async function runLaunchGuardian(options) {
     assertLaunchProfileId(options.profileId);
     const environment = { ...(options.environment ?? process.env) };
@@ -24,6 +25,7 @@ export async function runLaunchGuardian(options) {
         ? resolveCohortEndpoint(paths, releaseId, environment).endpoint
         : paths.endpoint;
     await client.connect(endpoint);
+    await markStartupPhase(environment, "guardian-connected");
     const containment = options.containment ?? new NativeGuardianContainment(instanceId, helperPath, resolve(paths.runtimeDir, "launch-instances", `${instanceId}.ready.json`));
     const stop = stopRequests(client, instanceId);
     let rootIdentity = null;

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

@@ -1,6 +1,6 @@
 import { type OwnershipProbe } from "./cohort-selection.js";
 import { type SupervisorEndpointMetadata } from "./cohort-state.js";
-import { type LaunchProfileId } from "../lifecycle/index.js";
+import { resolveProductPaths, type LaunchProfileId } from "../lifecycle/index.js";
 import { cleanupProvenIdleOwner } from "./process-cleanup.js";
 import { type MaterializedRelease, type VerifyMaterializedReleaseOptions } from "./release-store.js";
 export interface BootstrapOptions {
@@ -21,6 +21,8 @@ export interface BootstrapOptions {
      * release is fit.
      */
     readonly releaseIsLaunchable?: (releaseRoot: string) => boolean;
+    /** Test seam for bounded maintenance scheduled after stale endpoint sweeping. */
+    readonly scheduleMaintenance?: (dataDir: string, paths: ReturnType<typeof resolveProductPaths>) => Promise<void>;
 }
 export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
 export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;

package/dist/foundation/release/bootstrap.js

@@ -10,9 +10,12 @@ import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
 import { sweepDeadEndpoints } from "./endpoints.js";
 import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
+import { scheduleReleaseCleanup } from "./release-gc.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { markStartupPhase } from "../startup/index.js";
 export async function runBootstrap(options) {
     const environment = { ...(options.environment ?? process.env) };
+    await markStartupPhase(environment, "bootstrap-start");
     const launchProfileId = options.launchIntent?.profileId ?? "a1";
     assertLaunchProfileId(launchProfileId);
     environment[PRODUCT_IDENTITY.environment.launchProfile] = launchProfileId;
@@ -25,6 +28,10 @@ export async function runBootstrap(options) {
     // can now be several of them. Clearing them first keeps the decision below about what is
     // actually running.
     await sweepDeadEndpoints(paths).catch(() => []);
+    // Performance: reconciliation is serialized by cohort state, but launch never awaits a physical
+    // backlog. The scheduler commits a plan and starts a detached bounded worker.
+    const scheduleMaintenance = options.scheduleMaintenance ?? scheduleReleaseCleanup;
+    void scheduleMaintenance(paths.dataDir, paths).catch(() => { });
     // Protocol: each cohort keeps its own endpoint, so a launch looks for the endpoint of the release it
     // is about to run rather than for the one endpoint the runtime directory used to have.
     const activeReleaseId = state.references.active;
@@ -196,6 +203,7 @@ export async function startSupervisor(release, environment) {
     child.unref();
 }
 async function launchUi(release, environment) {
+    await markStartupPhase(environment, "bootstrap-selected");
     const entry = await resolveReleaseEntryPoint(release, "bin/guardian.js");
     return await new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(process.execPath, [entry], {
@@ -211,6 +219,7 @@ export function releaseEnvironment(environment, release) {
     return {
         ...environment,
         [PRODUCT_IDENTITY.environment.releaseId]: release.releaseId,
+        [PRODUCT_IDENTITY.environment.releaseLayers]: (release.dependencyLayers ?? []).map(layer => layer.layerId).join(","),
         [PRODUCT_IDENTITY.environment.releaseRoot]: release.releaseRoot,
         [PRODUCT_IDENTITY.environment.releaseDigest]: release.contentDigest,
     };

package/dist/foundation/release/cohort-state.d.ts

@@ -18,11 +18,41 @@ export interface ReleaseReferences {
     readonly rollback: string | null;
     readonly retention: readonly string[];
 }
+export type ExternalReleaseHoldAuthority = "agent" | "migration";
+/** A current hold supplied by an authority that must participate in every reconciliation. */
+export interface ExternalReleaseHold {
+    readonly authority: ExternalReleaseHoldAuthority;
+    readonly releaseId: string;
+}
+export interface ActiveReleaseTransactionReference {
+    readonly status: "active" | "completed" | "rolled-back" | "failed";
+    readonly priorActiveReleaseId: string | null;
+}
+export type ReleaseCleanupStage = "detached" | "trash";
+export interface ReleaseCleanupDisposition {
+    readonly release: ReleaseRecord;
+    readonly stage: ReleaseCleanupStage;
+    readonly trashPath: string | null;
+    readonly attempts: number;
+    readonly lastAttemptAt: string | null;
+    readonly lastError: string | null;
+}
+export interface ReleaseCleanupDiagnostic {
+    readonly releaseId: string;
+    readonly stage: string;
+    readonly attemptedAt: string;
+    readonly error: string;
+}
+export interface ReleaseCleanupState {
+    readonly pending: Readonly<Record<string, ReleaseCleanupDisposition>>;
+    readonly diagnostics: readonly ReleaseCleanupDiagnostic[];
+}
 export interface CohortState {
     readonly schema: typeof RELEASE_COHORT_SCHEMA;
     readonly revision: number;
     readonly releases: Readonly<Record<string, ReleaseRecord>>;
     readonly references: ReleaseReferences;
+    readonly cleanup: ReleaseCleanupState;
     readonly activation: {
         readonly state: "idle" | "pending" | "draining" | "blocked" | "failed";
         readonly reason: string | null;
@@ -54,18 +84,48 @@ export interface SupervisorEndpointMetadata {
     readonly optionalFeatures: readonly string[];
     readonly contractDigest: string;
 }
+export interface ProtectedReleaseInputs {
+    readonly liveReleaseIds?: readonly string[];
+    readonly externalHolds?: readonly ExternalReleaseHold[];
+    readonly transaction?: ActiveReleaseTransactionReference | null;
+}
+export interface ProtectedReleasePlan {
+    readonly protectedReleaseIds: readonly string[];
+    readonly retainedReleaseIds: readonly string[];
+    readonly collectibleReleaseIds: readonly string[];
+}
+export interface OrphanReleaseDisposition {
+    readonly release: ReleaseRecord;
+    readonly stage: ReleaseCleanupStage;
+    readonly trashPath?: string | null;
+}
+export interface ReleaseRetentionReconciliation {
+    readonly state: CohortState;
+    readonly plan: ProtectedReleasePlan;
+    readonly detachedReleaseIds: readonly string[];
+}
+/**
+ * Derive protection exclusively from current selectors and ownership authorities.
+ * The historical retention snapshot is deliberately not an input to this plan.
+ */
+export declare function planProtectedReleases(state: CohortState, inputs?: ProtectedReleaseInputs): ProtectedReleasePlan;
 /** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
 export declare class CohortStateStore {
     readonly path: string;
     constructor(dataDir: string);
     read(): Promise<CohortState>;
-    update(operation: (current: CohortState) => CohortState): Promise<CohortState>;
+    update(operation: (current: CohortState) => CohortState | Promise<CohortState>): Promise<CohortState>;
     recordCandidate(release: MaterializedRelease): Promise<CohortState>;
     approve(releaseId: string, diagnosticsPath: string): Promise<CohortState>;
     activate(releaseId: string): Promise<CohortState>;
     blockPending(reason: string, blockerGenerationIds: readonly string[]): Promise<CohortState>;
     rollback(ownershipReleased: boolean): Promise<CohortState>;
     setRetention(releaseIds: readonly string[]): Promise<CohortState>;
+    /** Atomically replace legacy retention history and detach every currently collectible record. */
+    reconcileRetention(resolveInputs: (current: CohortState) => ProtectedReleaseInputs | Promise<ProtectedReleaseInputs>, orphans?: readonly OrphanReleaseDisposition[]): Promise<ReleaseRetentionReconciliation>;
+    markCleanupTrash(releaseId: string, trashPath: string): Promise<CohortState>;
+    recordCleanupFailure(releaseId: string, stage: string, error: unknown): Promise<CohortState>;
+    completeCleanup(releaseId: string): Promise<CohortState>;
     removeUnreferencedRelease(releaseId: string, externalReferences: readonly string[]): Promise<CohortState>;
 }
 export declare function emptyState(): CohortState;

package/dist/foundation/release/cohort-state.js

@@ -1,8 +1,42 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 export const RELEASE_COHORT_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
+const RELEASE_ID_PATTERN = /^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/;
+/**
+ * Derive protection exclusively from current selectors and ownership authorities.
+ * The historical retention snapshot is deliberately not an input to this plan.
+ */
+export function planProtectedReleases(state, inputs = {}) {
+    const holds = inputs.externalHolds ?? [];
+    for (const hold of holds) {
+        if (hold.authority !== "agent" && hold.authority !== "migration")
+            throw new Error(`unknown release hold authority: ${String(hold.authority)}`);
+        if (!state.releases[hold.releaseId] && !state.cleanup.pending[hold.releaseId]) {
+            throw new Error(`external ${hold.authority} hold names unknown release ${hold.releaseId}`);
+        }
+    }
+    const protectedIds = new Set();
+    for (const id of [state.references.active, state.references.pending, state.references.approved, state.references.rollback]) {
+        if (id !== null)
+            protectedIds.add(id);
+    }
+    for (const id of inputs.liveReleaseIds ?? [])
+        protectedIds.add(id);
+    for (const hold of holds)
+        protectedIds.add(hold.releaseId);
+    if (inputs.transaction?.status === "active" && inputs.transaction.priorActiveReleaseId !== null) {
+        protectedIds.add(inputs.transaction.priorActiveReleaseId);
+    }
+    const protectedReleaseIds = [...protectedIds].sort();
+    const known = Object.keys(state.releases).sort();
+    return {
+        protectedReleaseIds,
+        retainedReleaseIds: known.filter(id => protectedIds.has(id)),
+        collectibleReleaseIds: known.filter(id => !protectedIds.has(id)),
+    };
+}
 /** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
 export class CohortStateStore {
     path;
@@ -11,7 +45,7 @@ export class CohortStateStore {
     }
     async read() {
         try {
-            const state = JSON.parse(await readFile(this.path, "utf8"));
+            const state = normalizeState(JSON.parse(await readFile(this.path, "utf8")));
             validateState(state);
             return state;
         }
@@ -27,7 +61,7 @@ export class CohortStateStore {
         const lock = await acquireLock(lockPath);
         try {
             const current = await this.read();
-            const next = operation(current);
+            const next = await operation(current);
             validateTransition(current, next);
             const committed = { ...next, revision: current.revision + 1 };
             const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
@@ -66,7 +100,6 @@ export class CohortStateStore {
                 references: {
                     ...current.references,
                     pending: current.references.active === release.releaseId ? current.references.pending : release.releaseId,
-                    retention: unique([...current.references.retention, release.releaseId]),
                 },
                 activation: activation("pending", "candidate awaits certification and safe activation"),
             };
@@ -91,11 +124,11 @@ export class CohortStateStore {
             return {
                 ...current,
                 references: {
+                    ...current.references,
                     active: releaseId,
                     pending: null,
                     approved: releaseId,
                     rollback: prior && prior !== releaseId ? prior : current.references.rollback,
-                    retention: unique([...current.references.retention, releaseId, ...(prior ? [prior] : [])]),
                 },
                 activation: activation("idle", null),
             };
@@ -122,7 +155,6 @@ export class CohortStateStore {
                     pending: null,
                     approved: rollbackId,
                     rollback: current.references.active,
-                    retention: unique([...current.references.retention, rollbackId, ...(current.references.active ? [current.references.active] : [])]),
                 },
                 activation: activation("idle", null),
             };
@@ -135,9 +167,74 @@ export class CohortStateStore {
             return { ...current, references: { ...current.references, retention: unique(releaseIds) } };
         });
     }
+    /** Atomically replace legacy retention history and detach every currently collectible record. */
+    async reconcileRetention(resolveInputs, orphans = []) {
+        let plan = null;
+        let detachedReleaseIds = [];
+        const state = await this.update(async (current) => {
+            const inputs = await resolveInputs(current);
+            plan = planProtectedReleases(current, inputs);
+            const nextReleases = { ...current.releases };
+            const pending = { ...current.cleanup.pending };
+            for (const releaseId of plan.collectibleReleaseIds) {
+                const release = nextReleases[releaseId];
+                pending[releaseId] ??= cleanupDisposition(release, "detached", null);
+                delete nextReleases[releaseId];
+            }
+            for (const orphan of orphans) {
+                const releaseId = orphan.release.releaseId;
+                if (nextReleases[releaseId] || pending[releaseId] || plan.protectedReleaseIds.includes(releaseId))
+                    continue;
+                pending[releaseId] = cleanupDisposition(orphan.release, orphan.stage, orphan.trashPath ?? null);
+            }
+            detachedReleaseIds = plan.collectibleReleaseIds;
+            return {
+                ...current,
+                releases: nextReleases,
+                references: { ...current.references, retention: plan.retainedReleaseIds },
+                cleanup: { ...current.cleanup, pending },
+            };
+        });
+        if (plan === null)
+            throw new Error("release retention reconciliation did not produce a plan");
+        return { state, plan, detachedReleaseIds };
+    }
+    async markCleanupTrash(releaseId, trashPath) {
+        return await this.update(current => {
+            const disposition = current.cleanup.pending[releaseId];
+            if (!disposition)
+                throw new Error(`release ${releaseId} has no cleanup disposition`);
+            return replaceCleanup(current, releaseId, { ...disposition, stage: "trash", trashPath, lastError: null });
+        });
+    }
+    async recordCleanupFailure(releaseId, stage, error) {
+        return await this.update(current => {
+            const attemptedAt = new Date().toISOString();
+            const message = boundedError(error);
+            const disposition = current.cleanup.pending[releaseId];
+            const pending = disposition ? {
+                ...current.cleanup.pending,
+                [releaseId]: { ...disposition, attempts: disposition.attempts + 1, lastAttemptAt: attemptedAt, lastError: message },
+            } : current.cleanup.pending;
+            return {
+                ...current,
+                cleanup: {
+                    pending,
+                    diagnostics: [...current.cleanup.diagnostics, { releaseId, stage, attemptedAt, error: message }].slice(-64),
+                },
+            };
+        });
+    }
+    async completeCleanup(releaseId) {
+        return await this.update(current => {
+            const pending = { ...current.cleanup.pending };
+            delete pending[releaseId];
+            return { ...current, cleanup: { ...current.cleanup, pending } };
+        });
+    }
     async removeUnreferencedRelease(releaseId, externalReferences) {
         return await this.update(current => {
-            requiredRelease(current, releaseId);
+            const release = requiredRelease(current, releaseId);
             const protectedIds = new Set([
                 current.references.active,
                 current.references.pending,
@@ -150,7 +247,14 @@ export class CohortStateStore {
                 throw new Error(`release ${releaseId} is still referenced and cannot be collected`);
             const releases = { ...current.releases };
             delete releases[releaseId];
-            return { ...current, releases };
+            return {
+                ...current,
+                releases,
+                cleanup: {
+                    ...current.cleanup,
+                    pending: { ...current.cleanup.pending, [releaseId]: cleanupDisposition(release, "detached", null) },
+                },
+            };
         });
     }
 }
@@ -160,9 +264,16 @@ export function emptyState() {
         revision: 0,
         releases: {},
         references: { active: null, pending: null, approved: null, rollback: null, retention: [] },
+        cleanup: { pending: {}, diagnostics: [] },
         activation: activation("idle", null),
     };
 }
+function cleanupDisposition(release, stage, trashPath) {
+    return { release, stage, trashPath, attempts: 0, lastAttemptAt: null, lastError: null };
+}
+function replaceCleanup(current, releaseId, disposition) {
+    return { ...current, cleanup: { ...current.cleanup, pending: { ...current.cleanup.pending, [releaseId]: disposition } } };
+}
 function activation(state, reason) {
     return { state, reason, blockerGenerationIds: [], updatedAt: new Date().toISOString() };
 }
@@ -177,22 +288,89 @@ async function acquireLock(path) {
     const deadline = Date.now() + 5_000;
     while (true) {
         try {
-            return await open(path, "wx", 0o600);
+            const lock = await open(path, "wx", 0o600);
+            await lock.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+            await lock.sync();
+            return lock;
         }
         catch (error) {
-            if (!(error instanceof Error && "code" in error && error.code === "EEXIST") || Date.now() >= deadline)
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+            if (await reclaimAbandonedLock(path))
+                continue;
+            if (Date.now() >= deadline)
                 throw error;
             await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
         }
     }
 }
+async function reclaimAbandonedLock(path) {
+    let abandoned = false;
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (typeof value.pid === "number") {
+            try {
+                process.kill(value.pid, 0);
+            }
+            catch (error) {
+                abandoned = !(error instanceof Error && "code" in error && error.code === "EPERM");
+            }
+        }
+    }
+    catch {
+        const metadata = await stat(path).catch(() => null);
+        abandoned = metadata !== null && Date.now() - metadata.mtimeMs > 10_000;
+    }
+    if (!abandoned)
+        return false;
+    const quarantine = `${path}.abandoned`;
+    const oldQuarantine = await stat(quarantine).catch(() => null);
+    if (oldQuarantine && Date.now() - oldQuarantine.mtimeMs > 10_000)
+        await rm(quarantine, { force: true });
+    try {
+        // Concurrency: the fixed destination lets exactly one waiter claim the stale lock;
+        // another waiter cannot accidentally rename a newly acquired replacement.
+        await rename(path, quarantine);
+        await rm(quarantine, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeState(value) {
+    if (!value || typeof value !== "object")
+        return value;
+    const state = value;
+    return {
+        ...state,
+        cleanup: state.cleanup ?? { pending: {}, diagnostics: [] },
+    };
+}
 function validateState(state) {
-    if (state.schema !== RELEASE_COHORT_SCHEMA || !Number.isSafeInteger(state.revision) || state.revision < 0)
+    if (!state || state.schema !== RELEASE_COHORT_SCHEMA || !Number.isSafeInteger(state.revision) || state.revision < 0
+        || !state.releases || typeof state.releases !== "object" || !state.references || !Array.isArray(state.references.retention)
+        || !state.cleanup || typeof state.cleanup.pending !== "object" || !Array.isArray(state.cleanup.diagnostics)) {
         throw new Error("invalid release cohort state");
+    }
+    for (const [releaseId, release] of Object.entries(state.releases))
+        validateReleaseRecord(releaseId, release);
     for (const reference of [state.references.active, state.references.pending, state.references.approved, state.references.rollback]) {
         if (reference !== null && !state.releases[reference])
             throw new Error(`release reference points to an unknown release: ${reference}`);
     }
+    for (const [releaseId, disposition] of Object.entries(state.cleanup.pending)) {
+        validateReleaseRecord(releaseId, disposition.release);
+        if (!["detached", "trash"].includes(disposition.stage))
+            throw new Error(`invalid cleanup disposition for ${releaseId}`);
+    }
+}
+function validateReleaseRecord(releaseId, release) {
+    if (release.releaseId !== releaseId || !RELEASE_ID_PATTERN.test(releaseId) || typeof release.releaseRoot !== "string"
+        || typeof release.packageVersion !== "string" || !/^[a-f0-9]{64}$/.test(release.contentDigest)
+        || !["candidate", "approved", "rejected"].includes(release.approval)) {
+        throw new Error(`invalid release record for ${releaseId}`);
+    }
 }
 function validateTransition(current, next) {
     validateState(next);
@@ -201,3 +379,6 @@ function validateTransition(current, next) {
     if (next.revision !== current.revision)
         throw new Error("release cohort revision is controlled by the state store");
 }
+function boundedError(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ").slice(0, 1_000);
+}

package/dist/foundation/release/dependency-layer.d.ts

@@ -0,0 +1,78 @@
+import { type ReleaseFileIdentity } from "./release.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export declare const DEPENDENCY_LAYER_SCHEMA: string;
+export declare const DEPENDENCY_LAYER_MANIFEST = "dependency-layer-manifest.json";
+export declare const RUNTIME_PAYLOAD_INVENTORY = "dist/runtime-payload-inventory.json";
+export interface RuntimePayloadExclusion {
+    readonly path: string;
+    readonly reason: "type-declaration" | "source-map" | "unreachable-development";
+}
+export interface RuntimePayloadInventory {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.runtimePayloadSchema;
+    readonly includedFiles: number;
+    readonly includedBytes: number;
+    readonly excludedFiles: number;
+    readonly excludedBytes: number;
+    readonly uncertaintyRetainedFiles: number;
+    readonly exclusions: readonly RuntimePayloadExclusion[];
+}
+export interface DependencyLayerIdentity {
+    readonly schema: typeof DEPENDENCY_LAYER_SCHEMA;
+    readonly layerId: string;
+    readonly contentDigest: string;
+    readonly files: readonly ReleaseFileIdentity[];
+    readonly inventory: RuntimePayloadInventory;
+}
+export interface DependencyLayerReference {
+    readonly layerId: string;
+    readonly contentDigest: string;
+    readonly binding: "node_modules";
+}
+export interface MaterializedDependencyLayer extends DependencyLayerIdentity {
+    readonly layerRoot: string;
+    readonly reused: boolean;
+}
+export interface DependencyLayerOperationEvent {
+    readonly operation: "source-read" | "layer-write" | "layer-reuse" | "verification-read";
+    readonly path: string;
+    readonly bytes: number;
+}
+export interface SelectedRuntimePayload {
+    readonly paths: readonly string[];
+    readonly inventory: RuntimePayloadInventory;
+}
+export interface PublishedRuntimeFileClassification {
+    readonly packageName: string;
+    readonly packageVersion: string;
+    readonly packagePath: string;
+    readonly disposition: "include" | "exclude";
+    readonly reason?: RuntimePayloadExclusion["reason"];
+}
+export interface GeneratedRuntimePayload extends SelectedRuntimePayload {
+    readonly classifications: readonly PublishedRuntimeFileClassification[];
+}
+export interface PublishedRuntimePayload extends GeneratedRuntimePayload {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.runtimePayloadSchema;
+    readonly entryPoints: readonly string[];
+    readonly declaredAssets: readonly string[];
+}
+/** Consume topology-independent publication classifications, retaining unknown installed content. */
+export declare function selectPublishedDependencyRuntimePayload(packageRoot: string, paths: readonly string[]): Promise<SelectedRuntimePayload>;
+/** Generate publication evidence from literal module reachability and declared runtime assets. */
+export declare function generateDependencyRuntimePayload(packageRoot: string, allPaths: readonly string[], productPaths: readonly string[]): Promise<GeneratedRuntimePayload>;
+/** Conservatively omit only files Node never executes; uncertain assets remain selected. */
+export declare function selectDependencyRuntimePayload(packageRoot: string, paths: readonly string[]): Promise<SelectedRuntimePayload>;
+export interface MaterializeDependencyLayerOptions {
+    readonly inventory: RuntimePayloadInventory;
+    readonly cachedFiles?: ReadonlyMap<string, Buffer>;
+    readonly onOperation?: (event: DependencyLayerOperationEvent) => void;
+    readonly writeCandidateFile?: (path: string, bytes: Uint8Array, mode: number) => Promise<void>;
+}
+/** Materialize or reuse an exact immutable dependency layer after one source-content pass. */
+export declare function materializeDependencyLayer(packageRoot: string, dataDir: string, paths: readonly string[], options: MaterializeDependencyLayerOptions): Promise<MaterializedDependencyLayer | null>;
+/** Read trusted layer certification and canonical metadata without rereading every payload byte. */
+export declare function readCertifiedDependencyLayer(dataDir: string, layerId: string, expected?: Pick<DependencyLayerIdentity, "layerId" | "contentDigest">): Promise<Omit<MaterializedDependencyLayer, "reused">>;
+/** Fully verify a layer when certification is absent or explicit tamper evidence is required. */
+export declare function verifyDependencyLayer(dataDir: string, reference: DependencyLayerReference, onOperation?: (event: DependencyLayerOperationEvent) => void): Promise<Omit<MaterializedDependencyLayer, "reused">>;
+export declare function dependencyReference(layer: MaterializedDependencyLayer): DependencyLayerReference;
+export declare function dependencyLayerCertificationPath(dataDir: string, layerId: string): string;