@timurproko/a1 0.1.8-dev.235df0e → 0.1.8-dev.260

package/dist/{src/foundation → foundation}/release/release-store.d.ts

@@ -1,9 +1,10 @@
 import { type ReleaseIdentity } from "./release.js";
+import { type ReadCertifiedDependencyLayerOptions, type RuntimePayloadInventory } from "./dependency-layer.js";
 export declare const RELEASE_MANIFEST_FILENAME: string;
 export interface MaterializedRelease extends ReleaseIdentity {
     readonly releaseRoot: string;
 }
-export type ReleaseContentOperation = "source-read" | "candidate-write" | "verification-read";
+export type ReleaseContentOperation = "source-read" | "candidate-write" | "layer-write" | "layer-reuse" | "verification-read";
 export interface ReleaseContentOperationEvent {
     readonly operation: ReleaseContentOperation;
     readonly path: string;
@@ -15,6 +16,7 @@ export interface MaterializeReleaseOptions {
         readonly fileCount: number;
     }) => void;
     readonly onOperation?: (event: ReleaseContentOperationEvent) => void;
+    readonly onRuntimeInventory?: (inventory: RuntimePayloadInventory) => void;
     /** Test seam for deterministic write-failure coverage. */
     readonly writeCandidateFile?: (path: string, bytes: Uint8Array, mode: number) => Promise<void>;
 }
@@ -27,17 +29,19 @@ export interface CertifiedReleaseRecord {
     readonly packageVersion?: string;
     readonly contentDigest: string;
 }
+/** Process-authority compatibility controls for metadata-only release loading. */
+export type ReadCertifiedReleaseManifestOptions = ReadCertifiedDependencyLayerOptions;
 export declare function materializeRelease(packageRoot: string, dataDir: string, options?: MaterializeReleaseOptions): Promise<MaterializedRelease>;
 /** Consume proof that this exact object was freshly materialized or fully verified in this process. */
 export declare function consumeMaterializationProof(release: MaterializedRelease): boolean;
-export declare function readMaterializedRelease(releaseRoot: string): Promise<MaterializedRelease>;
+export declare function readMaterializedRelease(releaseRoot: string, selectedStoreRoot?: string): Promise<MaterializedRelease>;
 /**
  * Load metadata for a release whose bytes were already certified by the
  * current parent process or an authenticated live supervisor. Callers must
  * establish one of those preconditions; untrusted releases require full
  * verification.
  */
-export declare function readCertifiedReleaseManifest(record: CertifiedReleaseRecord, selectedStoreRoot: string): Promise<MaterializedRelease>;
+export declare function readCertifiedReleaseManifest(record: CertifiedReleaseRecord, selectedStoreRoot: string, options?: ReadCertifiedReleaseManifestOptions): Promise<MaterializedRelease>;
 export declare function verifyMaterializedRelease(releaseRoot: string, expected?: ReleaseIdentity, selectedStoreRoot?: string, options?: VerifyMaterializedReleaseOptions): Promise<MaterializedRelease>;
 export declare function assertImmutableExecutionRoot(release: MaterializedRelease, dataDir: string): Promise<void>;
 export declare function resolveReleaseEntryPoint(release: MaterializedRelease, entryPoint: string): Promise<string>;

package/dist/{src/foundation → foundation}/release/release-store.js

@@ -1,9 +1,11 @@
 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 { assertImmutableFileMode } from "./immutable-platform.js";
+import { dependencyReference, materializeDependencyLayer, readCertifiedDependencyLayer, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 const RELEASE_FILE_IO_CONCURRENCY = 32;
 const certificationReady = new WeakSet();
 export const RELEASE_MANIFEST_FILENAME = PRODUCT_IDENTITY.manifest.releaseFilename;
@@ -13,15 +15,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 +60,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 });
@@ -71,10 +95,10 @@ export function consumeMaterializationProof(release) {
     certificationReady.delete(release);
     return true;
 }
