@loucompanion/forge-bridge 0.1.3-dev.b3bce6ba65a6 → 0.1.3-dev.ba293ccf876b

package/dist/runtime/prepared-runtime-identity.d.ts

@@ -0,0 +1,3 @@
+import { type HostParallelProofIdentity } from "./host-runtime-promotion.js";
+/** Bind evidence to the prepared source, including unstaged replacements, not just HEAD. */
+export declare function preparedRuntimeIdentity(worktreePath: string, signal?: AbortSignal): Promise<HostParallelProofIdentity>;

package/dist/runtime/prepared-runtime-identity.js

@@ -0,0 +1,191 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitClient } from "../shared/git/git.js";
+import { hostRuntimeContractPath, loadHostRuntimeContract } from "./host-runtime-contract.js";
+import { hostRuntimeContractFingerprint } from "./host-runtime-promotion.js";
+import { readCanonicalSourceFile } from "./canonical-source-file.js";
+import { assertCanonicalDirectory } from "./attempt-private-directory.js";
+import { readPinnedSourceDirectory } from "./pinned-source-directory.js";
+/** Bind evidence to the prepared source, including unstaged replacements, not just HEAD. */
+export async function preparedRuntimeIdentity(worktreePath, signal) {
+    const root = await fs.realpath(worktreePath);
+    const rootIdentity = (await assertCanonicalDirectory(root));
+    const sourceKey = (target) => process.platform === "win32" ? target.toLowerCase() : target;
+    const expectedEntries = new Map();
+    const directories = new Map();
+    const containedRelative = (target) => {
+        const relative = path.relative(root, path.resolve(target));
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new Error("host_runtime_source_invalid: source path escapes the worktree.");
+        }
+        return relative.replaceAll("\\", "/");
+    };
+    const directorySnapshot = async (target) => {
+        const resolved = path.resolve(target);
+        containedRelative(resolved);
+        const key = sourceKey(resolved);
+        let captured = directories.get(key);
+        if (!captured) {
+            captured = (async () => {
+                let identity;
+                if (key === sourceKey(root))
+                    identity = rootIdentity;
+                else {
+                    const parent = await expectedEntry(resolved);
+                    if (!parent || parent.kind !== "directory") {
+                        throw new Error("host_runtime_source_changed: discovery directory identity changed.");
+                    }
+                    identity = parent.identity;
+                }
+                const entries = await readPinnedSourceDirectory(resolved, identity);
+                for (const entry of entries)
+                    expectedEntries.set(sourceKey(path.join(resolved, entry.name)), entry);
+                return { path: resolved, identity, entries };
+            })();
+            directories.set(key, captured);
+        }
+        return (await captured).entries.map(entry => ({
+            name: entry.name,
+            isDirectory: entry.kind === "directory",
+            isFile: entry.kind === "file",
+        }));
+    };
+    const expectedEntry = async (target) => {
+        const resolved = path.resolve(target);
+        containedRelative(resolved);
+        if (sourceKey(resolved) === sourceKey(root)) {
+            return { name: path.basename(root), kind: "directory", identity: rootIdentity, size: 0n };
+        }
+        const parentPath = path.dirname(resolved);
+        if (sourceKey(parentPath) !== sourceKey(root)) {
+            const parent = await expectedEntry(parentPath);
+            if (!parent)
+                return undefined;
+            if (parent.kind !== "directory") {
+                throw new Error("host_runtime_source_changed: discovery ancestor is not a directory.");
+            }
+        }
+        await directorySnapshot(parentPath);
+        return expectedEntries.get(sourceKey(resolved));
+    };
+    // Pin the worktree before Git or discovery uses it. Every child directory is
+    // subsequently reached through an identity captured from its pinned parent.
+    await directorySnapshot(root);
+    const git = new GitClient();
+    const head = (await git.run(root, ["rev-parse", "HEAD"])).trim();
+    const inventory = async () => {
+        const included = (name) => name && (!name.startsWith(".forge/") || name === ".forge/forge.runtime.yml");
+        // ls-files --deleted loses a deletion once staged. HEAD-relative tombstones
+        // keep the same prepared source identity before and after git add -u.
+        const deleted = [...new Set((await git.run(root, ["ls-files", "-z", "--deleted"]))
+                .split("\0").concat((await git.run(root, ["diff", "--name-only", "--diff-filter=D", "-z", "HEAD", "--"]))
+                .split("\0")).filter(included))].sort();
+        const names = [...new Set((await git.run(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"]))
+                .split("\0").concat(deleted, hostRuntimeContractPath).filter(included))].sort();
+        return { names, deleted };
+    };
+    const source = await inventory();
+    const { names } = source;
+    if (names.length > 100_000)
+        throw new Error("host_runtime_source_invalid: source inventory exceeds the file limit.");
+    const deleted = new Set(source.deleted);
+    const hash = createHash("sha256");
+    const snapshot = new Map();
+    const additional = new Map();
+    let discoveryCapture = Promise.resolve();
+    let bytes = 0;
+    for (const name of names) {
+        signal?.throwIfAborted();
+        const target = path.resolve(root, name);
+        const relative = path.relative(root, target);
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new Error("host_runtime_source_invalid: source path escapes the worktree.");
+        }
+        hash.update(JSON.stringify(name));
+        try {
+            const expected = await expectedEntry(target);
+            if (!expected || expected.kind !== "file") {
+                throw Object.assign(new Error("host_runtime_source_changed: source inventory no longer names an ordinary file."), { code: "ENOENT" });
+            }
+            const sourceBytes = await readCanonicalSourceFile(target, 256 * 1024 * 1024 - bytes, expected.identity);
+            bytes += sourceBytes.length;
+            hash.update(createHash("sha256").update(sourceBytes).digest());
+            snapshot.set(sourceKey(target), Promise.resolve(sourceBytes));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || (!deleted.has(name) && name !== hostRuntimeContractPath))
+                throw error;
+            hash.update(deleted.has(name) ? "deleted" : "absent");
+            snapshot.set(sourceKey(target), Promise.resolve(null));
+        }
+    }
+    const contract = await loadHostRuntimeContract(root, target => {
+        const key = sourceKey(path.resolve(target));
+        const captured = snapshot.get(key);
+        if (captured)
+            return captured;
+        // Discovery also consumes ignored lockfiles and launch metadata. Capture
+        // those once, too; omission from Git's inventory must not change discovery.
+        const capture = discoveryCapture.then(async () => {
+            signal?.throwIfAborted();
+            const relative = path.relative(root, target).replaceAll("\\", "/");
+            if (relative.startsWith("..") || path.isAbsolute(relative)) {
+                throw new Error("host_runtime_source_invalid: discovery input escapes the worktree.");
+            }
+            let sourceBytes;
+            try {
+                const expected = await expectedEntry(target);
+                if (!expected)
+                    sourceBytes = null;
+                else if (expected.kind !== "file") {
+                    throw new Error("host_runtime_source_changed: discovery input is not an ordinary file.");
+                }
+                else {
+                    sourceBytes = await readCanonicalSourceFile(target, 256 * 1024 * 1024 - bytes, expected.identity);
+                }
+                if (sourceBytes !== null) {
+                    bytes += sourceBytes.length;
+                    if (bytes > 256 * 1024 * 1024)
+                        throw new Error("host_runtime_source_invalid: discovery exceeds the byte limit.");
+                }
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                sourceBytes = null;
+            }
+            additional.set(relative, sourceBytes);
+            return sourceBytes;
+        });
+        // Discovery walks in parallel, but reads share one total byte budget.
+        discoveryCapture = capture.then(() => undefined, () => undefined);
+        snapshot.set(key, capture);
+        return capture;
+    }, directorySnapshot);
+    for (const [name, sourceBytes] of [...additional].sort(([left], [right]) => left.localeCompare(right))) {
+        hash.update(JSON.stringify(["runtime-discovery", name]));
+        hash.update(sourceBytes === null ? "absent" : createHash("sha256").update(sourceBytes).digest());
+    }
+    if (head !== (await git.run(root, ["rev-parse", "HEAD"])).trim()
+        || JSON.stringify(source) !== JSON.stringify(await inventory())) {
+        throw new Error("host_runtime_source_changed: prepared source changed during verification.");
+    }
+    for (const captured of await Promise.all([...directories.values()])) {
+        const current = await readPinnedSourceDirectory(captured.path, captured.identity);
+        if (directoryInventory(current) !== directoryInventory(captured.entries)) {
+            throw new Error("host_runtime_source_changed: runtime discovery inventory changed during verification.");
+        }
+    }
+    return {
+        inputCommitSha: head,
+        runtimeContractFingerprint: hostRuntimeContractFingerprint(contract),
+        sourceFingerprint: `sha256:${hash.digest("hex")}`,
+    };
+}
+function directoryInventory(entries) {
+    return JSON.stringify(entries.map(entry => ({
+        name: entry.name,
+        kind: entry.kind,
+    })));
+}

