@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/environment/runtime.d.ts

@@ -0,0 +1,505 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type MachineFloorConfigProjection } from '../config/load.js';
+import { ENVIRONMENT_CODES, type EnvironmentCommandOutcome, type EnvironmentObservation, type ExecutionFailureCode, type ExecutionFence, type ExecutionPlan, type ExecutionStep, type CockpitId, type StackId } from './contract.js';
+import { type ResolvedExecutable } from './executable.js';
+import { type DrainOutcome, type ReservedDrainAttempt } from './claims.js';
+import { type PortLeaseProjection } from './ports.js';
+import type { StateNamespace } from './state.js';
+import type { LocalRuntimeMeasurements } from './runtime-measurement-record.js';
+import { type ConsumedSetupCheckoutObservation, type SetupCheckoutProjection } from './setup-observation.js';
+export declare const observationDeclarations: readonly [{
+    readonly id: 'runtime-availability';
+    readonly owner: "runtime-planning";
+    readonly postures: readonly ["mounted", "host"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "RUNTIME_UNAVAILABLE";
+    readonly isIssued: typeof isRuntimeObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}, {
+    readonly id: 'runtime-measurement';
+    readonly owner: "runtime-planning";
+    readonly postures: readonly ["environment", "mounted", "host"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "RUNTIME_UNMEASURED";
+    readonly isIssued: typeof isRuntimeObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}, {
+    readonly id: 'mount-posture';
+    readonly owner: "runtime-planning";
+    readonly postures: readonly ["mounted", "host"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "MOUNT_POSTURE_UNAVAILABLE";
+    readonly isIssued: typeof isRuntimeObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}];
+export declare const runtimeHealthObservationDeclarations: readonly [{
+    readonly id: 'runtime-mount-materialization';
+    readonly owner: "runtime-planning";
+    readonly postures: readonly ["running-stack"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "MOUNT_MATERIALIZATION_UNAVAILABLE";
+    readonly isIssued: typeof isRuntimeObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}, {
+    readonly id: 'runtime-port-family';
+    readonly owner: "runtime-planning";
+    readonly postures: readonly ["running-stack"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'not-applicable';
+        readonly reason: 'ports are leased after the first seed';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "PORT_FAMILY_COLLISION";
+    readonly isIssued: typeof isRuntimeObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}];
+export declare function isRuntimeObservation(value: unknown): value is EnvironmentObservation;
+declare function observationIssuedAt(value: unknown): number | undefined;
+export declare function observeRuntimeExecution(input: {
+    readonly plan: ExecutionPlan;
+    readonly outcome: ExecuteProbeOutcome;
+}): readonly EnvironmentObservation[];
+export type RuntimeOperation = 'validate' | 'up' | 'down';
+export interface RuntimeAdapterInput {
+    runtime: {
+        name: 'docker';
+        version: string;
+        executableSha256: string;
+    };
+    composeVersion: string;
+    executable: ResolvedExecutable;
+    operation: RuntimeOperation;
+    cwd: string;
+    composeFiles: readonly ComposeArtifact[];
+    projectName: string;
+    env: Readonly<Record<string, string>>;
+    ports: readonly number[];
+    labels: Readonly<Record<string, string>>;
+    timeoutMs: number;
+    activeProfiles?: readonly string[];
+    stackId?: StackId;
+    coldStartLimitMillis?: number;
+    expectedMountSources?: readonly string[];
+}
+export interface RuntimePlanResult {
+    runtime: 'docker';
+    operation: RuntimeOperation;
+    projectName: string;
+}
+export interface ComposeArtifact {
+    reference: string;
+    canonicalPath: string;
+    source: string;
+    sha256: string;
+}
+/** Each `[[sibling]] var` and the absolute sibling directory it names. */
+export type SiblingDirectoryVariables = Readonly<Record<string, string>>;
+export type RuntimeAdapterAuthority = 
+/** A stack's own Compose files, which interpolate the lease, the sibling directories and their own defaults. */
+Readonly<{
+    ownComposeFiles: true;
+    cockpitId: CockpitId;
+    stackId: StackId;
+    portLeaseProjection?: PortLeaseProjection;
+    siblingDirectories?: SiblingDirectoryVariables;
+}>;
+/** The numeric core of a version Docker or Compose printed, or undefined when it has none. */
+export declare function observedVersionCore(value: string): string | undefined;
+export declare function classifyResolvedRuntimeLiterals(values: readonly string[]): 'resolved' | 'unresolved' | 'unsafe';
+export type MachineFloorPlanInput = {
+    readonly runtimeExecutable: ResolvedExecutable;
+    readonly diskExecutable: ResolvedExecutable;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly authority?: MachineFloorAuthority;
+} | {
+    readonly runtimePlan: ExecutionPlan;
+    readonly diskExecutable: ResolvedExecutable;
+    readonly timeoutMs: number;
+    readonly authority?: MachineFloorAuthority;
+};
+export interface MachineFloorThresholds {
+    readonly memoryBytes: number;
+    readonly cpuMillis: number;
+    readonly freeDiskBytes: number;
+}
+declare const machineFloorEvidenceBrand: unique symbol;
+export interface MachineFloorEvidence {
+    readonly [machineFloorEvidenceBrand]: true;
+    readonly memoryBytes: number;
+    readonly cpuMillis: number;
+    readonly freeDiskBytes: number;
+    readonly observedAt: string;
+    readonly stackId?: StackId;
+    readonly floor?: MachineFloorThresholds;
+}
+export interface MachineFloorAuthority {
+    readonly kind: 'machine-floor-authority';
+}
+export declare function issueMachineFloorAuthority(input: {
+    readonly configuration: MachineFloorConfigProjection;
+    readonly checkout: SetupCheckoutProjection;
+}): Readonly<{
+    authority: MachineFloorAuthority;
+    checkout: ConsumedSetupCheckoutObservation;
+}> | undefined;
+export declare function isMachineFloorEvidence(value: unknown): value is MachineFloorEvidence;
+export interface DockerRuntimeObservationInput {
+    readonly executable: ResolvedExecutable;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+}
+export type RuntimeIdentity = 'docker-desktop' | 'orbstack' | 'colima' | 'rancher-desktop' | 'docker-engine';
+export interface DockerInfoIdentityInput {
+    readonly operatingSystem: string;
+    readonly name: string;
+    readonly osType: string;
+    readonly hostPlatform: string;
+}
+/**
+ * Name the container runtime product from one `docker info` reading, or null when it is not one we
+ * recognise. The identity selects this machine's runtime measurement, so a wrong match would
+ * admit a runtime on another product's measurement; anything unrecognised therefore stays null.
+ *
+ * Provenance of each rule: `orbstack` was observed on a host running OrbStack (OperatingSystem
+ * "OrbStack", Name "orbstack", OSType "linux"). The `docker-desktop`, `colima`, `rancher-desktop` and
+ * `docker-engine` rules are derived from those vendors' documented `docker info` output and have not
+ * been probed on a host here.
+ */
+export declare function runtimeIdentity(input: DockerInfoIdentityInput): RuntimeIdentity | null;
+export type DockerRuntimeObservation = Readonly<{
+    kind: 'complete';
+    runtime: {
+        readonly name: 'docker';
+        readonly version: string;
+        readonly executableSha256: string;
+    };
+    runtimeIdentity: RuntimeIdentity | null;
+    operatingSystem: string;
+    name: string;
+    osType: string;
+    hostPlatform: string;
+    composeVersion: string;
+    observedAt: string;
+}> | Readonly<{
+    kind: 'unavailable';
+    code: typeof ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE;
+    reason: string;
+    fix?: string;
+}>;
+export interface RuntimeMeasurementProbeAuthority {
+    readonly kind: 'runtime-measurement-probe-authority';
+}
+export declare function issueRuntimeMeasurementProbeAuthority(observation: DockerRuntimeObservation): RuntimeMeasurementProbeAuthority;
+export declare function runtimeMeasurementProbeObservation(authority: RuntimeMeasurementProbeAuthority, executableSha256: string): Extract<DockerRuntimeObservation, {
+    readonly kind: 'complete';
+}> | undefined;
+export type RuntimeMeasurementAdmission = Readonly<{
+    kind: 'admitted';
+    runtimeIdentity: string;
+    measurement: string;
+}> | Readonly<{
+    kind: 'unavailable';
+    code: typeof ENVIRONMENT_CODES.RUNTIME_UNMEASURED;
+    reason: string;
+}>;
+/** A floor cockpit writes: a bare numeric core. */
+export declare function isVersionFloor(value: string): boolean;
+/** Whether a version Docker or Compose printed is at least `floor`; false when either is malformed. */
+export declare function versionAtLeast(actual: string, floor: string): boolean;
+export declare function admitRuntimeMeasurement(observation: DockerRuntimeObservation, measurements: LocalRuntimeMeasurements): RuntimeMeasurementAdmission;
+export declare function observeRuntimeMeasurement(admission: RuntimeMeasurementAdmission, stackId: StackId): EnvironmentObservation;
+export declare function observeDockerRuntime(rawInput: DockerRuntimeObservationInput, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): Promise<DockerRuntimeObservation>;
+export type MachineFloorMeasurement = {
+    readonly kind: 'complete';
+    readonly evidence: MachineFloorEvidence;
+} | MachineFloorRefusal | {
+    readonly kind: 'unavailable';
+};
+type MachineFloorRefusal = Extract<EnvironmentCommandOutcome<null>, {
+    kind: 'refusal';
+}>;
+/** Measures the container runtime's memory and CPU and the checkout's free disk. */
+export declare function measureMachineFloor(rawInput: MachineFloorPlanInput, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): Promise<MachineFloorMeasurement>;
+export declare function createRuntimeAdapter(rawInput: RuntimeAdapterInput, authority?: RuntimeAdapterAuthority): EnvironmentCommandOutcome<RuntimePlanResult>;
+export interface RuntimeObservationWindow {
+    readonly startedAt: string;
+    readonly expiresAt: string;
+}
+export interface RuntimeTopologyService {
+    readonly id: string;
+    readonly dependsOn: readonly string[];
+    readonly bindMountSources: readonly string[];
+    readonly namedVolumeMounts?: readonly Readonly<{
+        readonly source: string;
+        readonly name: string;
+        readonly target: string;
+    }>[];
+    readonly healthcheck: boolean;
+}
+export interface RuntimeTopologyEvidence {
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly batchId: string;
+    readonly runtimeVersion: string;
+    readonly composeVersion: string;
+    readonly executableSha256: string;
+    readonly projectName: string;
+    readonly cwd: string;
+    readonly observationWindow: RuntimeObservationWindow;
+    readonly services: readonly RuntimeTopologyService[];
+}
+export type RuntimeTopologyObservation = {
+    readonly kind: 'complete';
+    readonly step: ExecutionStep;
+    readonly topology: RuntimeTopologyEvidence;
+    readonly observations: readonly EnvironmentObservation[];
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+    readonly mounts?: RuntimeMountMismatch;
+};
+export declare const OBSERVATION_WINDOW_HEADROOM_MS = 300000;
+/**
+ * Reads the stack's services through `compose config` from a validated runtime plan, and binds the
+ * topology to that plan, the observation window and the declared bind sources.
+ */
+export declare function observeRuntimeTopology(input: {
+    readonly runtimePlan: ExecutionPlan;
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly batchId: string;
+    readonly observationWindow: RuntimeObservationWindow;
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+}): Promise<RuntimeTopologyObservation>;
+/** Declared mount sources no service binds inside, and bind sources inside no declared one. */
+export type RuntimeMountMismatch = Readonly<{
+    missing: readonly string[];
+    unexpected: readonly string[];
+}>;
+export declare function isRuntimeTopologyEvidence(value: unknown): value is RuntimeTopologyEvidence;
+export declare function resolveRuntimeServiceOrder(topology: RuntimeTopologyEvidence): readonly string[];
+export declare function projectRuntimeExecutionEnvironment(topology: RuntimeTopologyEvidence, namespace?: StateNamespace): Readonly<Record<string, string>> | undefined;
+export type RuntimeContainerIdSlot = Readonly<{
+    kind: 'runtime-container-id';
+    service: string;
+}>;
+export interface RuntimeLifecycleExecutionSemantics {
+    readonly argv: readonly [string | RuntimeContainerIdSlot, ...(string | RuntimeContainerIdSlot)[]];
+    readonly argv0: string;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly timeoutCeilingMs: number;
+    readonly stdoutLimitBytes: number;
+    readonly stderrLimitBytes: number;
+    readonly paths: readonly string[];
+    readonly ports: readonly number[];
+    readonly expected: ExecutionStep['expected'];
+    readonly consumedFiles: ExecutionStep['consumedFiles'];
+    readonly filesystemChecks: ExecutionStep['filesystemChecks'];
+    readonly compensation: readonly RuntimeLifecycleExecutionSemantics[];
+}
+export interface RuntimeLifecycleServiceSemantics {
+    readonly id: string;
+    readonly start: RuntimeLifecycleExecutionSemantics;
+    readonly status: RuntimeLifecycleExecutionSemantics;
+    readonly identity: RuntimeLifecycleExecutionSemantics;
+    readonly inspect: RuntimeLifecycleExecutionSemantics;
+    readonly healthAcceptance: Readonly<{
+        state: 'running';
+        health: 'healthy' | null;
+    }>;
+}
+export interface RuntimeLifecycleSemantics {
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly runtimeVersion: string;
+    readonly composeVersion: string;
+    readonly projectName: string;
+    readonly topology: Readonly<{
+        order: readonly string[];
+        services: readonly RuntimeTopologyService[];
+    }>;
+    readonly runtimeChecks: Readonly<{
+        coldStartLimitMillis: number;
+        expectedMountSources: readonly string[];
+    }>;
+    readonly services: readonly RuntimeLifecycleServiceSemantics[];
+}
+/** The stable work a topology describes, which lifecycle planning digests; valid while its topology is. */
+export interface RuntimeLifecycleProjection {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly semantics: RuntimeLifecycleSemantics;
+}
+declare const runtimeServiceFailureEvidenceBrand: unique symbol;
+export interface RuntimeServiceFailureEvidence {
+    readonly [runtimeServiceFailureEvidenceBrand]: true;
+}
+export interface RuntimeServiceEvidence {
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly batchId: string;
+    readonly runtimeVersion: string;
+    readonly composeVersion: string;
+    readonly executableSha256: string;
+    readonly projectName: string;
+    readonly service: string;
+    readonly containerId: string;
+    readonly state: 'running';
+    readonly health: 'healthy' | null;
+    readonly observedAt: string;
+    readonly observationWindow: RuntimeObservationWindow;
+}
+export interface RuntimeServiceObservation {
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly batchId: string;
+    readonly runtimeVersion: string;
+    readonly composeVersion: string;
+    readonly executableSha256: string;
+    readonly projectName: string;
+    readonly service: string;
+    readonly containerId: string;
+    readonly state: 'created' | 'running' | 'restarting' | 'paused' | 'exited' | 'dead' | 'removing';
+    readonly health: 'healthy' | 'starting' | 'unhealthy' | null;
+    readonly observedAt: string;
+    readonly observationWindow: RuntimeObservationWindow;
+}
+/** What a service start or revalidation observed; `stop` stops, without removing, a service this run started. */
+export type RuntimeServiceOutcome = {
+    readonly kind: 'observed';
+    readonly observation: RuntimeServiceObservation;
+    readonly stop?: ExecutionStep;
+} | {
+    readonly kind: 'stale';
+} | {
+    readonly kind: 'failure';
+    readonly logs?: RuntimeServiceFailureEvidence;
+    readonly stop?: ExecutionStep;
+};
+type Execute = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+export declare function projectRuntimeLifecycle(topology: RuntimeTopologyEvidence): RuntimeLifecycleProjection | undefined;
+/**
+ * Starts one service with `up --wait`, finds its container through Compose and inspects it. Each
+ * step must finish inside the topology's observation window and after the one before it.
+ */
+export declare function startRuntimeService(input: {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly service: string;
+    readonly execute: Execute;
+}): Promise<RuntimeServiceOutcome>;
+/**
+ * Re-reads a service an earlier run started: stale when Compose no longer has the recorded
+ * container, otherwise the container's current inspection.
+ */
+export declare function revalidateRuntimeService(input: {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly service: string;
+    readonly expectedContainerId: string;
+    readonly execute: Execute;
+}): Promise<RuntimeServiceOutcome>;
+/** The observation as healthy-service evidence, or undefined when the service is not running healthy. */
+export declare function admitRuntimeServiceHealth(observation: RuntimeServiceObservation): RuntimeServiceEvidence | undefined;
+export declare function isRuntimeServiceEvidence(value: unknown): value is RuntimeServiceEvidence;
+export declare function observeRuntimeMountMaterialization(input: {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly services: readonly RuntimeServiceEvidence[];
+    readonly observedAt: string;
+}): EnvironmentObservation;
+export declare function observeRuntimePortFamily(input: {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly services: readonly RuntimeServiceEvidence[];
+    readonly namespace: StateNamespace;
+    readonly listenerTimeoutMs: number;
+    readonly revalidate: () => Promise<readonly RuntimeServiceEvidence[]>;
+}): Promise<EnvironmentObservation>;
+export declare function observeRuntimeServiceColdStart(input: {
+    readonly services: readonly RuntimeServiceEvidence[];
+}): EnvironmentObservation;
+export interface RuntimeServiceFailureLogContext {
+    readonly stage: 'start' | 'status' | 'identity' | 'inspect';
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly batchId: string;
+    readonly runtimeVersion: string;
+    readonly composeVersion: string;
+    readonly executableSha256: string;
+    readonly projectName: string;
+    readonly service: string;
+    readonly containerId: string | null;
+    readonly observedAt: string;
+    readonly observationWindow: RuntimeObservationWindow;
+    readonly executable: ResolvedExecutable;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly composeArgvPrefix: readonly string[];
+    readonly paths: ExecutionStep['paths'];
+    readonly consumedFiles: ExecutionStep['consumedFiles'];
+    readonly filesystemChecks: ExecutionStep['filesystemChecks'];
+}
+export declare function consumeRuntimeServiceFailureForLogs(evidence: RuntimeServiceFailureEvidence): RuntimeServiceFailureLogContext | undefined;
+export interface RuntimeServiceFailureContext {
+    readonly observation: RuntimeServiceObservation;
+    readonly executable: ResolvedExecutable;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+}
+export declare function consumeRuntimeServiceObservationForFailureLogs(value: RuntimeServiceObservation): RuntimeServiceFailureContext | undefined;
+export type RuntimeStopOutcome = 
+/** Compose stopped the stack and a fresh `ps` found nothing running. */
+{
+    readonly kind: 'stopped';
+    readonly outcome: DrainOutcome;
+    readonly fence: ExecutionFence;
+}
+/** The stop never started, so the drain attempt is settled as failed and nothing changed. */
+ | {
+    readonly kind: 'not-started';
+    readonly code: ExecutionFailureCode;
+    readonly outcome: DrainOutcome;
+    readonly fence: ExecutionFence;
+}
+/** No proof either way; the drain attempt stays open and its fence stays for repair. */
+ | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+/**
+ * Runs the drain's runtime-stop action: `compose stop` under the attempt's execution fence, then a
+ * fresh `ps` that must find nothing running, and settles the attempt as the outcome to publish.
+ */
+export declare function stopRuntime(input: {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly attempt: ReservedDrainAttempt;
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+}): Promise<RuntimeStopOutcome>;
+export {};