@loucompanion/forge-bridge 0.1.3-dev.d46a8e73d03d → 0.1.3-dev.e7b62d8fdd33

package/dist/runtime/host-runtime-promotion.d.ts

@@ -0,0 +1,23 @@
+import type { LoadedHostRuntimeContract } from "./host-runtime-contract.js";
+export interface HostParallelPromotionRecord {
+    readonly schemaVersion: 1;
+    readonly repoId: string;
+    readonly runtimeContractFingerprint: string;
+    readonly runtimeContractSource?: "project" | "derived";
+    readonly observedAt: string;
+    readonly observedDispatchAttemptId: string;
+    readonly verifiedPortNames: readonly string[];
+}
+/** Persists only observed, contract-bound host parallel-safety evidence. */
+export declare class HostParallelPromotionStore {
+    private readonly stateRoot;
+    constructor(stateRoot: string);
+    load(repoId: string): Promise<HostParallelPromotionRecord | null>;
+    list(): Promise<readonly HostParallelPromotionRecord[]>;
+    observe(repoId: string, runtimeContract: LoadedHostRuntimeContract, dispatchAttemptId: string, verifiedPortNames: readonly string[]): Promise<HostParallelPromotionRecord>;
+    invalidate(repoId: string): Promise<void>;
+    private recordPath;
+}
+export declare function hostRuntimeContractFingerprint(runtimeContract: LoadedHostRuntimeContract): string;
+export declare function hostRuntimeParallelEligible(runtimeContract: LoadedHostRuntimeContract): boolean;
+export declare function configuredLaunchPortNames(runtimeContract: LoadedHostRuntimeContract): readonly string[];

