@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.bfa11ebe98c6

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

@@ -0,0 +1,32 @@
+import type { LoadedHostRuntimeContract } from "./host-runtime-contract.js";
+export interface HostParallelPromotionRecord {
+    readonly schemaVersion: 1;
+    readonly repoId: string;
+    readonly runtimeContractFingerprint: string;
+    readonly inputCommitSha?: string | null;
+    readonly sourceFingerprint?: string;
+    readonly runtimeContractSource?: "project" | "derived";
+    readonly observedAt: string;
+    readonly observedDispatchAttemptId: string;
+    readonly verifiedPortNames: readonly string[];
+}
+export interface HostParallelProofIdentity {
+    readonly runtimeContractFingerprint: string;
+    readonly inputCommitSha: string;
+    readonly sourceFingerprint?: string;
+}
+/** Persists only observed, contract-bound host parallel-safety evidence. */
+export declare class HostParallelPromotionStore {
+    private readonly stateRoot;
+    constructor(stateRoot: string);
+    load(repoId: string, identity?: HostParallelProofIdentity): Promise<HostParallelPromotionRecord | null>;
+    list(): Promise<readonly HostParallelPromotionRecord[]>;
+    observe(repoId: string, runtimeContract: LoadedHostRuntimeContract, dispatchAttemptId: string, verifiedPortNames: readonly string[], inputCommitSha?: string, sourceFingerprint?: string): Promise<HostParallelPromotionRecord>;
+    private writeRecord;
+    private pruneVersions;
+    invalidate(repoId: string, scope?: "all" | "discovery"): 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,206 @@
+import { createHash, randomUUID } 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, identity) {
+        const normalizedRepoId = normalizeRepoId(repoId);
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.recordPath(normalizedRepoId, identity), "utf8"));
+            return validRecord(parsed, normalizedRepoId)
+                && (!identity || matchesIdentity(parsed, identity)) ? 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, inputCommitSha, sourceFingerprint) {
+        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),
+            inputCommitSha: inputCommitSha ?? null,
+            ...(sourceFingerprint ? { sourceFingerprint } : {}),
+            runtimeContractSource: runtimeContract.source === "project" ? "project" : "derived",
+            observedAt: new Date().toISOString(),
+            observedDispatchAttemptId: normalizedUuid(dispatchAttemptId, "dispatch attempt"),
+            verifiedPortNames: observedPorts,
+        };
+        if (inputCommitSha) {
+            await this.writeRecord(this.recordPath(normalizedRepoId, {
+                runtimeContractFingerprint: record.runtimeContractFingerprint, inputCommitSha, sourceFingerprint,
+            }), record);
+        }
+        await this.writeRecord(this.recordPath(normalizedRepoId), record);
+        await this.pruneVersions(normalizedRepoId);
+        return record;
+    }
+    async writeRecord(target, record) {
+        const root = path.dirname(target);
+        await ensurePrivateDirectory(root);
+        const temporary = `${target}.${randomUUID()}.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);
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async pruneVersions(repoId) {
+        const target = this.recordPath(repoId);
+        const root = path.dirname(target);
+        const prefix = path.basename(target, ".json") + ".";
+        const versions = (await fs.readdir(root)).filter(name => name.startsWith(prefix)
+            && /^[0-9a-f]{64}\.[0-9a-f]{64}\.json$/u.test(name));
+        if (versions.length <= 128)
+            return;
+        const dated = await Promise.all(versions.map(async (name) => ({ name,
+            at: await fs.stat(path.join(root, name)).then(stat => stat.mtimeMs, () => Number.MAX_SAFE_INTEGER) })));
+        for (const entry of dated.sort((a, b) => b.at - a.at).slice(128)) {
+            await fs.rm(path.join(root, entry.name), { force: true });
+        }
+    }
+    async invalidate(repoId, scope = "all") {
+        const target = this.recordPath(normalizeRepoId(repoId));
+        await fs.rm(target, { force: true });
+        // Background/default-branch discovery must not erase proofs bound to other
+        // prepared sources. Actual containment/cleanup degradation invalidates all.
+        if (scope === "discovery")
+            return;
+        const prefix = path.basename(target, ".json") + ".";
+        const entries = await fs.readdir(path.dirname(target)).catch((error) => {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        for (const entry of entries.filter(name => name.startsWith(prefix) && /^[0-9a-f]{64}\.[0-9a-f]{64}\.json$/u.test(name))) {
+            await fs.rm(path.join(path.dirname(target), entry), { force: true });
+        }
+    }
+    recordPath(normalizedRepoId, identity) {
+        const key = createHash("sha256").update(normalizedRepoId).digest("hex");
+        const version = identity ? `.${createHash("sha256").update(JSON.stringify([
+            identity.runtimeContractFingerprint, identity.inputCommitSha, identity.sourceFingerprint ?? null,
+        ])).digest("hex")}` : "";
+        return path.join(this.stateRoot, "runtime-promotion", "host", `${key}${version}.json`);
+    }
+}
+function matchesIdentity(record, identity) {
+    return record.runtimeContractFingerprint === identity.runtimeContractFingerprint
+        && record.inputCommitSha === identity.inputCommitSha
+        && record.sourceFingerprint === identity.sourceFingerprint;
+}
+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,70 @@
+export declare const memoryAdmissionPolicyVersion = "memory-admission-v2";
+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;
+    /** 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. Ambient host use must not
+ * also be folded into committedMemoryBytes: it is already reflected in the OS
+ * sample, and doing both permanently double-charges long-lived host processes.
+ * The total-memory ceiling independently caps Forge's own reservations.
+ */
+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,123 @@
+const GiB = 1024 ** 3;
+export const memoryAdmissionPolicyVersion = "memory-admission-v2";
+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. Ambient host use must not
+ * also be folded into committedMemoryBytes: it is already reflected in the OS
+ * sample, and doing both permanently double-charges long-lived host processes.
+ * The total-memory ceiling independently caps Forge's own reservations.
+ */
+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/native-test-postgres-fallback.d.ts

@@ -0,0 +1,25 @@
+export declare const nativeTestPostgresFallbackConfigEnvironment = "FORGE_NATIVE_TEST_POSTGRES_CONFIG";
+export declare const nativeTestPostgresFallbackFileName = "native-test-postgres.json";
+export declare const nativeTestPostgresFallbackDatabaseMode = "native_fallback";
+/**
+ * A dedicated, operator-provisioned PostgreSQL cluster that runner-authored .NET
+ * test tiers may use only while the Docker engine is unavailable. The cluster
+ * must hold nothing but disposable test databases, so its capability carries no
+ * more authority than the attempt-private container it replaces.
+ */
+export interface NativeTestPostgresFallback {
+    readonly connectionString: string;
+    readonly endpoint: string;
+}
+export declare class NativeTestPostgresFallbackError extends Error {
+    readonly code = "native_test_postgres_fallback_invalid";
+    constructor(detail: string);
+}
+export declare function resolveNativeTestPostgresFallbackPath(): string;
+/** The operator's fallback file when one has been provisioned on this host. */
+export declare function configuredNativeTestPostgresFallbackPath(): string | null;
+/** Returns null when no fallback is configured; throws when one is configured unsafely. */
+export declare function readNativeTestPostgresFallback(configPath?: string): NativeTestPostgresFallback | null;
+export declare function parseNativeTestPostgresFallback(connectionString: string): NativeTestPostgresFallback;
+/** Environment for one runner-authored .NET test process using the fallback. */
+export declare function nativeTestPostgresFallbackEnvironment(fallback: NativeTestPostgresFallback): Readonly<Record<string, string>>;

package/dist/runtime/native-test-postgres-fallback.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveLocalConfigPath } from "../cli/local-config.js";
+import { hostRuntimeLegacyTestPostgresEnvironment, hostRuntimeTestPostgresAdminEnvironment, } from "./host-runtime-contract.js";
+export const nativeTestPostgresFallbackConfigEnvironment = "FORGE_NATIVE_TEST_POSTGRES_CONFIG";
+export const nativeTestPostgresFallbackFileName = "native-test-postgres.json";
+export const nativeTestPostgresFallbackDatabaseMode = "native_fallback";
+const defaultPostgresPort = 5432;
+const loopbackHosts = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+export class NativeTestPostgresFallbackError extends Error {
+    code = "native_test_postgres_fallback_invalid";
+    constructor(detail) {
+        super(`native_test_postgres_fallback_invalid: ${detail}`);
+        this.name = "NativeTestPostgresFallbackError";
+    }
+}
+export function resolveNativeTestPostgresFallbackPath() {
+    const configured = process.env[nativeTestPostgresFallbackConfigEnvironment]?.trim();
+    return configured
+        ? path.resolve(configured)
+        : path.join(path.dirname(resolveLocalConfigPath()), nativeTestPostgresFallbackFileName);
+}
+/** The operator's fallback file when one has been provisioned on this host. */
+export function configuredNativeTestPostgresFallbackPath() {
+    const configPath = resolveNativeTestPostgresFallbackPath();
+    return fs.existsSync(configPath) ? configPath : null;
+}
+/** Returns null when no fallback is configured; throws when one is configured unsafely. */
+export function readNativeTestPostgresFallback(configPath = resolveNativeTestPostgresFallbackPath()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch {
+        throw new NativeTestPostgresFallbackError(`${configPath} is not valid JSON.`);
+    }
+    if (document.schemaVersion !== 1 || typeof document.connectionString !== "string") {
+        throw new NativeTestPostgresFallbackError(`${configPath} must contain schemaVersion 1 and a connectionString.`);
+    }
+    return parseNativeTestPostgresFallback(document.connectionString);
+}
+export function parseNativeTestPostgresFallback(connectionString) {
+    const fields = new Map();
+    for (const segment of connectionString.split(";")) {
+        const separator = segment.indexOf("=");
+        if (separator <= 0)
+            continue;
+        fields.set(segment.slice(0, separator).trim().toLowerCase().replaceAll(" ", ""), segment.slice(separator + 1).trim());
+    }
+    const host = (fields.get("host") ?? fields.get("server") ?? "").toLowerCase();
+    if (!loopbackHosts.has(host)) {
+        throw new NativeTestPostgresFallbackError("the fallback must use a single loopback host.");
+    }
+    const database = (fields.get("database") ?? fields.get("db") ?? fields.get("initialcatalog") ?? "").toLowerCase();
+    if (database !== "postgres") {
+        throw new NativeTestPostgresFallbackError("the fallback must connect to the 'postgres' administrative database.");
+    }
+    if (fields.get("searchpath")) {
+        throw new NativeTestPostgresFallbackError("the fallback must not set a search path.");
+    }
+    const port = Number.parseInt(fields.get("port") ?? "", 10);
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+        throw new NativeTestPostgresFallbackError("the fallback must name an explicit port.");
+    }
+    if (port === defaultPostgresPort) {
+        // The default port is where developer databases live; a dedicated test
+        // cluster must be provisioned on its own port.
+        throw new NativeTestPostgresFallbackError(`the fallback must not use the default PostgreSQL port ${defaultPostgresPort}; provision a dedicated test cluster.`);
+    }
+    if (!(fields.get("username") ?? fields.get("userid") ?? fields.get("user"))) {
+        throw new NativeTestPostgresFallbackError("the fallback must name a dedicated test role.");
+    }
+    return { connectionString: connectionString.trim(), endpoint: `${host}:${port}` };
+}
+/** Environment for one runner-authored .NET test process using the fallback. */
+export function nativeTestPostgresFallbackEnvironment(fallback) {
+    return {
+        [hostRuntimeTestPostgresAdminEnvironment]: fallback.connectionString,
+        [hostRuntimeLegacyTestPostgresEnvironment]: fallback.connectionString,
+        FORGE_MANAGED_VERIFICATION_DATABASE_MODE: nativeTestPostgresFallbackDatabaseMode,
+    };
+}

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;