@timurproko/a1 0.1.1-dev.3 → 0.1.1-dev.5

package/bin/a1-ui.js

@@ -4,11 +4,11 @@ const { runSelectedInteractiveRuntime } = await import("../dist/src/features/lau
 
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
   ownedUi: async () => {
-    const [{ runOwnedUi }, { composeStructuredWorkspaceApplication }] = await Promise.all([
+    const [{ runOwnedUi }, { composeOwnedUiApplication }] = await Promise.all([
       import("../dist/src/features/owned-ui/index.js"),
       import("../dist/src/composition/index.js"),
     ]);
-    const application = await composeStructuredWorkspaceApplication({ cwd: process.cwd() });
+    const application = await composeOwnedUiApplication({ cwd: process.cwd() });
     return await runOwnedUi({ application });
   },
   transparent: async profileId => {

package/dist/src/composition/index.d.ts

@@ -1,9 +1,6 @@
 import { type AgentEnginePort } from "../foundation/agent-engine-contracts/index.js";
 import { type PiEngineAdapter } from "../foundation/pi-engine-adapter/index.js";
 import { type OwnedUiApplicationPort, type PresentationComponentPort, type PresentationRuntimePort, type PresentationTerminalPort } from "../foundation/presentation-contracts/index.js";
-import { StructuredWorkspaceTabs, type StructuredWorkspaceLimits } from "../features/workspace/index.js";
-import { StructuredWorkspaceApplication } from "./structured-workspace-application.js";
-export * from "./structured-workspace-application.js";
 export interface ProcessCompositionOptions {
     readonly cwd?: string;
     readonly sessionId?: string;
@@ -17,21 +14,6 @@ export interface OwnedUiCompositionOptions {
     readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
 }
 export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOptions): Promise<OwnedUiApplicationPort>;
-export interface StructuredWorkspaceCompositionOptions {
-    readonly cwd?: string;
-    readonly workspaceId?: string;
-    readonly limits?: Partial<StructuredWorkspaceLimits>;
-    readonly createEngine?: (agentId: string) => Promise<AgentEnginePort>;
-    readonly createPiAdapter?: (agentId: string) => Promise<PiEngineAdapter>;
-}
-export declare function composeStructuredWorkspace(options?: StructuredWorkspaceCompositionOptions): StructuredWorkspaceTabs;
-export interface StructuredWorkspaceApplicationCompositionOptions extends StructuredWorkspaceCompositionOptions {
-    readonly terminal?: PresentationTerminalPort;
-    readonly mode?: "regular" | "fullscreen";
-    readonly initialAgentId?: string;
-    readonly initialAgentName?: string;
-}
-export declare function composeStructuredWorkspaceApplication(options?: StructuredWorkspaceApplicationCompositionOptions): Promise<StructuredWorkspaceApplication>;
 export interface ProcessComposition {
     readonly engine: AgentEnginePort;
     createPresentation(root: PresentationComponentPort, terminal: PresentationTerminalPort): PresentationRuntimePort;

package/dist/src/composition/index.js

@@ -3,9 +3,6 @@ import { createPiEngineAdapter } from "../foundation/pi-engine-adapter/index.js"
 import { createPiPresentationRuntime, createPiTerminalBridge } from "../foundation/pi-tui-runtime-adapter/index.js";
 import { assertPresentationComponent, assertPresentationRuntime, } from "../foundation/presentation-contracts/index.js";
 import { OwnedUiSessionShell } from "../foundation/pi-owned-ui-integration/index.js";
-import { StructuredWorkspaceTabs, } from "../features/workspace/index.js";
-import { StructuredWorkspaceApplication } from "./structured-workspace-application.js";
-export * from "./structured-workspace-application.js";
 const CAPABILITIES = {
     contractVersion: AGENT_ENGINE_CONTRACT_VERSION,
     commands: ["prompt", "steer", "follow-up", "abort", "retry", "compact", "bash", "replace-session"],
@@ -28,39 +25,6 @@ export async function composeOwnedUiApplication(options = {}) {
         dispose: () => shell.dispose(),
     };
 }
-export function composeStructuredWorkspace(options = {}) {
-    const cwd = options.cwd ?? process.cwd();
-    const createEngine = options.createEngine ?? (async (agentId) => {
-        const sessionId = `${agentId}.session`;
-        const adapter = options.createPiAdapter
-            ? await options.createPiAdapter(agentId)
-            : await createPiEngineAdapter({ cwd, sessionId });
-        return new PiAgentEngineBridge(adapter, cwd);
-    });
-    return new StructuredWorkspaceTabs({
-        cwd,
-        createEngine,
-        ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
-        ...(options.limits === undefined ? {} : { limits: options.limits }),
-    });
-}
-export async function composeStructuredWorkspaceApplication(options = {}) {
-    const workspace = composeStructuredWorkspace(options);
-    const created = await workspace.createAgent({
-        id: options.initialAgentId ?? "agent-1",
-        displayName: options.initialAgentName ?? "Agent 1",
-    });
-    if (created.kind === "rejected") {
-        await workspace.dispose();
-        throw new Error(`could not create the initial structured workspace agent: ${created.diagnostic}`);
-    }
-    return new StructuredWorkspaceApplication({
-        workspace,
-        cwd: options.cwd ?? process.cwd(),
-        ...(options.terminal === undefined ? {} : { terminal: options.terminal }),
-        ...(options.mode === undefined ? {} : { mode: options.mode }),
-    });
-}
 export async function composeProcess(options = {}) {
     let engine = options.engine;
     if (!engine) {

package/dist/src/features/workspace/index.d.ts

@@ -4,4 +4,3 @@ export * from "./reconciliation.js";
 export * from "./reducer.js";
 export * from "./router.js";
 export * from "./store.js";
-export * from "./structured-tabs.js";

package/dist/src/features/workspace/index.js

@@ -4,4 +4,3 @@ export * from "./reconciliation.js";
 export * from "./reducer.js";
 export * from "./router.js";
 export * from "./store.js";
-export * from "./structured-tabs.js";

package/dist/src/features/workspace/router.d.ts

@@ -22,15 +22,10 @@ export declare class WorkspaceRouter {
     constructor(reducer: WorkspaceReducer);
     createAgent(agent: ManagedAgentDescriptor): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
     selectAgent(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
-    restartAgent(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
-    markRecovered(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
-    markFailed(agentId: string, code: string, message: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
-    requestAttention(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
     stopAgent(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
     removeAgent(agentId: string): Promise<WorkspaceRouterResult<WorkspaceAgentState>>;
     recordActivity(agentId: string, amount?: number): Promise<WorkspaceRouterResult<number>>;
     sendStructuredCommand(agentId: string, command: string, payload: unknown): Promise<WorkspaceRouterResult<RoutedStructuredCommand>>;
     cancelStructuredCommand(agentId: string, targetCorrelationId: string): Promise<WorkspaceRouterResult<StructuredCommandRecord>>;
-    settleStructuredCommand(agentId: string, correlationId: string, outcome: "completed" | "failed"): Promise<WorkspaceRouterResult<StructuredCommandRecord>>;
     view(): WorkspaceView;
 }

package/dist/src/features/workspace/router.js

@@ -23,18 +23,6 @@ export class WorkspaceRouter {
     selectAgent(agentId) {
         return this.#enqueue(() => this.reducer.selectAgent(agentId));
     }
-    restartAgent(agentId) {
-        return this.#enqueue(() => this.reducer.restartAgent(agentId));
-    }
-    markRecovered(agentId) {
-        return this.#enqueue(() => this.reducer.markRecovered(agentId));
-    }
-    markFailed(agentId, code, message) {
-        return this.#enqueue(() => this.reducer.markFailed(agentId, code, message));
-    }
-    requestAttention(agentId) {
-        return this.#enqueue(() => this.reducer.requestAttention(agentId));
-    }
     stopAgent(agentId) {
         return this.#enqueue(() => this.reducer.stopAgent(agentId));
     }
@@ -104,20 +92,6 @@ export class WorkspaceRouter {
             return applied(this.reducer.view(), result.record);
         });
     }
-    settleStructuredCommand(agentId, correlationId, outcome) {
-        return this.#enqueue(() => {
-            const agent = this.reducer.view().agents.find(candidate => candidate.id === agentId);
-            if (!agent)
-                return reject("unknown-agent", `workspace agent does not exist: ${agentId}`);
-            const tracker = this.#trackerFor(agent);
-            if (!tracker)
-                return reject("capability-mismatch", `agent ${agent.id} is not structured`);
-            const result = tracker.complete(correlationId, outcome);
-            if (result.kind === "rejected")
-                return result;
-            return applied(this.reducer.view(), result.record);
-        });
-    }
     view() {
         return this.reducer.view();
     }

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

@@ -2,7 +2,7 @@ import { type OwnershipProbe } from "./cohort-selection.js";
 import { type SupervisorEndpointMetadata } from "./cohort-state.js";
 import { type LaunchProfileId } from "../lifecycle/index.js";
 import { cleanupProvenIdleOwner } from "./process-cleanup.js";
-import { type MaterializedRelease } from "./release-store.js";
+import { type MaterializedRelease, type VerifyMaterializedReleaseOptions } from "./release-store.js";
 export interface BootstrapOptions {
     readonly packageRoot: string;
     readonly launchIntent?: {
@@ -15,7 +15,7 @@ export interface BootstrapOptions {
     readonly output?: Pick<NodeJS.WriteStream, "write">;
 }
 export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
-export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string): Promise<string>;
+export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;
 export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<void>;
 export declare function releaseEnvironment(environment: NodeJS.ProcessEnv, release: MaterializedRelease): NodeJS.ProcessEnv;
 export declare function waitForVerifiedEndpoint(path: string, release: MaterializedRelease, timeoutMs: number): Promise<void>;

package/dist/src/foundation/release/bootstrap.js

@@ -8,7 +8,7 @@ import { CohortStateStore } from "./cohort-state.js";
 import { assertLaunchProfileId, resolveProductPaths } from "../lifecycle/index.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
-import { materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
+import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export async function runBootstrap(options) {
     const environment = { ...(options.environment ?? process.env) };
@@ -42,9 +42,7 @@ export async function runBootstrap(options) {
             return await launchUi(retained, environment);
         }
     }
-    const candidate = await materializeRelease(options.packageRoot, paths.dataDir, {
-        onProgress: progress => output.write(`${PRODUCT_TEXT.diagnostic(`installing ${progress.fileCount} files.`)}\n`),
-    });
+    const candidate = await materializeRelease(options.packageRoot, paths.dataDir);
     await stateStore.recordCandidate(candidate);
     state = await stateStore.read();
     if (!state.references.active) {
@@ -125,8 +123,10 @@ async function readInstalledVersion(packageRoot) {
     }
     return manifest.version;
 }
-export async function certifyMaterializedRelease(release, dataDir) {
-    await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"));
+export async function certifyMaterializedRelease(release, dataDir, verification = {}) {
+    if (!consumeMaterializationProof(release)) {
+        await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"), verification);
+    }
     const path = resolve(dataDir, `certification-${release.releaseId}.json`);
     await writeFile(path, JSON.stringify({
         schema: PRODUCT_IDENTITY.evidence.releaseCertificationSchema,

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

@@ -3,11 +3,23 @@ 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 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;
@@ -16,6 +28,8 @@ export interface CertifiedReleaseRecord {
     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>;
 /**
  * Load metadata for a release whose bytes were already certified by the
@@ -24,6 +38,6 @@ export declare function readMaterializedRelease(releaseRoot: string): Promise<Ma
  * verification.
  */
 export declare function readCertifiedReleaseManifest(record: CertifiedReleaseRecord, selectedStoreRoot: string): Promise<MaterializedRelease>;
-export declare function verifyMaterializedRelease(releaseRoot: string, expected?: ReleaseIdentity, 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,33 +1,52 @@
 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, options = {}) {
-    const identity = await deriveReleaseIdentity(packageRoot);
+    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);
-    options.onProgress?.({ phase: "copying", fileCount: identity.files.length });
-    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 {
-        const directories = [...new Set(identity.files.map(file => dirname(resolveWithin(candidate, file.path))))];
+        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 });
         });
-        await mapWithConcurrency(identity.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
-            const source = resolveWithin(identity.packageRoot, file.path);
-            const destination = resolveWithin(candidate, file.path);
-            await copyFile(source, destination);
-            await chmod(destination, file.executable ? 0o500 : 0o400);
+        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" });
         try {
             await rename(candidate, releaseRoot);
@@ -36,15 +55,22 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
             if (!await lstat(releaseRoot).catch(() => null))
                 throw error;
             await rm(candidate, { recursive: true, force: true });
-            return await verifyMaterializedRelease(releaseRoot, identity);
+            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
         }
-        return { ...identity, releaseRoot: await realpath(releaseRoot) };
+        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"));
@@ -69,7 +95,7 @@ export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
         throw new Error(`release directory does not match identity ${manifest.releaseId}`);
     return { ...manifest, releaseRoot: canonical };
 }
-export async function verifyMaterializedRelease(releaseRoot, expected, selectedStoreRoot) {
+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");
@@ -83,7 +109,7 @@ export async function verifyMaterializedRelease(releaseRoot, expected, selectedS
         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);
+        await verifyFile(canonical, file, options);
     });
     const recomputed = digestManifestFiles(manifest.files);
     if (recomputed !== manifest.contentDigest)
@@ -109,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"));
@@ -135,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

@@ -5,53 +5,78 @@ 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 sortedPaths = [...paths].sort();
-    const files = await mapWithConcurrency(sortedPaths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
-        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);
-        return {
-            path: normalizeRelative(path),
-            bytes: bytes.length,
-            sha256: createHash("sha256").update(bytes).digest("hex"),
-            executable: (metadata.mode & 0o111) !== 0,
-        };
+        const bytes = payload.cachedFiles.get(path) ?? await readFile(absolute);
+        return releaseFileIdentity(path, bytes, (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");
+    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");
@@ -93,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()) {
@@ -107,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) {
@@ -136,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,17 @@ export interface SelfUpdateOptions {
     runner?: UpdateProcessRunner;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
+    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;
@@ -52,3 +67,4 @@ export interface UpdateTransactionJournal {
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
 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;