@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

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

@@ -0,0 +1,49 @@
+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" | "layer-write" | "layer-reuse" | "verification-read";
+export interface ReleaseContentOperationEvent {
+    readonly operation: ReleaseContentOperation;
+    readonly path: string;
+    readonly bytes: number;
+}
+export interface MaterializeReleaseOptions {
+    readonly onProgress?: (progress: {
+        readonly phase: "copying";
+        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>;
+}
+export interface VerifyMaterializedReleaseOptions {
+    readonly onOperation?: (event: ReleaseContentOperationEvent) => void;
+}
+export interface CertifiedReleaseRecord {
+    readonly releaseId: string;
+    readonly releaseRoot: string;
+    readonly packageVersion?: string;
+    readonly contentDigest: string;
+    /** Absent on records written before releases declared a handoff contract. */
+    readonly launchContract?: 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, 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, 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/foundation/release/release-store.js

@@ -0,0 +1,235 @@
+import { createHash, randomUUID } from "node:crypto";
+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, discoverReleasePayload, releaseFileIdentity, resolveWithin, } from "./release.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { assertCurrentLaunchContract, isCurrentLaunchContract, readLaunchContext } from "../launch-context/index.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;
+export async function materializeRelease(packageRoot, dataDir, options = {}) {
+    const payload = await discoverReleasePayload(packageRoot, {
+        onSourceRead: (path, bytes) => options.onOperation?.({ operation: "source-read", path, bytes }),
+    });
+    assertCurrentLaunchContract(payload);
+    const storeRoot = resolve(dataDir, "releases");
+    await mkdir(storeRoot, { recursive: true, mode: 0o700 });
+    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(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(productPaths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
+            const source = resolveWithin(payload.packageRoot, path);
+            const destination = resolveWithin(candidate, path);
+            const metadata = await lstat(source);
+            if (!metadata.isFile() || metadata.isSymbolicLink())
+                throw new Error(`release payload is not a regular file: ${path}`);
+            const cached = payload.cachedFiles.get(path);
+            const bytes = cached ?? await readFile(source);
+            if (!cached)
+                options.onOperation?.({ operation: "source-read", path, bytes: bytes.length });
+            const mode = (metadata.mode & 0o111) !== 0 ? 0o500 : 0o400;
+            if (options.writeCandidateFile)
+                await options.writeCandidateFile(destination, bytes, mode);
+            else {
+                await writeFile(destination, bytes, { flag: "wx", mode });
+                await chmod(destination, mode);
+            }
+            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, layerReferences, payload.launchContract);
+        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 });
+            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
+        }
+        await writeFile(resolve(candidate, RELEASE_MANIFEST_FILENAME), JSON.stringify(identity, null, 2), { mode: 0o400, flag: "wx" });
+        try {
+            await rename(candidate, releaseRoot);
+        }
+        catch (error) {
+            if (!await lstat(releaseRoot).catch(() => null))
+                throw error;
+            await rm(candidate, { recursive: true, force: true });
+            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
+        }
+        return certificationReadyRelease({ ...identity, releaseRoot: await realpath(releaseRoot) });
+    }
+    catch (error) {
+        await rm(candidate, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Consume proof that this exact object was freshly materialized or fully verified in this process. */
+export function consumeMaterializationProof(release) {
+    if (!certificationReady.has(release))
+        return false;
+    certificationReady.delete(release);
+    return true;
+}
+export async function readMaterializedRelease(releaseRoot, selectedStoreRoot) {
+    const canonical = await realpath(releaseRoot);
+    const manifest = JSON.parse(await readFile(resolve(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
+    return certificationReadyRelease(await verifyMaterializedRelease(canonical, manifest, selectedStoreRoot));
+}
+/**
+ * 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 async function readCertifiedReleaseManifest(record, selectedStoreRoot, options = {}) {
+    const canonical = await realpath(record.releaseRoot);
+    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
+        || (record.packageVersion !== undefined && manifest.packageVersion !== record.packageVersion)) {
+        throw new Error(`certified release record differs from manifest for ${canonical}`);
+    }
+    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);
+    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);
+    if (expected && (manifest.releaseId !== expected.releaseId || manifest.contentDigest !== expected.contentDigest)) {
+        throw new Error(`release identity mismatch for ${canonical}`);
+    }
+    if (canonical.split(sep).at(-1) !== manifest.releaseId && !canonical.split(sep).at(-1)?.startsWith(`.candidate-${manifest.releaseId}-`)) {
+        throw new Error(`release directory does not match identity ${manifest.releaseId}`);
+    }
+    await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
+        await verifyFile(canonical, file, options);
+    });
+    const recomputed = createReleaseIdentity(manifest.packageRoot, manifest.packageVersion, manifest.files, manifest.dependencyLayers ?? [], manifest.launchContract).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) {
+    const storeRoot = await realpath(resolve(dataDir, "releases"));
+    assertContained(storeRoot, release.releaseRoot, "release root is outside the selected release store");
+    const selectedRoot = readLaunchContext(process.env, "release").releaseRoot;
+    if (!selectedRoot)
+        throw new Error(PRODUCT_TEXT.diagnostic("persistent process has no immutable release root"));
+    const selected = await realpath(selectedRoot);
+    if (selected !== release.releaseRoot)
+        throw new Error(PRODUCT_TEXT.diagnostic("persistent process selected a different immutable release root"));
+}
+export async function resolveReleaseEntryPoint(release, entryPoint) {
+    const normalized = entryPoint.split("\\").join("/").replace(/^\.\//, "");
+    if (!release.files.some(file => file.path === normalized))
+        throw new Error(`entry point is not in the verified release manifest: ${entryPoint}`);
+    const path = resolveWithin(release.releaseRoot, normalized);
+    const canonical = await realpath(path);
+    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);
+    if (!metadata?.isFile() || metadata.isSymbolicLink())
+        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");
+    if (digest !== file.sha256)
+        throw new Error(`release file digest mismatch: ${file.path}`);
+}
+function certificationReadyRelease(release) {
+    certificationReady.add(release);
+    return release;
+}
+function validateManifest(value) {
+    if (value.launchContract !== undefined && !isCurrentLaunchContract(value)) {
+        throw new Error(PRODUCT_TEXT.diagnostic(`release manifest declares an unsupported launch contract: ${String(value.launchContract)}`));
+    }
+    if (value.packageName !== PRODUCT_PACKAGE_NAME || typeof value.packageVersion !== "string")
+        throw new Error(PRODUCT_TEXT.diagnostic("release manifest metadata is invalid"));
+    if (!/^[a-f0-9]{64}$/.test(value.contentDigest) || !/^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/.test(value.releaseId))
+        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)}`);
+        }
+        if (!Number.isSafeInteger(file.bytes) || file.bytes < 0 || !/^[a-f0-9]{64}$/.test(file.sha256))
+            throw new Error(`invalid release manifest file identity: ${file.path}`);
+    }
+    const expected = createReleaseIdentity(value.packageRoot, value.packageVersion, value.files, value.dependencyLayers ?? [], value.launchContract);
+    if (expected.contentDigest !== value.contentDigest)
+        throw new Error("release manifest content/contract digest mismatch");
+}
+function assertContained(parent, child, message) {
+    const fromParent = relative(parent, child);
+    if (fromParent === "" || (!fromParent.startsWith(`..${sep}`) && fromParent !== ".." && !isAbsolute(fromParent)))
+        return;
+    throw new Error(`${message}: ${child}`);
+}

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

@@ -0,0 +1,43 @@
+import type { DependencyLayerReference } from "./types.js";
+export declare const PRODUCT_PACKAGE_NAME: string;
+export interface ReleaseFileIdentity {
+    readonly path: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly executable: boolean;
+}
+export interface ReleaseIdentity {
+    readonly packageName: typeof PRODUCT_PACKAGE_NAME;
+    readonly packageVersion: string;
+    readonly contentDigest: string;
+    readonly releaseId: string;
+    readonly packageRoot: string;
+    readonly launchContract?: string;
+    readonly files: readonly ReleaseFileIdentity[];
+    /** Absent for legacy full-copy releases. */
+    readonly dependencyLayers?: readonly DependencyLayerReference[];
+}
+export interface DiscoveredReleasePayload {
+    readonly packageRoot: string;
+    readonly packageVersion: string;
+    readonly paths: readonly string[];
+    readonly launchContract?: string;
+    /** Package manifests already read to discover the dependency closure. */
+    readonly cachedFiles: ReadonlyMap<string, Buffer>;
+}
+export interface DiscoverReleasePayloadOptions {
+    readonly onSourceRead?: (path: string, bytes: number) => void;
+}
+/** Discover the complete payload without reading ordinary file contents. */
+export declare function discoverReleasePayload(packageRoot: string, options?: DiscoverReleasePayloadOptions): Promise<DiscoveredReleasePayload>;
+/**
+ * Derive release execution identity only from installed distribution metadata and
+ * bytes. The version remains display metadata; the digest selects executable
+ * content.
+ */
+export declare function deriveReleaseIdentity(packageRoot: string): Promise<ReleaseIdentity>;
+export declare function createReleaseIdentity(packageRoot: string, packageVersion: string, files: readonly ReleaseFileIdentity[], dependencyLayers?: readonly DependencyLayerReference[], launchContract?: string): 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;
+export declare function packageRootFromModule(moduleUrl: string): string;

package/dist/foundation/release/release.js

@@ -0,0 +1,215 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { mapWithConcurrency } from "./concurrency.js";
+const RELEASE_FILE_IO_CONCURRENCY = 32;
+export const PRODUCT_PACKAGE_NAME = PRODUCT_IDENTITY.packageName;
+/** Discover the complete payload without reading ordinary file contents. */
+export async function discoverReleasePayload(packageRoot, options = {}) {
+    const canonicalRoot = await realpath(packageRoot);
+    const cachedFiles = new Map();
+    const readManifest = async (manifestRoot) => {
+        const manifestPath = resolve(manifestRoot, "package.json");
+        const bytes = await readFile(manifestPath);
+        const path = normalizeRelative(relative(canonicalRoot, manifestPath));
+        cachedFiles.set(path, bytes);
+        options.onSourceRead?.(path, bytes.length);
+        return JSON.parse(bytes.toString("utf8"));
+    };
+    const manifest = await readManifest(canonicalRoot);
+    if (manifest.name !== PRODUCT_PACKAGE_NAME)
+        throw new Error(`unexpected ${PRODUCT_TEXT.displayName} package name: ${String(manifest.name)}`);
+    if (typeof manifest.version !== "string" || manifest.version.length === 0)
+        throw new Error(PRODUCT_TEXT.diagnostic("package metadata has no version"));
+    const roots = distributionRoots(manifest);
+    const paths = new Set(["package.json"]);
+    for (const root of roots)
+        await collectFiles(canonicalRoot, resolveWithin(canonicalRoot, root), paths);
+    await collectDependencyClosure(canonicalRoot, canonicalRoot, manifest, paths, new Set(), readManifest);
+    return {
+        packageRoot: canonicalRoot,
+        packageVersion: manifest.version,
+        paths: [...paths].sort(),
+        ...(typeof manifest.privateLaunchContract === "string" ? { launchContract: manifest.privateLaunchContract } : {}),
+        cachedFiles,
+    };
+}
+/**
+ * Derive release execution identity only from installed distribution metadata and
+ * bytes. The version remains display metadata; the digest selects executable
+ * content.
+ */
+export async function deriveReleaseIdentity(packageRoot) {
+    const payload = await discoverReleasePayload(packageRoot);
+    const files = await mapWithConcurrency(payload.paths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
+        const absolute = resolveWithin(payload.packageRoot, path);
+        const metadata = await lstat(absolute);
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            throw new Error(`release payload is not a regular file: ${path}`);
+        const bytes = payload.cachedFiles.get(path) ?? await readFile(absolute);
+        return releaseFileIdentity(path, bytes, (metadata.mode & 0o111) !== 0);
+    });
+    return createReleaseIdentity(payload.packageRoot, payload.packageVersion, files, [], payload.launchContract);
+}
+export function createReleaseIdentity(packageRoot, packageVersion, files, dependencyLayers = [], launchContract) {
+    const fileDigest = digestManifestFiles(files);
+    const productDigest = launchContract === undefined ? fileDigest
+        : createHash("sha256").update(`launch-contract\0${launchContract}\0${fileDigest}`).digest("hex");
+    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,
+        contentDigest,
+        releaseId: `${packageVersion}-${contentDigest.slice(0, 20)}`,
+        packageRoot,
+        ...(launchContract === undefined ? {} : { launchContract }),
+        files: [...files].sort(compareReleaseFiles),
+        ...(dependencyLayers.length === 0 ? {} : { dependencyLayers: [...dependencyLayers] }),
+    };
+}
+export function releaseFileIdentity(path, bytes, executable) {
+    return {
+        path: normalizeRelative(path),
+        bytes: bytes.length,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        executable,
+    };
+}
+export function digestManifestFiles(files) {
+    const digest = createHash("sha256");
+    for (const file of [...files].sort(compareReleaseFiles)) {
+        digest.update(`${file.path}\0${file.bytes}\0${file.sha256}\0${file.executable ? 1 : 0}\n`);
+    }
+    return digest.digest("hex");
+}
+export function resolveWithin(root, candidate) {
+    if (candidate.includes("\0"))
+        throw new Error("release path contains a null byte");
+    const absolute = resolve(root, candidate);
+    const fromRoot = relative(root, absolute);
+    if (fromRoot === "" || (!isAbsolute(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`)))
+        return absolute;
+    throw new Error(`release path escapes selected root: ${candidate}`);
+}
+function distributionRoots(manifest) {
+    if (!Array.isArray(manifest.files))
+        throw new Error(PRODUCT_TEXT.diagnostic("package metadata has no distribution files list"));
+    const roots = manifest.files.map(value => {
+        if (typeof value !== "string" || value.length === 0)
+            throw new Error(PRODUCT_TEXT.diagnostic("distribution file entry is invalid"));
+        const normalized = normalizeRelative(value);
+        if (normalized === "package.json")
+            return normalized;
+        if (isAbsolute(value) || normalized === ".." || normalized.startsWith("../"))
+            throw new Error(PRODUCT_TEXT.diagnostic(`distribution path escapes package root: ${value}`));
+        return normalized;
+    });
+    return [...new Set(roots)];
+}
+async function collectFiles(root, path, output, skipNodeModules = false) {
+    const metadata = await lstat(path);
+    const relativePath = normalizeRelative(relative(root, path));
+    if (metadata.isSymbolicLink())
+        throw new Error(`release payload contains a symbolic link: ${relativePath}`);
+    if (metadata.isFile()) {
+        output.add(relativePath);
+        return;
+    }
+    if (!metadata.isDirectory())
+        throw new Error(`release payload contains an unsupported entry: ${relativePath}`);
+    for (const entry of await readdir(path)) {
+        if (entry === ".bin" || (skipNodeModules && entry === "node_modules"))
+            continue;
+        await collectFiles(root, resolve(path, entry), output, skipNodeModules);
+    }
+}
+async function collectDependencyClosure(root, requesterRoot, manifest, output, visited, readManifest) {
+    const required = dependencyNames(manifest.dependencies);
+    const optional = new Set(dependencyNames(manifest.optionalDependencies));
+    for (const name of [...new Set([...required, ...optional])].sort()) {
+        const packagePath = await findInstalledDependency(root, requesterRoot, name);
+        if (!packagePath) {
+            if (optional.has(name))
+                continue;
+            throw new Error(`installed ${PRODUCT_TEXT.displayName} dependency is missing: ${name}`);
+        }
+        if (visited.has(packagePath))
+            continue;
+        visited.add(packagePath);
+        await collectFiles(root, packagePath, output, true);
+        await collectDependencyClosure(root, packagePath, await readManifest(packagePath), output, visited, readManifest);
+    }
+}
+async function findInstalledDependency(root, requesterRoot, name) {
+    let directory = requesterRoot;
+    while (true) {
+        const candidate = resolve(directory, "node_modules", name);
+        if (await isContained(root, candidate)) {
+            const metadata = await lstat(candidate).catch(() => null);
+            if (metadata?.isDirectory() && !metadata.isSymbolicLink())
+                return candidate;
+            // 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
+            // only when the target is inside this installation, so a link can never
+            // pull bytes in from somewhere else.
+            if (metadata?.isSymbolicLink()) {
+                const target = await realpath(candidate).catch(() => null);
+                if (target !== null && await isContained(root, target)) {
+                    const targetMetadata = await lstat(target).catch(() => null);
+                    if (targetMetadata?.isDirectory())
+                        return target;
+                }
+            }
+        }
+        if (directory === root)
+            return null;
+        const parent = dirname(directory);
+        if (parent === directory || relative(root, parent).startsWith(".."))
+            return null;
+        directory = parent;
+    }
+}
+/** True when `path` sits inside `root`, comparing what each one actually resolves to. */
+async function isContained(root, path) {
+    const within = (from, to) => {
+        const value = relative(from, to);
+        return value !== ".." && !value.startsWith(`..${sep}`) && !isAbsolute(value);
+    };
+    if (within(root, path))
+        return true;
+    const canonicalRoot = await realpath(root).catch(() => null);
+    return canonicalRoot !== null && within(canonicalRoot, path);
+}
+function dependencyNames(value) {
+    if (value === undefined)
+        return [];
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(PRODUCT_TEXT.diagnostic("dependency metadata is invalid"));
+    return Object.keys(value);
+}
+function compareReleaseFiles(left, right) {
+    return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+}
+function normalizeRelative(path) {
+    return path.split(sep).join("/").replace(/^\.\//, "");
+}
+export function packageRootFromModule(moduleUrl) {
+    const url = new URL(moduleUrl);
+    if (url.protocol !== "file:")
+        throw new Error(PRODUCT_TEXT.diagnostic(`module URL must be a file URL: ${moduleUrl}`));
+    let directory = dirname(url.pathname.replace(/^\/(.:)/, "$1"));
+    while (basename(directory) !== "") {
+        if (basename(directory) === "dist")
+            return dirname(directory);
+        directory = dirname(directory);
+    }
+    throw new Error(PRODUCT_TEXT.diagnostic("package root could not be derived from module URL"));
+}

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

@@ -0,0 +1,68 @@
+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 launchContract: string;
+    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 {};