package/dist/runtime/host-runtime-promotion.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+/** Persists only observed, contract-bound host parallel-safety evidence. */
+export class HostParallelPromotionStore {
+    stateRoot;
+    constructor(stateRoot) {
+        this.stateRoot = stateRoot;
+    }
+    async load(repoId) {
+        const normalizedRepoId = normalizeRepoId(repoId);
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.recordPath(normalizedRepoId), "utf8"));
+            return validRecord(parsed, normalizedRepoId) ? parsed : null;
+        }
+        catch (error) {
+            if (error.code === "ENOENT" || error instanceof SyntaxError)
+                return null;
+            throw error;
+        }
+    }
+    async list() {
+        const root = path.join(this.stateRoot, "runtime-promotion", "host");
+        let entries;
+        try {
+            entries = await fs.readdir(root);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        const records = [];
+        for (const entry of entries.filter(value => /^[0-9a-f]{64}\.json$/u.test(value)).slice(0, 4096)) {
+            try {
+                const parsed = JSON.parse(await fs.readFile(path.join(root, entry), "utf8"));
+                const repoId = typeof parsed.repoId === "string" ? normalizeRepoId(parsed.repoId) : "";
+                if (repoId && validRecord(parsed, repoId))
+                    records.push(parsed);
+            }
+            catch (error) {
+                if (!(error instanceof SyntaxError))
+                    throw error;
+            }
+        }
+        return records.sort((left, right) => left.repoId.localeCompare(right.repoId));
+    }
+    async observe(repoId, runtimeContract, dispatchAttemptId, verifiedPortNames) {
+        if (!hostRuntimeParallelEligible(runtimeContract)) {
+            throw new Error("host_parallel_promotion_ineligible: the runtime contract is not eligible for parallel host execution.");
+        }
+        const requiredPorts = configuredLaunchPortNames(runtimeContract);
+        const observedPorts = [...new Set(verifiedPortNames)].sort((left, right) => left.localeCompare(right));
+        if (requiredPorts.length !== observedPorts.length
+            || requiredPorts.some((name, index) => name !== observedPorts[index])) {
+            throw new Error("host_parallel_promotion_unverified: every configured runtime listener must pass its assigned-port probe.");
+        }
+        const normalizedRepoId = normalizeRepoId(repoId);
+        const record = {
+            schemaVersion: 1,
+            repoId: normalizedRepoId,
+            runtimeContractFingerprint: hostRuntimeContractFingerprint(runtimeContract),
+            runtimeContractSource: runtimeContract.source === "project" ? "project" : "derived",
+            observedAt: new Date().toISOString(),
+            observedDispatchAttemptId: normalizedUuid(dispatchAttemptId, "dispatch attempt"),
+            verifiedPortNames: observedPorts,
+        };
+        const target = this.recordPath(normalizedRepoId);
+        const root = path.dirname(target);
+        await ensurePrivateDirectory(root);
+        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            const handle = await fs.open(temporary, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await fs.rename(temporary, target);
+            return record;
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async invalidate(repoId) {
+        await fs.rm(this.recordPath(normalizeRepoId(repoId)), { force: true });
+    }
+    recordPath(normalizedRepoId) {
+        const key = createHash("sha256").update(normalizedRepoId).digest("hex");
+        return path.join(this.stateRoot, "runtime-promotion", "host", `${key}.json`);
+    }
+}
+export function hostRuntimeContractFingerprint(runtimeContract) {
+    const canonical = JSON.stringify({
+        schemaVersion: runtimeContract.contract.schemaVersion,
+        runtime: runtimeContract.contract.runtime,
+        derivedCandidateFingerprint: runtimeContract.source === "derived"
+            ? runtimeContract.discovery?.candidateFingerprint ?? null
+            : null,
+    });
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+export function hostRuntimeParallelEligible(runtimeContract) {
+    const runtime = runtimeContract.contract.runtime;
+    const launchedPorts = runtime.ports.filter(port => port.launch !== null);
+    return (runtimeContract.source === "project" || runtimeContract.source === "derived")
+        && runtime.hostConcurrency === "parallel"
+        && runtime.browserProfile === "isolated"
+        && runtime.singletonResources.length === 0
+        && launchedPorts.length > 0
+        && launchedPorts.length === runtime.ports.length
+        && launchedPorts.every(port => port.adapter !== null);
+}
+export function configuredLaunchPortNames(runtimeContract) {
+    return runtimeContract.contract.runtime.ports
+        .filter(port => port.launch !== null)
+        .map(port => port.name)
+        .sort((left, right) => left.localeCompare(right));
+}
+function validRecord(value, repoId) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.schemaVersion === 1
+        && record.repoId === repoId
+        && /^sha256:[0-9a-f]{64}$/u.test(record.runtimeContractFingerprint ?? "")
+        && Number.isFinite(Date.parse(record.observedAt ?? ""))
+        && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(record.observedDispatchAttemptId ?? "")
+        && Array.isArray(record.verifiedPortNames)
+        && record.verifiedPortNames.length > 0
+        && record.verifiedPortNames.length <= 16
+        && record.verifiedPortNames.every(name => typeof name === "string" && /^[a-z][a-z0-9_-]{0,63}$/u.test(name));
+}
+function normalizeRepoId(repoId) {
+    const normalized = repoId.trim().toLowerCase();
+    if (!normalized || normalized.length > 512 || Array.from(normalized).some(character => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint < 32 || codePoint === 127;
+    })) {
+        throw new Error("host_parallel_promotion_invalid: repository identity is invalid.");
+    }
+    return normalized;
+}
+function normalizedUuid(value, label) {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(normalized)) {
+        throw new Error(`host_parallel_promotion_invalid: ${label} must be a full UUID.`);
+    }
+    return normalized;
+}
+async function ensurePrivateDirectory(target) {
+    await fs.mkdir(target, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        await fs.chmod(target, 0o700);
+}

package/dist/runtime/memory-capacity.d.ts

@@ -0,0 +1,68 @@
+export declare const memoryAdmissionPolicyVersion = "memory-admission-v1";
+export declare const memoryAdmissionEquation = "max(0, min(stabilized_available - reserve - pending_commitment, total - reserve - committed))";
+export interface MemoryAdmissionDiagnostics {
+    readonly policyVersion: string;
+    readonly sampledAt: string;
+    readonly totalMemoryBytes: number;
+    readonly rawAvailableMemoryBytes: number;
+    readonly stabilizedAvailableMemoryBytes: number;
+    readonly reclaimableMemoryBytes: number | null;
+    readonly reclaimableMemorySource: "not_sampled_separately";
+    readonly controlPlaneMemoryBytes: number;
+    readonly reserveMemoryBytes: number;
+    readonly committedMemoryBytes: number;
+    readonly pendingCommitmentMemoryBytes: number;
+    readonly availableForAdmissionBytes: number;
+    readonly requestedMemoryBytes: number | null;
+    readonly shortfallMemoryBytes: number | null;
+    readonly decision: "snapshot" | "admitted" | "denied";
+    readonly equation: string;
+}
+export interface MemoryAdmissionInputs {
+    readonly sampledAt: string;
+    readonly totalMemoryBytes: number;
+    readonly rawAvailableMemoryBytes: number;
+    readonly stabilizedAvailableMemoryBytes: number;
+    readonly controlPlaneMemoryBytes: number;
+    readonly reserveMemoryBytes: number;
+    /** Ambient host use plus every committed Forge request, including pending requests. */
+    readonly committedMemoryBytes: number;
+    /** Commitments not yet reflected in the OS available-memory sample. */
+    readonly pendingCommitmentMemoryBytes: number;
+    readonly requestedMemoryBytes?: number | null;
+}
+/**
+ * One memory admission equation for Docker and managed-host capacity. The raw
+ * OS/daemon sample already reflects resident active children, so only pending
+ * commitments are charged against sampled headroom. The total-memory ceiling
+ * independently charges every commitment and prevents reservation overcommit.
+ */
+export declare function buildMemoryAdmissionDiagnostics(inputs: MemoryAdmissionInputs): MemoryAdmissionDiagnostics;
+export interface AdaptiveMemoryReserveOptions {
+    readonly explicitBytes?: number | null;
+    readonly floorBytes?: number | null;
+    readonly ceilingBytes?: number | null;
+    readonly percent?: number | null;
+}
+/**
+ * Derives a host safety reserve from the capacity domain it protects. An
+ * explicit operator value remains authoritative; otherwise the reserve scales
+ * with the sampled total inside conservative floors and ceilings.
+ */
+export declare function resolveAdaptiveMemoryReserveBytes(totalMemoryBytes: number, options?: AdaptiveMemoryReserveOptions): number;
+/**
+ * Applies pressure immediately while requiring durable recovery samples before
+ * increasing advertised capacity. This prevents one GC/cache sample from
+ * waking queued work and then immediately withdrawing the same capacity.
+ */
+export declare class RecoveryStabilizedMemory {
+    private readonly requiredRecoverySamples;
+    private readonly minimumRecoverySampleIntervalMs;
+    private stableBytes;
+    private recoveryFloorBytes;
+    private recoverySamples;
+    private lastRecoverySampleAt;
+    constructor(requiredRecoverySamples?: number, minimumRecoverySampleIntervalMs?: number);
+    observe(rawAvailableBytes: number, sampledAt?: number): number;
+    private resetRecovery;
+}

package/dist/runtime/memory-capacity.js

@@ -0,0 +1,121 @@
+const GiB = 1024 ** 3;
+export const memoryAdmissionPolicyVersion = "memory-admission-v1";
+export const memoryAdmissionEquation = "max(0, min(stabilized_available - reserve - pending_commitment, total - reserve - committed))";
+/**
+ * One memory admission equation for Docker and managed-host capacity. The raw
+ * OS/daemon sample already reflects resident active children, so only pending
+ * commitments are charged against sampled headroom. The total-memory ceiling
+ * independently charges every commitment and prevents reservation overcommit.
+ */
+export function buildMemoryAdmissionDiagnostics(inputs) {
+    const totalMemoryBytes = nonNegativeInteger(inputs.totalMemoryBytes);
+    const rawAvailableMemoryBytes = nonNegativeInteger(inputs.rawAvailableMemoryBytes);
+    const stabilizedAvailableMemoryBytes = nonNegativeInteger(inputs.stabilizedAvailableMemoryBytes);
+    const reserveMemoryBytes = nonNegativeInteger(inputs.reserveMemoryBytes);
+    const committedMemoryBytes = nonNegativeInteger(inputs.committedMemoryBytes);
+    const pendingCommitmentMemoryBytes = Math.min(committedMemoryBytes, nonNegativeInteger(inputs.pendingCommitmentMemoryBytes));
+    const requestedMemoryBytes = inputs.requestedMemoryBytes == null
+        ? null
+        : nonNegativeInteger(inputs.requestedMemoryBytes);
+    const availableForAdmissionBytes = Math.max(0, Math.min(stabilizedAvailableMemoryBytes - reserveMemoryBytes - pendingCommitmentMemoryBytes, totalMemoryBytes - reserveMemoryBytes - committedMemoryBytes));
+    const shortfallMemoryBytes = requestedMemoryBytes === null
+        ? null
+        : Math.max(0, requestedMemoryBytes - availableForAdmissionBytes);
+    return {
+        policyVersion: memoryAdmissionPolicyVersion,
+        sampledAt: inputs.sampledAt,
+        totalMemoryBytes,
+        rawAvailableMemoryBytes,
+        stabilizedAvailableMemoryBytes,
+        reclaimableMemoryBytes: null,
+        reclaimableMemorySource: "not_sampled_separately",
+        controlPlaneMemoryBytes: nonNegativeInteger(inputs.controlPlaneMemoryBytes),
+        reserveMemoryBytes,
+        committedMemoryBytes,
+        pendingCommitmentMemoryBytes,
+        availableForAdmissionBytes,
+        requestedMemoryBytes,
+        shortfallMemoryBytes,
+        decision: requestedMemoryBytes === null
+            ? "snapshot"
+            : shortfallMemoryBytes === 0 ? "admitted" : "denied",
+        equation: memoryAdmissionEquation,
+    };
+}
+/**
+ * Derives a host safety reserve from the capacity domain it protects. An
+ * explicit operator value remains authoritative; otherwise the reserve scales
+ * with the sampled total inside conservative floors and ceilings.
+ */
+export function resolveAdaptiveMemoryReserveBytes(totalMemoryBytes, options = {}) {
+    const explicit = positiveInteger(options.explicitBytes);
+    if (explicit !== null)
+        return explicit;
+    const total = Math.max(0, finiteInteger(totalMemoryBytes));
+    const floor = positiveInteger(options.floorBytes) ?? GiB;
+    const ceiling = Math.max(floor, positiveInteger(options.ceilingBytes) ?? 4 * GiB);
+    const percent = positiveNumber(options.percent) ?? 12.5;
+    const proportional = Math.floor(total * Math.min(50, percent) / 100);
+    return Math.max(floor, Math.min(ceiling, proportional));
+}
+/**
+ * Applies pressure immediately while requiring durable recovery samples before
+ * increasing advertised capacity. This prevents one GC/cache sample from
+ * waking queued work and then immediately withdrawing the same capacity.
+ */
+export class RecoveryStabilizedMemory {
+    requiredRecoverySamples;
+    minimumRecoverySampleIntervalMs;
+    stableBytes = null;
+    recoveryFloorBytes = null;
+    recoverySamples = 0;
+    lastRecoverySampleAt = null;
+    constructor(requiredRecoverySamples = 2, minimumRecoverySampleIntervalMs = 1_000) {
+        this.requiredRecoverySamples = requiredRecoverySamples;
+        this.minimumRecoverySampleIntervalMs = minimumRecoverySampleIntervalMs;
+    }
+    observe(rawAvailableBytes, sampledAt = Date.now()) {
+        const observed = Math.max(0, finiteInteger(rawAvailableBytes));
+        if (this.stableBytes === null) {
+            this.stableBytes = observed;
+            return observed;
+        }
+        if (observed <= this.stableBytes) {
+            this.stableBytes = observed;
+            this.resetRecovery();
+            return observed;
+        }
+        this.recoveryFloorBytes = this.recoveryFloorBytes === null
+            ? observed
+            : Math.min(this.recoveryFloorBytes, observed);
+        if (this.lastRecoverySampleAt !== null
+            && sampledAt - this.lastRecoverySampleAt < Math.max(0, this.minimumRecoverySampleIntervalMs)) {
+            return this.stableBytes;
+        }
+        this.recoverySamples += 1;
+        this.lastRecoverySampleAt = sampledAt;
+        if (this.recoverySamples < Math.max(1, this.requiredRecoverySamples)) {
+            return this.stableBytes;
+        }
+        this.stableBytes = this.recoveryFloorBytes ?? this.stableBytes;
+        this.resetRecovery();
+        return this.stableBytes;
+    }
+    resetRecovery() {
+        this.recoveryFloorBytes = null;
+        this.recoverySamples = 0;
+        this.lastRecoverySampleAt = null;
+    }
+}
+function finiteInteger(value) {
+    return Number.isFinite(value) ? Math.floor(value) : 0;
+}
+function positiveInteger(value) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : null;
+}
+function positiveNumber(value) {
+    return Number.isFinite(value) && value > 0 ? value : null;
+}
+function nonNegativeInteger(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}