-export async function readMaterializedRelease(releaseRoot) {
+export async function readMaterializedRelease(releaseRoot, selectedStoreRoot) {
     const canonical = await realpath(releaseRoot);
     const manifest = JSON.parse(await readFile(resolve(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
-    return await verifyMaterializedRelease(canonical, manifest);
+    return certificationReadyRelease(await verifyMaterializedRelease(canonical, manifest, selectedStoreRoot));
 }
 /**
  * Load metadata for a release whose bytes were already certified by the
@@ -82,9 +106,10 @@ export async function readMaterializedRelease(releaseRoot) {
  * establish one of those preconditions; untrusted releases require full
  * verification.
  */
-export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
+export async function readCertifiedReleaseManifest(record, selectedStoreRoot, options = {}) {
     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 +118,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, {}, options);
     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 +137,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 +162,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 = {}, certificationOptions = {}) {
+    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, certificationOptions);
+    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);
@@ -142,6 +188,7 @@ async function verifyFile(root, file, options) {
         throw new Error(`release candidate is incomplete: ${file.path}`);
     if (metadata.size !== file.bytes)
         throw new Error(`release file size mismatch: ${file.path}`);
+    assertImmutableFileMode(metadata, path);
     const bytes = await readFile(path);
     options.onOperation?.({ operation: "verification-read", path: file.path, bytes: bytes.length });
     const digest = createHash("sha256").update(bytes).digest("hex");
@@ -159,6 +206,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/{src/foundation → 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/{src/foundation → 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) {
@@ -143,7 +150,7 @@ async function findInstalledDependency(root, requesterRoot, name) {
             const metadata = await lstat(candidate).catch(() => null);
             if (metadata?.isDirectory() && !metadata.isSymbolicLink())
                 return candidate;
-            // A linked dependency directory is how this installation unifies a module
+            // Invariant: a linked dependency directory is how this installation unifies a module
             // that would otherwise be present twice, and the link is made by A1 itself
             // at install and at every launch. Follow it to the directory it names and
             // collect from there, so the payload still reads only real files — but

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

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

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

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

package/dist/{src/foundation → foundation}/release/update-transaction.d.ts

@@ -14,6 +14,7 @@ export interface UpdateTransaction {
     readonly startedAt: string;
     readonly updatedAt: string;
 }
+/** Persists the durable update journal and permits only validated forward transaction phases. */
 export declare class UpdateTransactionStore {
     #private;
     readonly path: string;

package/dist/{src/foundation → foundation}/release/update-transaction.js

@@ -3,6 +3,7 @@ import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export const UPDATE_JOURNAL_SCHEMA = PRODUCT_IDENTITY.protocol.updateJournalSchema;
+/** Persists the durable update journal and permits only validated forward transaction phases. */
 export class UpdateTransactionStore {
     path;
     constructor(dataDir) { this.path = resolve(dataDir, "update-transaction.json"); }

package/dist/{src/foundation → 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,12 +28,18 @@ 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 {
     packageRoot: string;
     channel?: UpdateChannel;
-    /** A specific preview to install, named by its commit or its full version. */
+    /** A specific preview to install, named by its development number or full version. */
     target?: string;
     environment?: NodeJS.ProcessEnv;
     fileSystem?: UpdateFileSystem;
@@ -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;
@@ -77,6 +85,14 @@ export interface UpdateTransactionJournal {
     clearCompleted(): Promise<void>;
 }
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
+export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end-session";
+/**
+ * What an update does about the owner it found. A cohort running from retained immutable
+ * content keeps its work: the installation replaces files it does not read, and it listens on
+ * its own endpoint. A cohort running from the mutable installation is the one exception,
+ * because that installation is exactly what is about to be replaced under it.
+ */
+export declare function planUpdateOwnership(ownership: "live-verified" | "dead", runsFromRetainedRelease: boolean): UpdateOwnershipAction;
 export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
 export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
 export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;