@timurproko/a1 0.1.1-dev.1 → 0.1.1-dev.11

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

@@ -3,8 +3,41 @@ export declare const RELEASE_MANIFEST_FILENAME: string;
 export interface MaterializedRelease extends ReleaseIdentity {
     readonly releaseRoot: string;
 }
-export declare function materializeRelease(packageRoot: string, dataDir: string): Promise<MaterializedRelease>;
+export type ReleaseContentOperation = "source-read" | "candidate-write" | "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;
+    /** 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;
+}
+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 verifyMaterializedRelease(releaseRoot: string, expected?: ReleaseIdentity, 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 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/release/release-store.js

@@ -1,43 +1,101 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, copyFile, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { PRODUCT_PACKAGE_NAME, deriveReleaseIdentity, resolveWithin } from "./release.js";
+import { PRODUCT_PACKAGE_NAME, createReleaseIdentity, digestManifestFiles, discoverReleasePayload, releaseFileIdentity, resolveWithin, } from "./release.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { mapWithConcurrency } from "./concurrency.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) {
-    const identity = await deriveReleaseIdentity(packageRoot);
+export async function materializeRelease(packageRoot, dataDir, options = {}) {
+    const payload = await discoverReleasePayload(packageRoot, {
+        onSourceRead: (path, bytes) => options.onOperation?.({ operation: "source-read", path, bytes }),
+    });
     const storeRoot = resolve(dataDir, "releases");
     await mkdir(storeRoot, { recursive: true, mode: 0o700 });
-    const releaseRoot = resolveWithin(storeRoot, identity.releaseId);
-    const existing = await lstat(releaseRoot).catch(() => null);
-    if (existing)
-        return await verifyMaterializedRelease(releaseRoot, identity);
-    const candidate = resolveWithin(storeRoot, `.candidate-${identity.releaseId}-${randomUUID()}`);
+    options.onProgress?.({ phase: "copying", fileCount: payload.paths.length });
+    const candidate = resolveWithin(storeRoot, `.candidate-${randomUUID()}`);
     await mkdir(candidate, { recursive: false, mode: 0o700 });
     try {
-        for (const file of identity.files) {
-            const source = resolveWithin(identity.packageRoot, file.path);
-            const destination = resolveWithin(candidate, file.path);
-            await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
-            await copyFile(source, destination);
-            await chmod(destination, file.executable ? 0o500 : 0o400);
+        const directories = [...new Set(payload.paths.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 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);
+        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" });
-        await verifyMaterializedRelease(candidate, identity);
-        await rename(candidate, releaseRoot);
-        return await verifyMaterializedRelease(releaseRoot, identity);
+        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) {
     const canonical = await realpath(releaseRoot);
     const manifest = JSON.parse(await readFile(resolve(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
     return await verifyMaterializedRelease(canonical, manifest);
 }
-export async function verifyMaterializedRelease(releaseRoot, expected, 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) {
+    const canonical = await realpath(record.releaseRoot);
+    assertContained(await realpath(selectedStoreRoot), 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}`);
+    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");
@@ -50,15 +108,17 @@ export async function verifyMaterializedRelease(releaseRoot, expected, selectedS
     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}`);
     }
-    for (const file of manifest.files)
-        await verifyFile(canonical, file);
+    await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
+        await verifyFile(canonical, file, options);
+    });
     const recomputed = digestManifestFiles(manifest.files);
     if (recomputed !== manifest.contentDigest)
         throw new Error(`release content digest mismatch for ${manifest.releaseId}`);
     return { ...manifest, releaseRoot: canonical };
 }
 export async function assertImmutableExecutionRoot(release, dataDir) {
-    await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"));
+    const storeRoot = await realpath(resolve(dataDir, "releases"));
+    assertContained(storeRoot, release.releaseRoot, "release root is outside the selected release store");
     const selectedRoot = process.env[PRODUCT_IDENTITY.environment.releaseRoot];
     if (!selectedRoot)
         throw new Error(PRODUCT_TEXT.diagnostic("persistent process has no immutable release root"));
@@ -75,17 +135,23 @@ export async function resolveReleaseEntryPoint(release, entryPoint) {
     assertContained(release.releaseRoot, canonical, "entry point resolves outside the selected release root");
     return canonical;
 }
-async function verifyFile(root, file) {
+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}`);
-    const digest = createHash("sha256").update(await readFile(path)).digest("hex");
+    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.packageName !== PRODUCT_PACKAGE_NAME || typeof value.packageVersion !== "string")
         throw new Error(PRODUCT_TEXT.diagnostic("release manifest metadata is invalid"));
@@ -101,13 +167,6 @@ function validateManifest(value) {
             throw new Error(`invalid release manifest file identity: ${file.path}`);
     }
 }
-function digestManifestFiles(files) {
-    const digest = createHash("sha256");
-    for (const file of [...files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)) {
-        digest.update(`${file.path}\0${file.bytes}\0${file.sha256}\0${file.executable ? 1 : 0}\n`);
-    }
-    return digest.digest("hex");
-}
 function assertContained(parent, child, message) {
     const fromParent = relative(parent, child);
     if (fromParent === "" || (!fromParent.startsWith(`..${sep}`) && fromParent !== ".." && !isAbsolute(fromParent)))

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

@@ -13,11 +13,26 @@ export interface ReleaseIdentity {
     readonly packageRoot: string;
     readonly files: readonly ReleaseFileIdentity[];
 }
+export interface DiscoveredReleasePayload {
+    readonly packageRoot: string;
+    readonly packageVersion: string;
+    readonly paths: readonly 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[]): 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/src/foundation/release/release.js

@@ -2,54 +2,81 @@ 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;
-/**
- * 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) {
+/** Discover the complete payload without reading ordinary file contents. */
+export async function discoverReleasePayload(packageRoot, options = {}) {
     const canonicalRoot = await realpath(packageRoot);
-    const manifestPath = resolve(canonicalRoot, "package.json");
-    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    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) {
-        const absolute = resolveWithin(canonicalRoot, root);
-        await collectFiles(canonicalRoot, absolute, paths);
-    }
-    await collectDependencyClosure(canonicalRoot, canonicalRoot, manifest, paths, new Set());
-    const files = [];
-    for (const path of [...paths].sort()) {
-        const absolute = resolveWithin(canonicalRoot, path);
+    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(),
+        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())
+        if (!metadata.isFile() || metadata.isSymbolicLink())
             throw new Error(`release payload is not a regular file: ${path}`);
