@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/claims.d.ts

@@ -0,0 +1,389 @@
+import { type CheckoutId, type CockpitId, type EnvironmentDiagnostic, type EnvironmentObservation, type HolderId, type ExecutionStep, type ExecutionFence, type StackId } from './contract.js';
+import { type ExecuteProbeOutcome, type FencedExecutionTermination } from '../environment-exec/execute.js';
+import { type SkippedStateNamespace, type StateNamespace, type StateRecord, type StateResult, type StateTransactionOptions } from './state.js';
+export declare const observationDeclarations: readonly [{
+    readonly id: 'claim-state';
+    readonly owner: "environment-claims";
+    readonly postures: readonly ["environment"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'not-applicable';
+        readonly reason: 'claims do not exist before the first seed';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "CLAIM_STATE_UNHEALTHY";
+    readonly isIssued: typeof isClaimObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}];
+declare function isClaimObservation(value: unknown): value is EnvironmentObservation;
+declare function observationIssuedAt(value: unknown): number | undefined;
+export declare function observeClaimState(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly observedAt: string;
+}): Promise<EnvironmentObservation>;
+interface ClaimHolder {
+    readonly holderId: HolderId;
+    readonly checkoutId: CheckoutId;
+    readonly claimedAt: string;
+    readonly pid?: number;
+    readonly processStart?: string;
+}
+export interface PortLeaseRecord {
+    readonly offset: number;
+    readonly ports: Readonly<Record<string, number>>;
+    readonly released: boolean;
+    readonly declaration: {
+        readonly step: number;
+        readonly count: number;
+        readonly bases: Readonly<Record<string, number>>;
+    };
+}
+export interface CoordinationRecord {
+    readonly holders: readonly ClaimHolder[];
+    readonly lease: PortLeaseRecord | null;
+    readonly lastReleasedHolder: HolderId | null;
+    readonly drain?: DrainReservation | null;
+}
+type DrainPurpose = 'sleep' | 'down' | 'reset';
+type DrainAction = {
+    readonly stage: 'runtime-stop';
+    readonly targetId: string;
+    readonly validForMs: number;
+} | {
+    readonly stage: 'reclaim';
+    readonly targetId: string;
+    readonly validForMs: number;
+    readonly targetCommitment: DrainTargetCommitment;
+};
+export interface DrainTargetCommitment {
+    readonly format: 'cockpit-reclaim-target/v1';
+    readonly sha256: string;
+    readonly body: string;
+}
+export interface DrainReservationRequest {
+    readonly purpose: DrainPurpose;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly requesterId: HolderId;
+    readonly configSha256: string;
+    readonly planDigest: string;
+    readonly operationBasis: string;
+    readonly generation: string;
+    readonly targetIds: readonly string[];
+    readonly actions: readonly DrainAction[];
+    readonly expectedCoordinationRevision: number;
+}
+export interface DrainReservation extends DrainReservationRequest {
+    readonly coordinationRevision: number;
+    readonly reservedAt: string;
+    readonly reservationId: string;
+    readonly completedActionCount: number;
+    readonly progressRevision: number;
+    readonly attempt: DrainAttempt | null;
+}
+interface DrainAttempt {
+    readonly attemptId: string;
+    readonly reservationId: string;
+    readonly purpose: DrainPurpose;
+    readonly targetIds: readonly string[];
+    readonly generation: string;
+    readonly actionIndex: number;
+    readonly currentTarget: string;
+    readonly currentStage: DrainAction['stage'];
+    readonly committedRevision: number;
+    readonly committedAt: string;
+    readonly validThrough: string;
+    readonly status: 'active' | 'failed';
+    readonly failedRevision: number | null;
+    readonly failedAt: string | null;
+}
+interface FailedReclaimRecoveryTarget {
+    readonly targetId: string;
+    readonly targetCommitment: DrainTargetCommitment;
+}
+export interface FailedReclaimRecovery {
+    readonly purpose: 'down' | 'reset';
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly planDigest: string;
+    readonly freshAfter: string;
+    readonly completed: readonly FailedReclaimRecoveryTarget[];
+    readonly current: FailedReclaimRecoveryTarget;
+    readonly pending: readonly FailedReclaimRecoveryTarget[];
+}
+/** An attempt the claims owner committed, and the execution fence its one step runs under. */
+export interface ReservedDrainAttempt {
+    readonly reservation: DrainReservation;
+    readonly attempt: DrainAttempt;
+    readonly fence: ExecutionFence;
+}
+/**
+ * What a drain step settled to, for `commitDrainOutcome` to publish. The publication admits it only
+ * while the coordination record still holds its exact active attempt, so it publishes at most once.
+ */
+export type DrainOutcome = {
+    readonly kind: 'success';
+    readonly reservation: DrainReservation;
+    readonly fact: RuntimeStopped | ReclaimCompleted;
+} | {
+    readonly kind: 'failure';
+    readonly reservation: DrainReservation;
+    readonly failedAt: string;
+};
+/**
+ * The reclaim attempt a removal ran under and the record it was planned from. The next plan matches
+ * it against the record the removal's outcome published; `failedAt` is set when the removal never started.
+ */
+export interface ReclaimDrainStep {
+    readonly planningRecord: StateRecord;
+    readonly reservation: DrainReservation;
+    readonly failedAt: string | null;
+}
+export interface RuntimeStopped {
+    readonly purpose: DrainPurpose;
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly planDigest: string;
+    readonly operationBasis: string;
+    readonly coordinationRevision: number;
+    readonly reservationId: string;
+    readonly reservedAt: string;
+    readonly generation: string;
+    readonly attemptId: string;
+    readonly attemptRevision: number;
+    readonly attemptCommittedAt: string;
+    readonly validThrough: string;
+    readonly actionIndex: number;
+    readonly currentTarget: string;
+    readonly currentStage: DrainAction['stage'];
+    readonly observedAt: string;
+}
+export interface ReclaimCompleted extends RuntimeStopped {
+    readonly remainingTargetIds: readonly string[];
+}
+type ClaimMutationRefusal = {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+type ReleaseClaimResult = {
+    readonly kind: 'complete';
+    readonly change: 'released' | 'unchanged';
+    readonly decision: 'stop' | 'retain';
+    readonly remaining: readonly HolderId[];
+} | ClaimMutationRefusal;
+export interface HolderProcess {
+    readonly pid?: number;
+    readonly processStart?: string;
+}
+export type ProcessStartObservation = {
+    readonly state: 'absent';
+} | {
+    readonly state: 'present';
+    readonly start: string;
+} | {
+    readonly state: 'unknown';
+    readonly reason: string;
+};
+/** What observing a process reads from this machine; production binds it with `processHost`. */
+export interface ProcessHost {
+    readonly platform: NodeJS.Platform;
+    /** Whether the pid exists, by signal 0; anything short of proof of absence is `live` or `unavailable`. */
+    readonly presence: (pid: number) => Promise<'live' | 'absent' | 'unavailable'>;
+    /** `ps -o lstart=` for the pid under a fixed locale and zone. */
+    readonly psStart: (pid: number) => Promise<{
+        readonly kind: 'complete';
+        readonly text: string;
+    } | {
+        readonly kind: 'failed';
+        readonly reason: string;
+    }>;
+    /** A file's UTF-8 text; rejects with the read's errno error. */
+    readonly readFile: (path: string) => Promise<string>;
+}
+/** A start identity as `observeProcessStart` reports it: `lstart:<timestamp>` or `proc:<boot id>:<ticks>`. */
+export declare function isProcessStart(value: unknown): value is string;
+/**
+ * Whether an observation proves gone the process recorded with `processStart`. A gone pid proves it
+ * whether or not a start was recorded, since reuse can only make a dead process look alive; a start
+ * identity decides only against one read the same way.
+ */
+export declare function isProcessGone(processStart: string | undefined, observed: ProcessStartObservation): boolean;
+export declare function observeProcessStart(pid: number, host: ProcessHost): Promise<ProcessStartObservation>;
+/** The production `ProcessHost`: signal 0 and ps cross the executor, and /proc is read directly. */
+export declare function processHost(execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): ProcessHost;
+export declare function liveHolderMessage(holders: readonly ClaimHolder[]): string;
+type ReleaseDeadSessionHoldersResult = {
+    readonly kind: 'complete';
+    readonly released: readonly ClaimHolder[];
+} | ClaimMutationRefusal;
+/**
+ * Remove the holds of `cockpit session` wrappers whose process is gone. A session killed with
+ * SIGKILL, a crash or a closed terminal never runs its closing `sleep`, and its hold then made
+ * `down`, `reset` and `sleep` refuse forever while naming a session nobody could end. When every
+ * holder is dead, the requesting holder takes the stack over in the same transaction: the stack is
+ * still running, and a lease no holder retains reads as a stopped stack whose ports are free.
+ */
+export declare function releaseDeadSessionHolders(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly successor: {
+        readonly holderId: HolderId;
+        readonly checkoutId: CheckoutId;
+    } & HolderProcess;
+    readonly now: string;
+    readonly observe: (pid: number) => Promise<ProcessStartObservation>;
+}): Promise<ReleaseDeadSessionHoldersResult>;
+export type ActiveStackInventoryResult = {
+    readonly kind: 'complete';
+    readonly value: readonly {
+        readonly stackId: StackId;
+        readonly record: CoordinationRecord;
+    }[];
+} | ClaimMutationRefusal;
+export declare function readActiveStackInventory(namespace: StateNamespace, options?: Pick<StateTransactionOptions, 'observeHolder'>): Promise<ActiveStackInventoryResult>;
+export declare function readRootPortInventory(namespace: StateNamespace, options?: Pick<StateTransactionOptions, 'observeHolder'>): Promise<{
+    readonly kind: 'complete';
+    readonly value: readonly {
+        cockpitId: CockpitId;
+        stackId: StackId;
+        record: CoordinationRecord;
+    }[];
+    readonly skipped: readonly SkippedStateNamespace[];
+} | ClaimMutationRefusal>;
+export declare function decodeCoordinationRecord(record: StateRecord | null, stackId: StackId): CoordinationRecord | undefined;
+export declare function addCoordinationHolder(value: CoordinationRecord, holder: {
+    readonly holderId: HolderId;
+    readonly checkoutId: CheckoutId;
+} & HolderProcess, now: string): {
+    readonly value: CoordinationRecord;
+    readonly change: 'acquired' | 'unchanged';
+} | undefined;
+export declare function removeExactCoordinationHolder(value: CoordinationRecord, holderId: HolderId): CoordinationRecord | undefined;
+export declare function coordinationStateRecord(namespace: StateNamespace, stackId: StackId, current: StateRecord | null, now: string, value: CoordinationRecord): StateRecord;
+export declare function isDrainActive(value: CoordinationRecord): boolean;
+type DrainReservationResult = {
+    readonly kind: 'complete';
+    readonly reservation: DrainReservation;
+} | ClaimMutationRefusal;
+export declare function reserveDrain(input: {
+    readonly namespace: StateNamespace;
+    readonly request: DrainReservationRequest;
+}): Promise<DrainReservationResult>;
+export type DrainAttemptResult = ({
+    readonly kind: 'complete';
+} & ReservedDrainAttempt) | ClaimMutationRefusal;
+/**
+ * Commits the next attempt of a reservation: its first try, or a retry of the action whose try was
+ * published as failed. The commit admits only the exact persisted reservation at the revision it
+ * names, so two holders of one reservation cannot both start an attempt.
+ */
+export declare function reserveDrainAttempt(input: {
+    readonly namespace: StateNamespace;
+    readonly reservation: DrainReservation;
+}): Promise<DrainAttemptResult>;
+/**
+ * Binds an active reclaim attempt to the coordination record its removal was planned from. Undefined
+ * when that record does not directly precede the attempt, so a plan never runs under another try.
+ */
+export declare function reclaimDrainStep(input: {
+    readonly planningRecord: StateRecord;
+    readonly reservation: DrainReservation;
+}): ReclaimDrainStep | undefined;
+/** The coordination value the outcome publishes over `record`, or undefined when it no longer applies. */
+export declare function reduceDrainOutcome(input: {
+    readonly outcome: DrainOutcome;
+    readonly record: StateRecord;
+}): CoordinationRecord | undefined;
+/**
+ * Publishes a settled drain outcome to the coordination record. The publication admits it only while
+ * the record holds the outcome's exact active attempt, so an outcome publishes at most once.
+ */
+export declare function commitDrainOutcome(input: {
+    readonly outcome: DrainOutcome;
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly beforePublish?: StateTransactionOptions['beforePublish'];
+}): Promise<StateResult<StateRecord> | ClaimMutationRefusal>;
+/**
+ * Whether `record` is the one the step's outcome published: its removal progressed, or (for a step
+ * that never started) its failure was recorded. Anything else is unmatched.
+ */
+export declare function matchReclaimDrainContinuation(input: {
+    readonly continuation: ReclaimDrainStep | null;
+    readonly record: StateRecord;
+}): 'progressed' | 'failed' | 'unmatched';
+type SleepDrainRecoveryInspection = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'repairable';
+    readonly fence: ExecutionFence;
+    readonly record: StateRecord;
+} | {
+    readonly kind: 'recoverable';
+    readonly generation: string;
+    readonly runtimeStopValidForMs: number;
+    /** The record inspected; recovery acts only while the stored record is still exactly this one. */
+    readonly record: StateRecord;
+} | ClaimMutationRefusal;
+type DestructiveDrainRecoveryInspection = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'repairable';
+    readonly fence: ExecutionFence;
+    readonly record: StateRecord;
+} | {
+    readonly kind: 'recoverable';
+    readonly request: DrainReservationRequest;
+} | ClaimMutationRefusal;
+/**
+ * Records an interrupted attempt as failed once the executor's termination is proven for its fence.
+ * The record must still be exactly the one inspected, so a concurrent change is never overwritten.
+ */
+export declare function settleInterruptedDrainRepair(input: {
+    readonly namespace: StateNamespace;
+    readonly record: StateRecord;
+    readonly evidence: FencedExecutionTermination;
+}): Promise<StateResult<StateRecord> | ClaimMutationRefusal>;
+export declare function inspectDestructiveDrainRecovery(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly purpose: 'down' | 'reset';
+}): Promise<DestructiveDrainRecoveryInspection>;
+export declare function inspectSleepDrainRecovery(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+}): Promise<SleepDrainRecoveryInspection>;
+/**
+ * Resumes a persisted sleep drain from fresh planning evidence. The stored record must still be the
+ * one inspected and the fresh request must name its revision and the same work.
+ */
+export declare function recoverSleepDrainReservation(input: {
+    readonly namespace: StateNamespace;
+    readonly record: StateRecord;
+    readonly request: DrainReservationRequest;
+}): Promise<DrainReservationResult>;
+export declare function recoverDrainReservation(input: {
+    readonly namespace: StateNamespace;
+    readonly request: DrainReservationRequest;
+}): Promise<DrainReservationResult>;
+/**
+ * The committed targets of a recovered reservation whose reclaim try failed, read from the record
+ * that published that failure. Undefined for any other reservation or record.
+ */
+export declare function inspectFailedReclaimRecovery(input: {
+    readonly reservation: DrainReservation;
+    readonly record: StateRecord;
+}): FailedReclaimRecovery | undefined;
+export declare function releaseClaim(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly requesterId: HolderId;
+    readonly holderId: HolderId;
+    readonly now: string;
+}): Promise<ReleaseClaimResult>;
+export {};