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

package/dist/src/features/workspace/structured-tabs.js

@@ -0,0 +1,453 @@
+import { AGENT_ENGINE_CONTRACT_VERSION, assertAgentCapabilityContract, assertAgentEvent, assertAgentSnapshot, } from "../../foundation/agent-engine-contracts/index.js";
+import { WORKSPACE_CONTRACT_VERSION, } from "../../foundation/workspace-contracts/index.js";
+import { presentWorkspace } from "./presentation.js";
+import { WorkspaceReducer } from "./reducer.js";
+import { WorkspaceRouter } from "./router.js";
+const DEFAULT_LIMITS = Object.freeze({
+    maxAgents: 8,
+    maxMessagesPerAgent: 512,
+    maxMessageBytes: 256 * 1024,
+    maxEditorBytes: 64 * 1024,
+});
+export class StructuredWorkspaceTabs {
+    router;
+    #cwd;
+    #createEngine;
+    #limits;
+    #now;
+    #tabs = new Map();
+    #listeners = new Set();
+    #disposed = false;
+    constructor(options) {
+        if (!options.cwd || options.cwd.includes("\0"))
+            throw new TypeError("structured workspace cwd is invalid");
+        if (typeof options.createEngine !== "function")
+            throw new TypeError("structured workspace engine factory is required");
+        this.#cwd = options.cwd;
+        this.#createEngine = options.createEngine;
+        this.#limits = validateLimits({ ...DEFAULT_LIMITS, ...options.limits });
+        this.#now = options.now ?? (() => new Date().toISOString());
+        this.router = new WorkspaceRouter(new WorkspaceReducer(options.workspaceId ?? "workspace-default"));
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.view());
+        return () => this.#listeners.delete(listener);
+    }
+    async createAgent(input) {
+        if (this.#disposed)
+            return rejected("workspace-disposed", "structured workspace is disposed");
+        if (this.#tabs.size >= this.#limits.maxAgents)
+            return rejected("agent-limit", `structured workspace is limited to ${this.#limits.maxAgents} agents`);
+        if (this.#tabs.has(input.id))
+            return rejected("duplicate-agent", `structured workspace agent already exists: ${input.id}`);
+        const sessionId = input.sessionId ?? `${input.id}.session`;
+        let runtime;
+        try {
+            runtime = await this.#createRuntime(input.id, sessionId);
+        }
+        catch (error) {
+            return rejected("engine-start-failed", diagnostic(error));
+        }
+        const descriptor = {
+            id: input.id,
+            displayName: input.displayName,
+            adapterId: `engine.${input.id}`,
+            runtime: "structured",
+            lifecycle: workspaceLifecycle(runtime.snapshot.lifecycle),
+            capability: workspaceCapability(runtime.engine, input.id, this.#limits),
+            createdAt: this.#now(),
+            recoveryReferenceId: null,
+        };
+        const created = await this.router.createAgent(descriptor);
+        if (created.kind === "rejected") {
+            await disposeRuntime(runtime.session, runtime.engine);
+            return created;
+        }
+        const tab = {
+            agentId: input.id,
+            sessionId,
+            engine: runtime.engine,
+            session: runtime.session,
+            unsubscribe: () => { },
+            eventTail: Promise.resolve(),
+            lifecycle: runtime.snapshot.lifecycle,
+            transcript: this.#boundedSnapshot(runtime.snapshot),
+            editorText: "",
+            activeCommandIds: new Set(runtime.snapshot.activeCommandIds),
+            lastSequence: runtime.snapshot.sequence,
+            failure: null,
+        };
+        tab.unsubscribe = tab.session.subscribe(event => this.#queueEvent(tab, event));
+        this.#tabs.set(input.id, tab);
+        await this.#reflectLifecycle(tab, runtime.snapshot.lifecycle, null);
+        this.#notify();
+        return applied(this.view(), this.#tabView(tab));
+    }
+    async selectAgent(agentId) {
+        const selected = await this.router.selectAgent(agentId);
+        if (selected.kind === "rejected")
+            return selected;
+        const tab = this.#tabs.get(agentId);
+        if (!tab)
+            return rejected("missing-runtime", `structured runtime is missing for ${agentId}`);
+        this.#notify();
+        return applied(this.view(), this.#tabView(tab));
+    }
+    setEditorText(agentId, text) {
+        const tab = this.#tabs.get(agentId);
+        if (!tab)
+            return rejected("unknown-agent", `structured workspace agent does not exist: ${agentId}`);
+        if (typeof text !== "string" || byteLength(text) > this.#limits.maxEditorBytes) {
+            return rejected("editor-limit", `structured editor exceeds ${this.#limits.maxEditorBytes} bytes`);
+        }
+        tab.editorText = text;
+        this.#notify();
+        return applied(this.view(), this.#tabView(tab));
+    }
+    async submitSelected() {
+        const selectedAgentId = this.router.view().selectedAgentId;
+        if (!selectedAgentId)
+            return rejected("no-selected-agent", "no structured workspace agent is selected");
+        const tab = this.#tabs.get(selectedAgentId);
+        if (!tab)
+            return rejected("missing-runtime", `structured runtime is missing for ${selectedAgentId}`);
+        return await this.sendPrompt(selectedAgentId, tab.editorText);
+    }
+    async sendPrompt(agentId, text) {
+        if (typeof text !== "string" || text.length === 0)
+            return rejected("empty-prompt", "structured prompt must not be empty");
+        if (byteLength(text) > this.#limits.maxEditorBytes)
+            return rejected("editor-limit", `structured prompt exceeds ${this.#limits.maxEditorBytes} bytes`);
+        const routed = await this.router.sendStructuredCommand(agentId, "prompt", { text });
+        if (routed.kind === "rejected")
+            return routed;
+        const tab = this.#tabs.get(agentId);
+        if (!tab)
+            return rejected("missing-runtime", `structured runtime is missing for ${agentId}`);
+        const correlationId = routed.value.correlationId;
+        tab.activeCommandIds.add(correlationId);
+        if (tab.editorText === text)
+            tab.editorText = "";
+        let outcome;
+        try {
+            outcome = await tab.session.execute({
+                contractVersion: AGENT_ENGINE_CONTRACT_VERSION,
+                type: "prompt",
+                commandId: correlationId,
+                sessionId: tab.sessionId,
+                text,
+            });
+        }
+        catch (error) {
+            outcome = "failed";
+            await this.#failTab(tab, "command-failed", diagnostic(error));
+        }
+        if (outcome !== "accepted") {
+            tab.activeCommandIds.delete(correlationId);
+            await this.router.settleStructuredCommand(agentId, correlationId, outcome === "completed" ? "completed" : "failed");
+        }
+        this.#notify();
+        return applied(this.view(), { correlationId, outcome });
+    }
+    async stopAgent(agentId) {
+        const tab = this.#tabs.get(agentId);
+        if (!tab)
+            return rejected("unknown-agent", `structured workspace agent does not exist: ${agentId}`);
+        tab.unsubscribe();
+        try {
+            await disposeRuntime(tab.session, tab.engine);
+        }
+        catch (error) {
+            await this.#failTab(tab, "stop-failed", diagnostic(error));
+            return rejected("stop-failed", diagnostic(error));
+        }
+        tab.lifecycle = "stopped";
+        tab.activeCommandIds.clear();
+        const stopped = await this.router.stopAgent(agentId);
+        if (stopped.kind === "rejected")
+            return stopped;
+        this.#notify();
+        return applied(this.view(), this.#tabView(tab));
+    }
+    async restartAgent(agentId) {
+        const tab = this.#tabs.get(agentId);
+        if (!tab)
+            return rejected("unknown-agent", `structured workspace agent does not exist: ${agentId}`);
+        await this.router.restartAgent(agentId);
+        tab.unsubscribe();
+        await disposeRuntime(tab.session, tab.engine).catch(() => undefined);
+        try {
+            const runtime = await this.#createRuntime(agentId, tab.sessionId);
+            tab.engine = runtime.engine;
+            tab.session = runtime.session;
+            tab.lifecycle = runtime.snapshot.lifecycle;
+            tab.transcript = this.#boundedSnapshot(runtime.snapshot);
+            tab.activeCommandIds = new Set(runtime.snapshot.activeCommandIds);
+            tab.lastSequence = runtime.snapshot.sequence;
+            tab.failure = null;
+            tab.eventTail = Promise.resolve();
+            tab.unsubscribe = tab.session.subscribe(event => this.#queueEvent(tab, event));
+            await this.#reflectLifecycle(tab, runtime.snapshot.lifecycle, null);
+            this.#notify();
+            return applied(this.view(), this.#tabView(tab));
+        }
+        catch (error) {
+            await this.#failTab(tab, "restart-failed", diagnostic(error));
+            return rejected("restart-failed", diagnostic(error));
+        }
+    }
+    async refreshAgent(agentId) {
+        const tab = this.#tabs.get(agentId);
+        if (!tab)
+            return rejected("unknown-agent", `structured workspace agent does not exist: ${agentId}`);
+        try {
+            const snapshot = await tab.session.snapshot();
+            assertAgentSnapshot(snapshot);
+            if (snapshot.sessionId !== tab.sessionId)
+                throw new TypeError("structured snapshot session identity changed");
+            tab.lifecycle = snapshot.lifecycle;
+            tab.transcript = this.#boundedSnapshot(snapshot);
+            tab.activeCommandIds = new Set(snapshot.activeCommandIds);
+            tab.lastSequence = snapshot.sequence;
+            tab.failure = null;
+            await this.#reflectLifecycle(tab, snapshot.lifecycle, null);
+            this.#notify();
+            return applied(this.view(), this.#tabView(tab));
+        }
+        catch (error) {
+            await this.#failTab(tab, "snapshot-failed", diagnostic(error));
+            return rejected("snapshot-failed", diagnostic(error));
+        }
+    }
+    async removeAgent(agentId) {
+        const tab = this.#tabs.get(agentId);
+        if (!tab)
+            return rejected("unknown-agent", `structured workspace agent does not exist: ${agentId}`);
+        const removed = await this.router.removeAgent(agentId);
+        if (removed.kind === "rejected")
+            return removed;
+        tab.unsubscribe();
+        await disposeRuntime(tab.session, tab.engine).catch(() => undefined);
+        this.#tabs.delete(agentId);
+        this.#notify();
+        return applied(this.view(), agentId);
+    }
+    async flush() {
+        await Promise.all([...this.#tabs.values()].map(tab => tab.eventTail));
+    }
+    view() {
+        const workspace = this.router.view();
+        const panels = workspace.agents.flatMap(agent => {
+            const tab = this.#tabs.get(agent.id);
+            return tab ? [this.#tabView(tab)] : [];
+        });
+        const presentation = presentWorkspace(workspace);
+        const rows = new Map(presentation.rows.map(row => [row.agentId, row]));
+        const tabs = panels.map(panel => {
+            const row = rows.get(panel.agentId);
+            return Object.freeze({
+                role: "tab",
+                agentId: panel.agentId,
+                label: row?.label ?? panel.agentId,
+                selected: panel.selected,
+                accessibleDescription: row?.accessibleDescription ?? panel.accessibleDescription,
+            });
+        });
+        return Object.freeze({
+            role: "tablist",
+            workspace,
+            presentation,
+            tabs: Object.freeze(tabs),
+            panels: Object.freeze(panels),
+            selectedPanel: panels.find(panel => panel.selected) ?? null,
+        });
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        const failures = [];
+        for (const tab of [...this.#tabs.values()].reverse()) {
+            tab.unsubscribe();
+            await tab.eventTail.catch(error => failures.push(error));
+            await disposeRuntime(tab.session, tab.engine).catch(error => failures.push(error));
+        }
+        this.#tabs.clear();
+        this.#listeners.clear();
+        if (failures.length > 0)
+            throw new AggregateError(failures, "structured workspace disposal failed");
+    }
+    async #createRuntime(agentId, sessionId) {
+        const engine = await this.#createEngine(agentId);
+        try {
+            assertAgentCapabilityContract(engine.capabilities);
+            const session = await engine.createSession({ sessionId, cwd: this.#cwd });
+            assertAgentCapabilityContract(session.capabilities);
+            const snapshot = await session.snapshot();
+            assertAgentSnapshot(snapshot);
+            if (session.sessionId !== sessionId || snapshot.sessionId !== sessionId)
+                throw new TypeError("structured session identity does not match its workspace tab");
+            return { engine, session, snapshot };
+        }
+        catch (error) {
+            await engine.dispose().catch(() => undefined);
+            throw error;
+        }
+    }
+    #queueEvent(tab, event) {
+        tab.eventTail = tab.eventTail
+            .then(() => this.#applyEvent(tab, event))
+            .catch(error => this.#failTab(tab, "event-failed", diagnostic(error)))
+            .then(() => this.#notify());
+    }
+    async #applyEvent(tab, event) {
+        assertAgentEvent(event, tab.session.capabilities);
+        if (event.sessionId !== tab.sessionId)
+            throw new TypeError("structured event crossed workspace tab identity");
+        if (event.sequence <= tab.lastSequence)
+            return;
+        if (event.sequence !== tab.lastSequence + 1 || event.type === "snapshot-invalidated") {
+            await this.refreshAgent(tab.agentId);
+            return;
+        }
+        tab.lastSequence = event.sequence;
+        if (event.type === "content") {
+            this.#appendMessage(tab, event.content);
+            await this.router.recordActivity(tab.agentId);
+            return;
+        }
+        if (event.type === "lifecycle") {
+            tab.lifecycle = event.lifecycle;
+            await this.#reflectLifecycle(tab, event.lifecycle, event.reason);
+            return;
+        }
+        if (event.type === "command-outcome") {
+            tab.activeCommandIds.delete(event.commandId);
+            await this.router.settleStructuredCommand(tab.agentId, event.commandId, event.outcome === "completed" ? "completed" : "failed");
+            if (event.outcome === "failed")
+                await this.router.requestAttention(tab.agentId);
+            return;
+        }
+        if (event.type === "diagnostic") {
+            if (event.recoverable)
+                await this.router.requestAttention(tab.agentId);
+            else
+                await this.#failTab(tab, event.code, event.message);
+        }
+    }
+    #appendMessage(tab, message) {
+        if (byteLength(JSON.stringify(message)) > this.#limits.maxMessageBytes)
+            throw new RangeError("structured message exceeds its workspace tab byte limit");
+        tab.transcript.push(message);
+        while (tab.transcript.length > this.#limits.maxMessagesPerAgent)
+            tab.transcript.shift();
+    }
+    #boundedSnapshot(snapshot) {
+        if (byteLength(JSON.stringify(snapshot)) > snapshot.capabilities.snapshots.maxBytes)
+            throw new RangeError("structured snapshot exceeds its negotiated byte limit");
+        const messages = snapshot.content.slice(-this.#limits.maxMessagesPerAgent);
+        for (const message of messages) {
+            if (byteLength(JSON.stringify(message)) > this.#limits.maxMessageBytes)
+                throw new RangeError("structured snapshot message exceeds its workspace tab byte limit");
+        }
+        return [...messages];
+    }
+    async #reflectLifecycle(tab, lifecycle, reason) {
+        if (lifecycle === "ready" || lifecycle === "busy")
+            await this.router.markRecovered(tab.agentId);
+        else if (lifecycle === "starting")
+            await this.router.restartAgent(tab.agentId);
+        else if (lifecycle === "stopped")
+            await this.router.stopAgent(tab.agentId);
+        else if (lifecycle === "failed")
+            await this.#failTab(tab, "engine-failed", reason ?? "structured engine failed");
+    }
+    async #failTab(tab, code, message) {
+        tab.lifecycle = "failed";
+        tab.failure = `${code}: ${message}`;
+        tab.activeCommandIds.clear();
+        await this.router.markFailed(tab.agentId, code, message);
+    }
+    #notify() {
+        const view = this.view();
+        for (const listener of this.#listeners)
+            listener(view);
+    }
+    #tabView(tab) {
+        const selected = this.router.view().selectedAgentId === tab.agentId;
+        const toolMessages = tab.transcript.filter(message => message.role === "tool" || message.content.some(content => content.kind === "tool-call" || content.kind === "tool-result"));
+        return Object.freeze({
+            role: "tabpanel",
+            agentId: tab.agentId,
+            sessionId: tab.sessionId,
+            selected,
+            lifecycle: tab.lifecycle,
+            transcript: Object.freeze([...tab.transcript]),
+            toolMessages: Object.freeze(toolMessages),
+            editorText: tab.editorText,
+            activeCommandIds: Object.freeze([...tab.activeCommandIds]),
+            lastSequence: tab.lastSequence,
+            failure: tab.failure,
+            accessibleDescription: `${selected ? "selected" : "background"} structured agent ${tab.agentId}; ${tab.lifecycle}; ${tab.transcript.length} messages`,
+        });
+    }
+}
+function workspaceCapability(engine, agentId, limits) {
+    return {
+        kind: "structured",
+        protocolVersion: WORKSPACE_CONTRACT_VERSION,
+        adapterId: `engine.${agentId}`,
+        commands: Object.freeze([...engine.capabilities.commands]),
+        eventTypes: Object.freeze([...engine.capabilities.events]),
+        snapshots: engine.capabilities.snapshots.supported ? "authoritative" : "none",
+        resume: engine.capabilities.snapshots.supported ? "snapshot" : "none",
+        cancellation: engine.capabilities.commands.includes("abort") ? "correlated" : "none",
+        attachmentTypes: Object.freeze([]),
+        flow: Object.freeze({
+            maxEventBytes: limits.maxMessageBytes,
+            maxSnapshotBytes: engine.capabilities.snapshots.maxBytes,
+            maxAttachmentBytes: limits.maxMessageBytes,
+            maxQueuedEvents: limits.maxMessagesPerAgent,
+            maxConcurrentCommands: 4,
+            maxReconnectEvents: limits.maxMessagesPerAgent,
+        }),
+    };
+}
+function workspaceLifecycle(lifecycle) {
+    if (lifecycle === "starting")
+        return "creating";
+    if (lifecycle === "stopping")
+        return "stopping";
+    if (lifecycle === "stopped")
+        return "stopped";
+    if (lifecycle === "failed")
+        return "failed";
+    return "ready";
+}
+function validateLimits(limits) {
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new RangeError(`structured workspace ${name} must be a positive safe integer`);
+    }
+    return Object.freeze(limits);
+}
+async function disposeRuntime(session, engine) {
+    const failures = [];
+    await session.dispose().catch(error => failures.push(error));
+    await engine.dispose().catch(error => failures.push(error));
+    if (failures.length > 0)
+        throw new AggregateError(failures, "structured agent runtime disposal failed");
+}
+function applied(view, value) {
+    return { kind: "applied", view, value };
+}
+function rejected(code, message) {
+    return { kind: "rejected", code, diagnostic: message };
+}
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}

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, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
+import { 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) };
@@ -18,18 +18,43 @@ export async function runBootstrap(options) {
     const output = options.output ?? process.stderr;
     const paths = resolveProductPaths(environment);
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
-    const candidate = await materializeRelease(options.packageRoot, paths.dataDir);
     const stateStore = new CohortStateStore(paths.dataDir);
-    await stateStore.recordCandidate(candidate);
     let state = await stateStore.read();
+    let endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
+    let probe = endpoint ? await probeOwnership(endpoint) : "dead";
+    const installedVersion = await readInstalledVersion(options.packageRoot);
+    const activeId = state.references.active;
+    const active = activeId === null ? undefined : state.releases[activeId];
+    if (active?.approval === "approved" && active.packageVersion === installedVersion) {
+        const endpointMatches = endpoint?.releaseId === active.releaseId
+            && endpoint.releaseRoot === active.releaseRoot
+            && endpoint.contentDigest === active.contentDigest;
+        if (endpointMatches && probe === "live-verified") {
+            const retained = await readCertifiedReleaseManifest(active, resolve(paths.dataDir, "releases"));
+            return await launchUi(retained, environment);
+        }
+        if (endpoint === null || probe === "dead") {
+            if (endpoint)
+                await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
+            const retained = await readMaterializedRelease(active.releaseRoot);
+            await startSupervisor(retained, environment);
+            await waitForVerifiedEndpoint(paths.endpointMetadataPath, retained, 8_000);
+            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`),
+    });
+    await stateStore.recordCandidate(candidate);
+    state = await stateStore.read();
     if (!state.references.active) {
         const diagnosticsPath = await certifyMaterializedRelease(candidate, paths.dataDir);
         await stateStore.approve(candidate.releaseId, diagnosticsPath);
         await stateStore.activate(candidate.releaseId);
         state = await stateStore.read();
     }
-    const endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-    const probe = endpoint ? await probeOwnership(endpoint) : "dead";
+    endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
+    probe = endpoint ? await probeOwnership(endpoint) : "dead";
     let decision = selectCohortLaunch(candidate, state, endpoint, probe);
     if (decision.action === "blocked") {
         await stateStore.blockPending(decision.reason, endpoint?.ownership.liveGenerationIds ?? []);
@@ -93,6 +118,13 @@ export async function runBootstrap(options) {
     await waitForVerifiedEndpoint(paths.endpointMetadataPath, selected, 8_000);
     return await launchUi(selected, environment);
 }
+async function readInstalledVersion(packageRoot) {
+    const manifest = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
+    if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+        throw new Error(PRODUCT_TEXT.diagnostic("package metadata has no version"));
+    }
+    return manifest.version;
+}
 export async function certifyMaterializedRelease(release, dataDir) {
     await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"));
     const path = resolve(dataDir, `certification-${release.releaseId}.json`);

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

@@ -0,0 +1 @@
+export declare function mapWithConcurrency<Value, Result>(values: readonly Value[], concurrency: number, operation: (value: Value, index: number) => Promise<Result>): Promise<Result[]>;

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

@@ -0,0 +1,17 @@
+export async function mapWithConcurrency(values, concurrency, operation) {
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1)
+        throw new RangeError("concurrency must be a positive safe integer");
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        while (true) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= values.length)
+                return;
+            results[index] = await operation(values[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, worker));
+    return results;
+}

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

@@ -3,8 +3,27 @@ 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 interface MaterializeReleaseOptions {
+    readonly onProgress?: (progress: {
+        readonly phase: "copying";
+        readonly fileCount: number;
+    }) => 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>;
 export declare function readMaterializedRelease(releaseRoot: 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): 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

@@ -3,8 +3,10 @@ import { chmod, copyFile, lstat, mkdir, readFile, realpath, rename, rm, writeFil
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { PRODUCT_PACKAGE_NAME, deriveReleaseIdentity, resolveWithin } from "./release.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { mapWithConcurrency } from "./concurrency.js";
+const RELEASE_FILE_IO_CONCURRENCY = 32;
 export const RELEASE_MANIFEST_FILENAME = PRODUCT_IDENTITY.manifest.releaseFilename;
-export async function materializeRelease(packageRoot, dataDir) {
+export async function materializeRelease(packageRoot, dataDir, options = {}) {
     const identity = await deriveReleaseIdentity(packageRoot);
     const storeRoot = resolve(dataDir, "releases");
     await mkdir(storeRoot, { recursive: true, mode: 0o700 });
@@ -12,20 +14,31 @@ export async function materializeRelease(packageRoot, dataDir) {
     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()}`);
     await mkdir(candidate, { recursive: false, mode: 0o700 });
     try {
-        for (const file of identity.files) {
+        const directories = [...new Set(identity.files.map(file => dirname(resolveWithin(candidate, file.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 mkdir(dirname(destination), { recursive: true, mode: 0o700 });
             await copyFile(source, destination);
             await chmod(destination, file.executable ? 0o500 : 0o400);
-        }
+        });
         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 await verifyMaterializedRelease(releaseRoot, identity);
+        }
+        return { ...identity, releaseRoot: await realpath(releaseRoot) };
     }
     catch (error) {
         await rm(candidate, { recursive: true, force: true });
@@ -37,6 +50,25 @@ export async function readMaterializedRelease(releaseRoot) {
     const manifest = JSON.parse(await readFile(resolve(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
     return await verifyMaterializedRelease(canonical, manifest);
 }
+/**
+ * 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) {
     const canonical = await realpath(releaseRoot);
     if (selectedStoreRoot)
@@ -50,15 +82,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 mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
         await verifyFile(canonical, file);
+    });
     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"));