package/dist/runtime/node-host-runtime-adapter.d.ts

@@ -0,0 +1,54 @@
+import { HostPortBroker, type HostPortLaunch, type HostPortLeaseOwner, type HostPortReservation } from "./host-port-broker.js";
+import { type HostRuntimePortAdapter, type HostRuntimePortConfig } from "./host-runtime-contract.js";
+export type HostListenerOwnership = "unbound" | "owned" | "foreign";
+export interface NodeRuntimeCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly environment?: Readonly<Record<string, string>>;
+}
+export interface NodeRuntimeLaunchRequest extends NodeRuntimeCommand {
+    readonly framework: HostRuntimePortAdapter;
+    readonly port: HostPortReservation;
+    readonly baseUrl: string;
+}
+export interface NodeRuntimeCommandLauncher<T> {
+    readonly launch: (request: NodeRuntimeLaunchRequest, signal?: AbortSignal) => Promise<T>;
+    readonly inspectListener: (value: T, request: NodeRuntimeLaunchRequest, signal?: AbortSignal) => Promise<HostListenerOwnership>;
+    readonly readinessDiagnostics?: (value: T) => Promise<NodeRuntimeReadinessDiagnostics>;
+    readonly stop: (value: T) => Promise<void>;
+}
+export interface NodeRuntimeReadinessDiagnostics {
+    readonly exited: boolean;
+    readonly exitCode?: number;
+    readonly stdoutTail?: string;
+    readonly stderrTail?: string;
+    readonly outputRevision?: number;
+}
+export interface NodeHostRuntimeAdapterOptions {
+    readonly readinessTimeoutMs?: number;
+    readonly hardReadinessTimeoutMs?: number;
+    readonly readinessPollIntervalMs?: number;
+    readonly httpProbeTimeoutMs?: number;
+    readonly probeHttp?: (url: string, timeoutMs: number, signal?: AbortSignal) => Promise<boolean>;
+}
+export interface NodeRuntimeAdapterLaunch<T> extends HostPortLaunch<T> {
+    readonly request: NodeRuntimeLaunchRequest;
+}
+/**
+ * Launches an explicitly configured HTTP project command beneath the caller's
+ * attempt supervisor. It never shells a command and never promotes a project
+ * by framework detection alone.
+ */
+export declare class NodeHostRuntimeAdapter {
+    private readonly broker;
+    private readonly readinessTimeoutMs;
+    private readonly hardReadinessTimeoutMs;
+    private readonly readinessPollIntervalMs;
+    private readonly httpProbeTimeoutMs;
+    private readonly probeHttp;
+    constructor(broker: HostPortBroker, options?: NodeHostRuntimeAdapterOptions);
+    launch<T>(owner: HostPortLeaseOwner, portConfig: HostRuntimePortConfig, command: NodeRuntimeCommand, launcher: NodeRuntimeCommandLauncher<T>, signal?: AbortSignal): Promise<NodeRuntimeAdapterLaunch<T>>;
+    private waitUntilReady;
+}
+export declare function buildNodeRuntimeLaunchRequest(framework: HostRuntimePortAdapter, portConfig: HostRuntimePortConfig, command: NodeRuntimeCommand, port: HostPortReservation): NodeRuntimeLaunchRequest;