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

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

@@ -0,0 +1,217 @@
+import type { RunOnceDispatchPacket } from "../session/session.types.js";
+import { type ProviderProcessRunner } from "../session/provider-cli/provider-cli.process.js";
+import { type RuntimeIsolationLease } from "./runtime-isolation-lease.js";
+import { type LoadedHostRuntimeContract } from "./host-runtime-contract.js";
+import { HostPortBroker } from "./host-port-broker.js";
+import { NodeHostRuntimeAdapter, type NodeRuntimeAdapterLaunch, type NodeRuntimeCommand, type NodeRuntimeCommandLauncher } from "./node-host-runtime-adapter.js";
+import type { AttemptProcessTreeMemoryTelemetry } from "./attempt-process-supervisor.js";
+import { AttemptProcessSupervisorRegistry } from "./attempt-process-supervisor-registry.js";
+import { type AttemptDatabaseBroker } from "./attempt-database-broker.js";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+import { type MemoryAdmissionDiagnostics } from "./memory-capacity.js";
+import { PlaywrightHostRuntimeAdapter } from "./playwright-host-runtime-adapter.js";
+import { HostParallelPromotionStore } from "./host-runtime-promotion.js";
+import { type HostProcessRecovery } from "../shared/process/host-process-recovery.js";
+export interface HostRuntimeLeaseStart {
+    readonly lease: RuntimeIsolationLease;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly runtimeContract: LoadedHostRuntimeContract;
+    readonly executionClass: HostRuntimeExecutionClass;
+}
+export interface HostRuntimeAdmissionCheckpoint {
+    readonly code: "host_runtime_serial_admission_waiting" | "host_runtime_prepared_probe_started" | "host_runtime_prepared_probe_progress" | "host_runtime_prepared_probe_completed" | "host_runtime_prepared_admission_waiting" | "host_runtime_prepared_admission_acquired";
+    readonly message: string;
+    readonly expiresAt: string;
+}
+export type HostRuntimeAdmissionCheckpointHandler = (checkpoint: HostRuntimeAdmissionCheckpoint) => void | Promise<void>;
+export interface HostRuntimeProjectCheckpoint {
+    readonly code: "host_runtime_build_started" | "host_runtime_build_cached" | "host_runtime_build_completed" | "host_runtime_database_provisioned";
+    readonly message: string;
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+export type HostRuntimeProjectCheckpointHandler = (checkpoint: HostRuntimeProjectCheckpoint) => void | Promise<void>;
+export type HostRuntimeExecutionClass = "analysis_only" | "managed_runtime";
+export type HostRuntimeSafetyClass = "host_serial_only" | "host_parallel_candidate" | "host_parallel_safe";
+export interface HostRuntimeProjectCapacitySnapshot {
+    readonly repoId: string;
+    readonly safetyClass: HostRuntimeSafetyClass;
+    readonly activeAttempts: number;
+    readonly reservedAttempts: number;
+    readonly waitingAttempts: number;
+    readonly degradedAttempts: number;
+    readonly runtimeContractFingerprint?: string | null;
+    readonly runtimeContractSource?: "project" | "derived" | null;
+    readonly promotedAt?: string | null;
+}
+export interface HostRuntimeCapacitySnapshot {
+    readonly preparedWorktreeReadiness?: boolean;
+    readonly activeAttempts: number;
+    readonly reservedAttempts: number;
+    readonly waitingAttempts: number;
+    readonly degradedAttempts: number;
+    readonly exclusiveReservations: number;
+    readonly sharedReservations: number;
+    readonly hardMaxAttempts: number;
+    readonly effectiveMaxAttempts: number;
+    readonly availableAttempts: number;
+    readonly totalMemoryBytes: number;
+    readonly availableMemoryBytes: number;
+    readonly hostReserveBytes: number;
+    readonly availableCpuMillis: number;
+    readonly availableWorkspaceBytes: number;
+    readonly activeReservationMemoryBytes: number;
+    readonly memoryAdmission: MemoryAdmissionDiagnostics;
+    readonly unavailableCode?: string | null;
+    readonly unavailableReason?: string | null;
+    readonly projects: readonly HostRuntimeProjectCapacitySnapshot[];
+}
+export interface HostRuntimeReapOptions {
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly nowMs?: number;
+}
+export interface HostRuntimeReapReport {
+    readonly examined: number;
+    readonly reaped: number;
+    readonly processesTerminated: number;
+    readonly reusedPidsProtected: number;
+    readonly degraded: number;
+    /**
+     * Active attempts of a previous runner instance whose every supervised
+     * process tree was proved absent, terminated or PID-reused. Forge may settle
+     * these exact attempts instead of leaving their launch outcome unknown.
+     */
+    readonly recoveredAttempts?: readonly HostRuntimeRecoveredAttempt[];
+}
+export interface HostRuntimeRecoveredAttempt {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+}
+export interface HostNodeRuntimeLaunch<T> extends NodeRuntimeAdapterLaunch<T> {
+    readonly runtimeLease: RuntimeIsolationLease;
+}
+export interface HostRuntimeLeaseRuntime {
+    acquirePreparation?(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    acquire(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    start(dispatch: RunOnceDispatchPacket, worktreePath: string, signal?: AbortSignal, onAdmissionCheckpoint?: HostRuntimeAdmissionCheckpointHandler): Promise<HostRuntimeLeaseStart>;
+    startConfiguredProject(dispatchAttemptId: string, fencingToken: string, signal?: AbortSignal, onProjectCheckpoint?: HostRuntimeProjectCheckpointHandler): Promise<HostRuntimeLeaseStart>;
+    updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
+    providerProcessRunner?(dispatchAttemptId: string, fencingToken: string): ProviderProcessRunner | null;
+    providerMemoryTelemetry?(dispatchAttemptId: string, fencingToken: string): AttemptProcessTreeMemoryTelemetry | null;
+    release(dispatchAttemptId: string, fencingToken: string): Promise<RuntimeIsolationLease | null>;
+    invalidatePromotion?(repoId: string, scope?: "all" | "discovery"): Promise<void>;
+    hasForegroundDemand?(): boolean;
+    reap?(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport>;
+    snapshot?(): HostRuntimeCapacitySnapshot;
+}
+export interface HostCapacityResourceSample {
+    readonly totalMemoryBytes: number;
+    readonly availableMemoryBytes: number;
+    readonly totalCpuMillis: number;
+    readonly availableWorkspaceBytes: number;
+}
+export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime {
+    private readonly stateRoot;
+    private readonly processSupervisors;
+    private readonly processRunner;
+    private readonly listenerInspector;
+    private readonly promotionStore;
+    private readonly playwrightAdapter;
+    private readonly processRecovery;
+    private readonly capacityResourceSample?;
+    private readonly databaseBroker;
+    private readonly preparedReadiness;
+    private readonly active;
+    private readonly pendingRenewals;
+    private readonly acquiringAdmissions;
+    private readonly admissions;
+    private readonly singletonOwners;
+    private readonly singletonWaiters;
+    private readonly parallelProjectOwners;
+    private readonly parallelProjectWaiters;
+    private readonly capacityReservations;
+    private readonly capacityWaiters;
+    private capacityWaiterScanCursor;
+    private readonly backgroundAdmissionWaiters;
+    private readonly degraded;
+    private readonly knownPromotions;
+    private ledgerWriteTail;
+    private workspaceAvailableBytes;
+    private readonly portBroker;
+    private readonly nodeAdapter;
+    private readonly capacityConfiguration;
+    private readonly memoryAvailability;
+    private readonly executionRoot;
+    constructor(stateRoot: string, portBroker?: HostPortBroker, nodeAdapter?: NodeHostRuntimeAdapter, processSupervisors?: AttemptProcessSupervisorRegistry, processRunner?: ProviderProcessRunner, listenerInspector?: HostListenerInspector, promotionStore?: HostParallelPromotionStore, playwrightAdapter?: PlaywrightHostRuntimeAdapter, processRecovery?: HostProcessRecovery, capacityResourceSample?: HostCapacityResourceSample | undefined, executionRoot?: string, databaseBroker?: AttemptDatabaseBroker | null);
+    reap(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport>;
+    snapshot(): HostRuntimeCapacitySnapshot;
+    hasForegroundDemand(): boolean;
+    acquirePreparation(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    acquire(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    private reserveHostCapacity;
+    private reserveBackgroundAdmission;
+    private hostCapacityAvailable;
+    private hostCapacityImpossibleReason;
+    private hostResourceSnapshot;
+    private refreshWorkspaceCapacity;
+    private releaseHostCapacity;
+    private drainCapacityWaiters;
+    private capacityWaitersForScan;
+    private detachCapacityWaiter;
+    private reserveSingletonKeys;
+    private reserveParallelProject;
+    private upgradeParallelProjectToSingleton;
+    start(dispatch: RunOnceDispatchPacket, worktreePath: string, signal?: AbortSignal, onAdmissionCheckpoint?: HostRuntimeAdmissionCheckpointHandler): Promise<HostRuntimeLeaseStart>;
+    updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
+    startConfiguredProject(dispatchAttemptId: string, fencingToken: string, signal?: AbortSignal, onProjectCheckpoint?: HostRuntimeProjectCheckpointHandler): Promise<HostRuntimeLeaseStart>;
+    providerProcessRunner(dispatchAttemptId: string, fencingToken: string): ProviderProcessRunner | null;
+    private markCapacityReservationRunning;
+    providerMemoryTelemetry(dispatchAttemptId: string, fencingToken: string): AttemptProcessTreeMemoryTelemetry | null;
+    private promoteVerifiedRuntime;
+    launchNodeRuntime<T>(dispatchAttemptId: string, fencingToken: string, portName: string, command: NodeRuntimeCommand, launcher: NodeRuntimeCommandLauncher<T>, signal?: AbortSignal): Promise<HostNodeRuntimeLaunch<T>>;
+    release(dispatchAttemptId: string, fencingToken: string, preservePreparation?: boolean): Promise<RuntimeIsolationLease | null>;
+    private readLedgers;
+    private recoverPersistedProcesses;
+    private markLedgerDegraded;
+    private rememberDegraded;
+    private forgetDegraded;
+    private attemptRoot;
+    private writeLedger;
+    private writeLedgerAtomic;
+    private ledgerPath;
+    private singletonKeysAvailable;
+    private assignSingletonKeys;
+    private releaseSingletonKeys;
+    private convertSingletonToParallelProject;
+    private parallelProjectOwned;
+    private parallelProjectAvailable;
+    private assignParallelProject;
+    private releaseParallelProjectNoDrain;
+    private releaseParallelProjects;
+    private deleteAdmission;
+    private renewAdmissionWaiterDeadline;
+    private clearPendingRenewal;
+    private cancelAdmissionWaiters;
+    private drainSingletonWaiters;
+    private drainParallelProjectWaiters;
+    private drainBackgroundAdmissionWaiters;
+    private refreshKnownPromotions;
+    invalidatePromotion(repoId: string, scope?: "all" | "discovery"): Promise<void>;
+    private drainAdmissionWaiters;
+    private reconcileReservationOwners;
+    private reservationOwnerIsLive;
+    private hasAttemptRepresentation;
+}
+export declare class HostRuntimeLeaseCleanupError extends Error {
+    readonly lease: RuntimeIsolationLease;
+    constructor(lease: RuntimeIsolationLease, cause: unknown);
+}
+export declare class HostRuntimeAdmissionExpiredError extends Error {
+    constructor();
+}
+export declare class HostRuntimeCapacityRequestImpossibleError extends Error {
+    constructor(reason: string);
+}
+export declare function hostRuntimeEventResources(lease: RuntimeIsolationLease, runtimeContract?: LoadedHostRuntimeContract, executionClass?: HostRuntimeExecutionClass): Record<string, unknown>;
+export declare function hostRuntimeSingletonKeys(dispatch: RunOnceDispatchPacket): readonly string[];