@khorsheed/dsh-ankh-guard 0.1.1 → 0.2.0

package/lib/types/launch-spec.d.ts

@@ -0,0 +1,263 @@
+import type { TransitionReference } from './transition.ts';
+export type CutoverRecoveryPolicy = 'restore-previous' | 'wait-for-user';
+export type BrowserHandoffPolicy = 'required' | 'off';
+export type LaunchRole = 'target' | 'previous';
+export type CutoverControlAction = 'abort' | 'restore-previous';
+export type PreflightSurface = 'source' | 'built';
+/**
+ * Immutable execution binding for composition preflight. The runner and host
+ * installation are explicit because the guarded checkout and the successor's
+ * npm toolchain may be different module graphs.
+ */
+export interface LaunchPreflightSpec {
+    version: 1;
+    surface: PreflightSurface;
+    runnerExecutable: string;
+    runnerRuntimeArgs: string[];
+    runnerPath: string;
+    runnerSha256: string;
+    /** package.json used as createRequire()'s anchor for a built successor. */
+    installAnchor: string;
+    installAnchorSha256: string;
+    hostPackageVersion: string;
+    /** Full digest of the launch command this preflight contract approves. */
+    targetCommandSha256: string;
+    /** One-shot candidate command that validates the target CLI/argv contract. */
+    candidateProbeCommand?: string;
+    candidateProbeSha256?: string;
+    /** Guard binds and runs this caller assertion; it does not derive the probe. */
+    candidateProbeProvenance?: 'caller-supplied';
+}
+/** Everything needed to launch one supervised instance. The state directory is the transaction anchor. */
+export interface LaunchSpec {
+    version: 1;
+    command: string;
+    port: number;
+    home: string;
+    /** Repository whose HEAD is bound to the guard credential and rollback. */
+    credentialRepo: string;
+    /** dsh host checkout used by preflight and exported as DSH_HARNESS. */
+    harnessRoot: string;
+    profile: string;
+    /** Absent only on launch state written before execution binding existed. */
+    preflight?: LaunchPreflightSpec;
+}
+export interface StableLaunchState {
+    version: 1;
+    mode: 'stable';
+    active: LaunchSpec;
+}
+export interface CutoverLaunchState {
+    version: 1;
+    mode: 'cutover';
+    cutoverId: string;
+    selected: LaunchRole;
+    previous: LaunchSpec;
+    target: LaunchSpec;
+    /** Immutable, cutover-scoped filesystem transition prepared before takeover. */
+    transition?: TransitionReference;
+}
+export type LaunchState = StableLaunchState | CutoverLaunchState;
+export type CutoverPhase = 'prepared' | 'supervisor-starting' | 'supervisor-ready' | 'target-starting' | 'target-retrying' | 'restoring' | 'ready' | 'restored' | 'awaiting-user' | 'prepare-failed';
+export interface LaunchSpecSummary {
+    commandSha256: string;
+    port: number;
+    home: string;
+    credentialRepo: string;
+    harnessRoot: string;
+    profile: string;
+    preflight?: {
+        surface: PreflightSurface;
+        runnerExecutable: string;
+        runnerRuntimeArgs: string[];
+        runnerPath: string;
+        runnerSha256: string;
+        installAnchor: string;
+        installAnchorSha256: string;
+        hostPackageVersion: string;
+        targetCommandSha256: string;
+        candidateProbeSha256?: string;
+        candidateProbeProvenance?: 'caller-supplied';
+    };
+}
+export interface CutoverAttempt {
+    role: LaunchRole;
+    number: number;
+    childPid: number;
+    childStartToken?: string;
+    startedAt: number;
+    outcome?: 'failed' | 'ready';
+    detail?: string;
+}
+/** PID identity proof safe to persist in the redacted operational receipt. */
+export interface CutoverProcessOwnership {
+    childPid: number;
+    childStartToken: string;
+    listenerPid: number;
+    listenerStartToken: string;
+}
+export interface CutoverBrowserHandoff {
+    required: boolean;
+    status: 'pending' | 'acknowledged' | 'fallback-opened' | 'off' | 'failed' | 'not-required';
+    channel?: 'original-tab' | 'fallback-tab';
+    authentication?: 'existing-cookie' | 'launch-url';
+    authority?: string;
+    acknowledgedAt?: number;
+}
+export interface LaunchCutoverReceipt {
+    version: 1;
+    id: string;
+    phase: CutoverPhase;
+    preparedAt: number;
+    updatedAt: number;
+    initiator?: string;
+    previous: LaunchSpecSummary;
+    target: LaunchSpecSummary;
+    /** Redacted transition evidence; the plan paths live only in launch state. */
+    transition?: {
+        planSha256: string;
+        operationCount: number;
+        phase: 'pending' | 'applied' | 'rolled-back' | 'failed';
+        failureOperation?: 'apply' | 'rollback';
+        detail?: string;
+    };
+    supervisor: {
+        previousPid: number;
+        previousStartToken: string;
+        targetDriverPid?: number;
+        targetDriverStartToken?: string;
+        targetPid?: number;
+        targetStartToken?: string;
+        previousRetirement?: 'yielded' | 'identity-gone' | 'forced';
+    };
+    child: {
+        previousPid?: number;
+        targetPid?: number;
+        restoredPid?: number;
+    };
+    ownership: {
+        previous: CutoverProcessOwnership;
+        target?: CutoverProcessOwnership;
+        restored?: CutoverProcessOwnership;
+    };
+    readiness?: {
+        role: LaunchRole;
+        childPid: number;
+        listenerPid: number;
+        stableWindowMs: number;
+        retryCount: number;
+    };
+    authentication: {
+        transportStatus?: number;
+        launchUrlObserved?: boolean;
+        exchangeStatus?: number;
+        authenticatedStatus?: number;
+        /** Compatibility summary; detailed browser evidence lives in browserHandoff. */
+        browserHandoff: CutoverBrowserHandoff['status'];
+    };
+    /** Browser acknowledgement is independent of server transport/readiness/canary. */
+    browserHandoff: CutoverBrowserHandoff;
+    /** Candidate and composition checks completed before the previous host stopped. */
+    preflight?: {
+        surface: PreflightSurface;
+        runnerExecutable: string;
+        runnerRuntimeArgs: string[];
+        runnerPath: string;
+        runnerSha256: string;
+        installAnchor: string;
+        installAnchorSha256: string;
+        hostPackageVersion: string;
+        targetCommandSha256: string;
+        candidateProbeSha256: string;
+        candidateProbeProvenance: 'caller-supplied';
+        candidateProbe: 'pass';
+        composition: 'pass';
+    };
+    /** Target evidence is retained even if recovery later becomes terminal. */
+    targetValidation?: {
+        readiness?: LaunchCutoverReceipt['readiness'];
+        canary?: {
+            outcome: 'pass' | 'fail';
+            detail?: string;
+        };
+    };
+    canary?: {
+        outcome: 'pass' | 'fail';
+        detail?: string;
+    };
+    attempts: CutoverAttempt[];
+    failureCount: {
+        target: number;
+        previous: number;
+    };
+    recovery: {
+        policy: CutoverRecoveryPolicy;
+        result: 'pending' | 'not-needed' | 'restored' | 'waiting-for-user' | 'prepare-failed';
+        detail?: string;
+        validation?: {
+            readiness?: LaunchCutoverReceipt['readiness'];
+            canary?: {
+                outcome: 'pass' | 'fail' | 'skipped';
+                detail?: string;
+            };
+        };
+    };
+    events: Array<{
+        at: number;
+        kind: string;
+        detail?: string;
+    }>;
+}
+export interface CutoverControlRequest {
+    version: 1;
+    cutoverId: string;
+    action: CutoverControlAction;
+    requestedAt: number;
+}
+export declare function commandSha256(command: string): string;
+/** Read the selected launch state, or null for a deployment predating this protocol. */
+export declare function readLaunchState(stateDir: string): LaunchState | null;
+/** The exact spec a newly starting supervisor must honor. */
+export declare function selectedLaunchSpec(state: LaunchState): LaunchSpec;
+/** Persist an ordinary, non-transactional active spec. */
+export declare function writeStableLaunchSpec(stateDir: string, spec: LaunchSpec, ifAbsent?: boolean): boolean;
+export declare function summarizeLaunchSpec(spec: LaunchSpec): LaunchSpecSummary;
+/** Safe operator view: preserve topology and selection without printing commands. */
+export declare function summarizeLaunchState(state: LaunchState | null): unknown;
+/** Read the durable receipt, or null when absent/malformed. */
+export declare function readCutoverReceipt(stateDir: string): LaunchCutoverReceipt | null;
+/** Persist an operator control request for the current watchdog to consume. */
+export declare function writeCutoverControl(stateDir: string, cutoverId: string, action: CutoverControlAction, now: number): CutoverControlRequest;
+export declare function readCutoverControl(stateDir: string): CutoverControlRequest | null;
+export declare function clearCutoverControl(stateDir: string, cutoverId: string): void;
+/**
+ * Prepare one cutover. The receipt lands first; the single launch-state rename
+ * is the commit point selecting target. A crash before that rename leaves the
+ * previous stable state authoritative and the old supervisor untouched.
+ */
+export declare function prepareLaunchCutover(stateDir: string, input: {
+    id: string;
+    previous: LaunchSpec;
+    target: LaunchSpec;
+    recoveryPolicy: CutoverRecoveryPolicy;
+    browserHandoff: BrowserHandoffPolicy;
+    previousSupervisorPid: number;
+    previousSupervisorStartToken: string;
+    previousOwnership: CutoverProcessOwnership;
+    transition?: TransitionReference;
+    initiator?: string;
+    now: number;
+}): LaunchCutoverReceipt;
+/**
+ * Apply one watchdog event. Arguments are deliberately credential-free; the
+ * launch URL itself never crosses this boundary or lands in the receipt.
+ */
+export declare function recordCutoverEvent(stateDir: string, id: string, kind: string, args: readonly string[], now: number): LaunchCutoverReceipt;
+/** A restarted instance must not wake/report while the watchdog is still proving the cutover. */
+export declare function cutoverBlocksWake(stateDir: string): boolean;
+/** The active transaction's full specs plus its redacted policy receipt. */
+export declare function activeCutover(stateDir: string): {
+    state: CutoverLaunchState;
+    receipt: LaunchCutoverReceipt;
+} | null;
+//# sourceMappingURL=launch-spec.d.ts.map