package/dist/runtime/prepared-runtime-readiness.d.ts

@@ -0,0 +1,22 @@
+import type { RunOnceDispatchPacket } from "../session/session.types.js";
+import type { HostRuntimeAdmissionCheckpointHandler, HostRuntimeLeaseRuntime } from "./host-runtime-lease.js";
+import { HostParallelPromotionStore, type HostParallelProofIdentity } from "./host-runtime-promotion.js";
+/** Foreground barrier: prepare a wave, verify its exact runtimes, then release agents. */
+export declare class PreparedRuntimeReadiness {
+    private readonly runtime;
+    private readonly store;
+    private readonly releasePreparation;
+    private readonly admissionExpired;
+    private readonly preparations;
+    private readonly draining;
+    constructor(runtime: HostRuntimeLeaseRuntime, store: HostParallelPromotionStore, releasePreparation: (id: string, fence: string) => Promise<unknown>, admissionExpired: () => Error);
+    acquire(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    has(id: string): boolean;
+    hasPending(): boolean;
+    verify(dispatch: RunOnceDispatchPacket, worktree: string, checkpoint?: HostRuntimeAdmissionCheckpointHandler): Promise<HostParallelProofIdentity | undefined>;
+    renew(id: string, fence: string, expiresAt: string): Promise<void>;
+    cancel(id: string, fence: string, reason?: Error): void;
+    private drain;
+    private scheduleDeadline;
+    private check;
+}

package/dist/runtime/prepared-runtime-readiness.js

@@ -0,0 +1,191 @@
+import { randomUUID } from "node:crypto";
+import { loadHostRuntimeContract } from "./host-runtime-contract.js";
+import { configuredLaunchPortNames, hostRuntimeContractFingerprint, hostRuntimeParallelEligible } from "./host-runtime-promotion.js";
+import { preparedRuntimeIdentity } from "./prepared-runtime-identity.js";
+/** Foreground barrier: prepare a wave, verify its exact runtimes, then release agents. */
+export class PreparedRuntimeReadiness {
+    runtime;
+    store;
+    releasePreparation;
+    admissionExpired;
+    preparations = new Map();
+    draining = new Set();
+    constructor(runtime, store, releasePreparation, admissionExpired) {
+        this.runtime = runtime;
+        this.store = store;
+        this.releasePreparation = releasePreparation;
+        this.admissionExpired = admissionExpired;
+    }
+    async acquire(dispatch, signal) {
+        const id = dispatch.sandbox.dispatchAttemptId;
+        if (this.preparations.has(id))
+            throw new Error("host_runtime_preparation_conflict: duplicate preparation.");
+        const controller = new AbortController();
+        const abort = () => this.cancel(id, dispatch.lease.fencingToken);
+        const entry = { dispatch, controller, phase: "preparing", expiresAt: dispatch.lease.expiresAt,
+            removeAbort: () => signal?.removeEventListener("abort", abort) };
+        this.preparations.set(id, entry);
+        this.scheduleDeadline(entry);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        try {
+            // Preparation consumes normal capacity, but no project-runtime claim.
+            return await this.runtime.acquire({ ...dispatch,
+                runtimeIntent: { ...dispatch.runtimeIntent, executionClass: "analysis_only", applicationRuntimeRequired: false },
+            }, controller.signal);
+        }
+        catch (error) {
+            const failure = controller.signal.aborted ? controller.signal.reason : error;
+            this.cancel(id, dispatch.lease.fencingToken);
+            throw failure;
+        }
+    }
+    has(id) { return this.preparations.has(id); }
+    hasPending() { return this.preparations.size > 0; }
+    async verify(dispatch, worktree, checkpoint) {
+        const id = dispatch.sandbox.dispatchAttemptId;
+        const entry = this.preparations.get(id);
+        if (!entry || entry.dispatch.lease.fencingToken !== dispatch.lease.fencingToken) {
+            throw new Error("host_runtime_preparation_missing: preparation ownership changed.");
+        }
+        // Release preparation headroom before waiting for peers; otherwise a one-slot
+        // host would deadlock while the rest of the wave tries to prepare.
+        await this.releasePreparation(id, dispatch.lease.fencingToken);
+        entry.controller.signal.throwIfAborted();
+        const completion = new Promise((resolve, reject) => {
+            entry.resolve = resolve;
+            entry.reject = reject;
+        });
+        entry.check = () => this.check(entry, worktree, checkpoint);
+        entry.phase = "queued";
+        void this.drain(dispatch.repo.id);
+        return await completion;
+    }
+    async renew(id, fence, expiresAt) {
+        const entry = this.preparations.get(id);
+        if (!entry || entry.dispatch.lease.fencingToken !== fence || Date.parse(expiresAt) <= Date.parse(entry.expiresAt))
+            return;
+        entry.expiresAt = expiresAt;
+        this.scheduleDeadline(entry);
+        if (entry.probe)
+            await this.runtime.updateLease(entry.probe.sandbox.dispatchAttemptId, entry.probe.lease.fencingToken, expiresAt);
+    }
+    cancel(id, fence, reason = new Error("host_runtime_preparation_cancelled: prepared readiness was cancelled.")) {
+        const entry = this.preparations.get(id);
+        if (!entry || entry.dispatch.lease.fencingToken !== fence)
+            return;
+        if (entry.deadline)
+            clearTimeout(entry.deadline);
+        entry.controller.abort(reason);
+        // Do not return to session teardown while a supervised probe still owns the worktree.
+        if (entry.phase === "checking")
+            return;
+        entry.reject?.(entry.controller.signal.reason);
+        entry.removeAbort();
+        this.preparations.delete(id);
+        void this.drain(entry.dispatch.repo.id);
+    }
+    async drain(repoId) {
+        if (this.draining.has(repoId))
+            return;
+        const entries = () => [...this.preparations.values()].filter(entry => entry.dispatch.repo.id === repoId);
+        if (entries().some(entry => entry.phase === "preparing"))
+            return;
+        this.draining.add(repoId);
+        const completed = [];
+        try {
+            for (const entry of entries()) {
+                if (entry.phase !== "queued")
+                    continue;
+                entry.phase = "checking";
+                try {
+                    completed.push({ entry, identity: await entry.check() });
+                }
+                catch (error) {
+                    completed.push({ entry, error });
+                }
+            }
+            // No provider from this wave can start while a sibling proof is running.
+            for (const result of completed) {
+                const { entry } = result;
+                this.preparations.delete(entry.dispatch.sandbox.dispatchAttemptId);
+                if (entry.deadline)
+                    clearTimeout(entry.deadline);
+                entry.removeAbort();
+                if (entry.controller.signal.aborted)
+                    entry.reject?.(entry.controller.signal.reason);
+                else if (result.error)
+                    entry.reject?.(result.error);
+                else
+                    entry.resolve?.(result.identity);
+            }
+        }
+        finally {
+            this.draining.delete(repoId);
+            if (entries().some(entry => entry.phase === "queued"))
+                void this.drain(repoId);
+        }
+    }
+    scheduleDeadline(entry) {
+        if (entry.deadline)
+            clearTimeout(entry.deadline);
+        const delay = Date.parse(entry.expiresAt) - Date.now();
+        entry.deadline = setTimeout(() => this.cancel(entry.dispatch.sandbox.dispatchAttemptId, entry.dispatch.lease.fencingToken, this.admissionExpired()), Number.isFinite(delay) ? Math.max(0, Math.min(delay, 2_147_483_647)) : 0);
+        entry.deadline.unref();
+    }
+    async check(entry, worktree, checkpoint) {
+        const { dispatch, controller } = entry;
+        if (!dispatch.runtimeIntent.applicationRuntimeRequired)
+            return undefined;
+        const contract = await loadHostRuntimeContract(worktree);
+        if (!hostRuntimeParallelEligible(contract))
+            return undefined;
+        const identity = await preparedRuntimeIdentity(worktree, controller.signal);
+        if (hostRuntimeContractFingerprint(contract) !== identity.runtimeContractFingerprint) {
+            throw new Error("host_runtime_prepared_probe_changed: runtime contract changed while capturing its source identity.");
+        }
+        if (await this.store.load(dispatch.repo.id, identity))
+            return identity;
+        await checkpoint?.({ code: "host_runtime_prepared_probe_started", expiresAt: entry.expiresAt,
+            message: `Verifying prepared runtime ${identity.inputCommitSha.slice(0, 12)} before agent admission; project-default readiness is not a substitute.` });
+        const probeId = randomUUID();
+        const probe = { ...dispatch,
+            cycleRun: { ...dispatch.cycleRun, phase: "prepared_readiness" },
+            lease: { ...dispatch.lease, id: probeId, fencingToken: randomUUID(), expiresAt: entry.expiresAt },
+            sandbox: { ...dispatch.sandbox, dispatchAttemptId: probeId, executionLeaseId: probeId,
+                inputCommitSha: identity.inputCommitSha },
+        };
+        entry.probe = probe;
+        let cleanupConfirmed;
+        try {
+            controller.signal.throwIfAborted();
+            await this.runtime.acquire(probe, controller.signal);
+            const prepared = await this.runtime.start(probe, worktree, controller.signal);
+            if (hostRuntimeContractFingerprint(prepared.runtimeContract) !== identity.runtimeContractFingerprint) {
+                throw new Error("host_runtime_prepared_probe_changed: probe loaded a different runtime contract; application was not started.");
+            }
+            const started = await this.runtime.startConfiguredProject(probeId, probe.lease.fencingToken, controller.signal, progress => checkpoint?.({ code: "host_runtime_prepared_probe_progress", expiresAt: entry.expiresAt,
+                message: progress.message }));
+            const ports = started.lease.resources.ports.map(port => port.name).sort();
+            const verified = JSON.stringify(ports) === JSON.stringify(configuredLaunchPortNames(contract))
+                && hostRuntimeContractFingerprint(started.runtimeContract) === identity.runtimeContractFingerprint
+                && JSON.stringify(identity) === JSON.stringify(await preparedRuntimeIdentity(worktree, controller.signal));
+            if (!verified)
+                throw new Error("host_runtime_prepared_probe_changed: source changed or assigned-port verification was incomplete.");
+        }
+        finally {
+            // A failed teardown must not publish reusable evidence.
+            cleanupConfirmed = Boolean(await this.runtime.release(probeId, probe.lease.fencingToken));
+            entry.probe = undefined;
+        }
+        if (!cleanupConfirmed) {
+            throw new Error("host_runtime_prepared_probe_cleanup_unconfirmed: matching probe teardown was not confirmed.");
+        }
+        controller.signal.throwIfAborted();
+        await this.store.observe(dispatch.repo.id, contract, probeId, configuredLaunchPortNames(contract), identity.inputCommitSha, identity.sourceFingerprint);
+        await checkpoint?.({ code: "host_runtime_prepared_probe_completed", expiresAt: entry.expiresAt,
+            message: `Prepared runtime ${identity.inputCommitSha.slice(0, 12)} passed isolation verification; its source-bound proof is retained independently.` });
+        return identity;
+    }
+}

package/dist/runtime/runtime-isolation-lease.d.ts

@@ -0,0 +1,67 @@
+export declare const runtimeIsolationLeaseStates: readonly ["reserved", "starting", "active", "releasing", "released", "degraded"];
+export type RuntimeIsolationLeaseState = typeof runtimeIsolationLeaseStates[number];
+export type RuntimeIsolationMode = "docker" | "host";
+export interface RuntimeIsolationPort {
+    readonly name: string;
+    readonly protocol: "tcp" | "udp";
+    readonly hostIp: "127.0.0.1" | "::1";
+    readonly hostPort: number;
+    readonly targetPort: number;
+}
+export interface RuntimeIsolationPath {
+    readonly path: string;
+    readonly role: string;
+}
+export interface RuntimeIsolationDockerResource {
+    readonly type: "container" | "network" | "volume";
+    readonly name: string;
+    readonly role: string;
+    readonly id?: string | null;
+}
+export interface RuntimeIsolationResources {
+    readonly memoryReservationBytes: number;
+    readonly cpuMillis: number;
+    readonly pids: number;
+    readonly ports: readonly RuntimeIsolationPort[];
+    readonly paths: readonly RuntimeIsolationPath[];
+    readonly processSupervisorId: string | null;
+    readonly dockerResources: readonly RuntimeIsolationDockerResource[];
+    readonly singletonKeys: readonly string[];
+}
+export interface RuntimeIsolationLease {
+    readonly schemaVersion: 1;
+    readonly leaseId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly worktreeKey: string;
+    readonly worktreePath: string;
+    readonly mode: RuntimeIsolationMode;
+    readonly state: RuntimeIsolationLeaseState;
+    readonly createdAt: string;
+    readonly stateChangedAt: string;
+    readonly expiresAt: string;
+    readonly releasedAt: string | null;
+    readonly resources: RuntimeIsolationResources;
+}
+export interface RuntimeIsolationLeaseInput {
+    readonly leaseId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly worktreeKey: string;
+    readonly worktreePath: string;
+    readonly mode: RuntimeIsolationMode;
+    readonly expiresAt: string;
+    readonly resources: RuntimeIsolationResources;
+    readonly createdAt?: string;
+}
+export declare function createRuntimeIsolationLease(input: RuntimeIsolationLeaseInput): RuntimeIsolationLease;
+export declare function transitionRuntimeIsolationLease(lease: RuntimeIsolationLease, nextState: RuntimeIsolationLeaseState, occurredAt?: string): RuntimeIsolationLease;
+export declare function renewRuntimeIsolationLease(lease: RuntimeIsolationLease, fencingToken: string, expiresAt: string): RuntimeIsolationLease | null;
+export declare function withRuntimeIsolationResources(lease: RuntimeIsolationLease, resources: RuntimeIsolationResources): RuntimeIsolationLease;
+export declare function validRuntimeIsolationLease(value: unknown): value is RuntimeIsolationLease;

package/dist/runtime/runtime-isolation-lease.js

@@ -0,0 +1,158 @@
+export const runtimeIsolationLeaseStates = [
+    "reserved",
+    "starting",
+    "active",
+    "releasing",
+    "released",
+    "degraded",
+];
+const allowedTransitions = {
+    reserved: new Set(["starting", "releasing", "degraded"]),
+    starting: new Set(["active", "releasing", "degraded"]),
+    active: new Set(["releasing", "degraded"]),
+    releasing: new Set(["released", "degraded"]),
+    released: new Set(),
+    degraded: new Set(["releasing"]),
+};
+export function createRuntimeIsolationLease(input) {
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    const lease = {
+        schemaVersion: 1,
+        leaseId: input.leaseId,
+        dispatchAttemptId: input.dispatchAttemptId,
+        executionLeaseId: input.executionLeaseId,
+        fencingToken: input.fencingToken,
+        runnerId: input.runnerId,
+        runnerInstanceId: input.runnerInstanceId,
+        worktreeKey: input.worktreeKey,
+        worktreePath: input.worktreePath,
+        mode: input.mode,
+        state: "reserved",
+        createdAt,
+        stateChangedAt: createdAt,
+        expiresAt: input.expiresAt,
+        releasedAt: null,
+        resources: input.resources,
+    };
+    if (!validRuntimeIsolationLease(lease)) {
+        throw new Error("runtime_lease_invalid: lease identity, lifetime, or resources are invalid.");
+    }
+    return lease;
+}
+export function transitionRuntimeIsolationLease(lease, nextState, occurredAt = new Date().toISOString()) {
+    if (lease.state === nextState)
+        return lease;
+    if (!allowedTransitions[lease.state].has(nextState) || !validTimestamp(occurredAt)) {
+        throw new Error(`runtime_lease_transition_invalid: cannot transition ${lease.state} to ${nextState}.`);
+    }
+    const transitioned = {
+        ...lease,
+        state: nextState,
+        stateChangedAt: occurredAt,
+        releasedAt: nextState === "released" ? occurredAt : null,
+    };
+    if (!validRuntimeIsolationLease(transitioned)) {
+        throw new Error("runtime_lease_invalid: transitioned lease is invalid.");
+    }
+    return transitioned;
+}
+export function renewRuntimeIsolationLease(lease, fencingToken, expiresAt) {
+    if (lease.fencingToken !== fencingToken || lease.state === "released" || !validTimestamp(expiresAt))
+        return null;
+    const renewed = { ...lease, expiresAt };
+    return validRuntimeIsolationLease(renewed) ? renewed : null;
+}
+export function withRuntimeIsolationResources(lease, resources) {
+    if (lease.state === "released") {
+        throw new Error("runtime_lease_transition_invalid: released leases cannot acquire resources.");
+    }
+    const updated = { ...lease, resources };
+    if (!validRuntimeIsolationLease(updated)) {
+        throw new Error("runtime_lease_invalid: resources are invalid.");
+    }
+    return updated;
+}
+export function validRuntimeIsolationLease(value) {
+    if (!isRecord(value)
+        || value.schemaVersion !== 1
+        || !isUuid(value.leaseId)
+        || !isUuid(value.dispatchAttemptId)
+        || !isUuid(value.executionLeaseId)
+        || !isUuid(value.fencingToken)
+        || !isUuid(value.runnerId)
+        || !isUuid(value.runnerInstanceId)
+        || !boundedText(value.worktreeKey, 255)
+        || !boundedText(value.worktreePath, 4096)
+        || (value.mode !== "docker" && value.mode !== "host")
+        || !runtimeIsolationLeaseStates.includes(value.state)
+        || !validTimestamp(value.createdAt)
+        || !validTimestamp(value.stateChangedAt)
+        || !validTimestamp(value.expiresAt)
+        || Date.parse(value.stateChangedAt) < Date.parse(value.createdAt)
+        || Date.parse(value.expiresAt) < Date.parse(value.createdAt)
+        || (value.state === "released") !== validTimestamp(value.releasedAt)) {
+        return false;
+    }
+    if (value.releasedAt !== null && Date.parse(value.releasedAt) < Date.parse(value.createdAt))
+        return false;
+    return validResources(value.resources, value.mode);
+}
+function validResources(value, mode) {
+    if (!isRecord(value)
+        || !nonNegativeInteger(value.memoryReservationBytes)
+        || !nonNegativeInteger(value.cpuMillis)
+        || !nonNegativeInteger(value.pids)
+        || !Array.isArray(value.ports) || value.ports.length > 64
+        || !Array.isArray(value.paths) || value.paths.length > 64
+        || !Array.isArray(value.dockerResources) || value.dockerResources.length > 128
+        || !Array.isArray(value.singletonKeys) || value.singletonKeys.length > 64
+        || (value.processSupervisorId !== null && !boundedText(value.processSupervisorId, 255))) {
+        return false;
+    }
+    if (value.ports.some(port => !validPort(port))
+        || value.paths.some(entry => !isRecord(entry) || !boundedText(entry.path, 4096) || !boundedText(entry.role, 128))
+        || value.singletonKeys.some(key => !boundedText(key, 255))
+        || value.dockerResources.some(resource => !validDockerResource(resource))) {
+        return false;
+    }
+    return mode === "docker" || value.dockerResources.length === 0;
+}
+function validPort(value) {
+    return isRecord(value)
+        && boundedText(value.name, 128)
+        && (value.protocol === "tcp" || value.protocol === "udp")
+        && (value.hostIp === "127.0.0.1" || value.hostIp === "::1")
+        && validPortNumber(value.hostPort)
+        && validPortNumber(value.targetPort);
+}
+function validDockerResource(value) {
+    return isRecord(value)
+        && (value.type === "container" || value.type === "network" || value.type === "volume")
+        && boundedText(value.name, 255)
+        && boundedText(value.role, 128)
+        && (value.id === undefined || value.id === null || boundedText(value.id, 255));
+}
+function validPortNumber(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= 65535;
+}
+function nonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function validTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function boundedText(value, maximumLength) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximumLength
+        && Array.from(value).every((character) => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint > 31 && codePoint !== 127;
+        });
+}
+function isUuid(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/runtime/workspace-resource-estimator.d.ts

@@ -0,0 +1,17 @@
+export declare const minimumWorkspaceEstimateBytes: number;
+export declare const architectMinimumWorkspaceEstimateBytes: number;
+export interface RepositoryWorkspaceFootprint {
+    readonly sourceBytes: number;
+    readonly hasNode: boolean;
+    readonly hasDotNet: boolean;
+    readonly hasBrowser: boolean;
+    readonly serviceCount: number;
+}
+export interface WorkspaceEstimateHints {
+    readonly role?: string | null;
+    readonly serviceCount?: number;
+    readonly browser?: boolean;
+}
+export declare function estimateWorkspaceBytesFromRepo(repoPath: string, hints?: WorkspaceEstimateHints): Promise<number>;
+export declare function calculateWorkspaceBytes(footprint: RepositoryWorkspaceFootprint, role?: string | null): number;
+export declare function measureRepositoryWorkspace(repoPath: string): Promise<RepositoryWorkspaceFootprint>;