-        const bytes = await readFile(absolute);
-        files.push({
-            path: normalizeRelative(path),
-            bytes: bytes.length,
-            sha256: createHash("sha256").update(bytes).digest("hex"),
-            executable: (metadata.mode & 0o111) !== 0,
-        });
-    }
-    const digest = createHash("sha256");
-    for (const file of files)
-        digest.update(`${file.path}\0${file.bytes}\0${file.sha256}\0${file.executable ? 1 : 0}\n`);
-    const contentDigest = digest.digest("hex");
+        const bytes = payload.cachedFiles.get(path) ?? await readFile(absolute);
+        return releaseFileIdentity(path, bytes, (metadata.mode & 0o111) !== 0);
+    });
+    return createReleaseIdentity(payload.packageRoot, payload.packageVersion, files);
+}
+export function createReleaseIdentity(packageRoot, packageVersion, files) {
+    const contentDigest = digestManifestFiles(files);
     return {
         packageName: PRODUCT_PACKAGE_NAME,
-        packageVersion: manifest.version,
+        packageVersion,
         contentDigest,
-        releaseId: `${manifest.version}-${contentDigest.slice(0, 20)}`,
-        packageRoot: canonicalRoot,
-        files,
+        releaseId: `${packageVersion}-${contentDigest.slice(0, 20)}`,
+        packageRoot,
+        files: [...files].sort(compareReleaseFiles),
     };
 }
+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");
@@ -91,7 +118,7 @@ async function collectFiles(root, path, output, skipNodeModules = false) {
         await collectFiles(root, resolve(path, entry), output, skipNodeModules);
     }
 }
-async function collectDependencyClosure(root, requesterRoot, manifest, output, visited) {
+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()) {
@@ -105,8 +132,7 @@ async function collectDependencyClosure(root, requesterRoot, manifest, output, v
             continue;
         visited.add(packagePath);
         await collectFiles(root, packagePath, output, true);
-        const dependencyManifest = JSON.parse(await readFile(resolve(packagePath, "package.json"), "utf8"));
-        await collectDependencyClosure(root, packagePath, dependencyManifest, output, visited);
+        await collectDependencyClosure(root, packagePath, await readManifest(packagePath), output, visited, readManifest);
     }
 }
 async function findInstalledDependency(root, requesterRoot, name) {
@@ -134,6 +160,9 @@ function dependencyNames(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(/^\.\//, "");
 }

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

@@ -18,6 +18,18 @@ 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 interface UpdatePhaseTimingEvent {
+    readonly phase: UpdateMeasuredPhase;
+    readonly durationMs: number;
+}
+export interface UpdatePerformanceEvidence {
+    readonly fileCount: number;
+    readonly sourceReads: number;
+    readonly candidateWrites: number;
+    readonly verificationReads: number;
+    readonly postNpmDurationMs: number;
+}
 export interface SelfUpdateOptions {
     packageRoot: string;
     channel?: UpdateChannel;
@@ -27,14 +39,18 @@ export interface SelfUpdateOptions {
     runner?: UpdateProcessRunner;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
+    progress?: boolean;
+    onPhaseTiming?: (event: UpdatePhaseTimingEvent) => void;
+    now?: () => number;
 }
+export type UpdateActivationPhase = Extract<UpdateTransactionPhase, "materialized" | "certified" | "active-reference-committed">;
 export interface UpdateLifecycleCoordinator {
     targetIsActive(targetVersion: string): Promise<boolean>;
     shutdownVerifiedOwners(targetVersion: string): Promise<{
         priorActiveVersion: string | null;
     }>;
     verifyPackageUnlocked(packageRoot: string): Promise<void>;
-    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateTransactionPhase) => Promise<void>): Promise<void>;
+    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>): Promise<void>;
 }
 export interface UpdateTransactionJournal {
     readonly path: string;
@@ -50,5 +66,6 @@ export interface UpdateTransactionJournal {
     clearCompleted(): Promise<void>;
 }
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
-export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem): UpdateLifecycleCoordinator;
+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;