@indigoai-us/hq-cli 5.126.0 → 5.128.0

package/dist/lib/lanes/reconcile.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Periodic reconcile pass (spec §5.7, §6.8, §9).
+ *
+ * Owned by the machine, not by any lane. Reads never mutate; every write is a
+ * compare-and-set. The per-lane watcher owns progress/terminal/silence of a
+ * live process — this pass owns the transitions no single lane can own.
+ */
+import { type LivenessDeps } from "./liveness.js";
+import { type EnvelopeRepairSpawnInput, type SpawnLaneDeps } from "./spawn.js";
+import { type ThrottleDeps } from "./throttle.js";
+import type { LaneRecord, LivenessState, QuestionRecord, SeniorRef } from "./types.js";
+import { type LaneMesh } from "./mesh-events.js";
+/** Spec §9: unanswered at the current hop for 60 minutes → one hop. */
+export declare const QUESTION_AGE_MS: number;
+/** Spec §6.6 + §9: v1 permits exactly one aged advance. */
+export declare const MAX_AGED_ADVANCES = 1;
+/** Aligns with watcher silence: a host that has not reported for this long is dead. */
+export declare const DEAD_HOST_MS: number;
+export declare const RECONCILE_LOCK_STALE_MS = 30000;
+export declare const RECONCILE_LOCK_TIMEOUT_MS = 5000;
+export declare const RECONCILE_UNIT_NAME = "hq-lanes-reconcile.service";
+export declare const RECONCILE_TIMER_NAME = "hq-lanes-reconcile.timer";
+export interface ReconcileSkip {
+    kind: "lane" | "question" | "store" | "throttle" | "liveness";
+    id?: string;
+    why: string;
+}
+export interface ReconcileChange {
+    id: string;
+    from?: string;
+    to?: string;
+    reason?: string;
+    /** The attempted provider PATH when admission found no executable. */
+    searched_path?: string;
+}
+export interface ReconcileSummary {
+    ok: boolean;
+    action: "reconcile";
+    dry_run: boolean;
+    admitted: ReconcileChange[];
+    overdue: ReconcileChange[];
+    aged: ReconcileChange[];
+    advanced: ReconcileChange[];
+    resumed: ReconcileChange[];
+    dead_host: ReconcileChange[];
+    heartbeats: string[];
+    skipped: ReconcileSkip[];
+    errors: Array<{
+        message: string;
+        code?: string;
+    }>;
+    heartbeat_at: string | null;
+}
+export interface ReconcileHost {
+    hostname: string;
+    outpostId: string | null;
+}
+export interface ReconcileDeps {
+    now: () => Date;
+    host: ReconcileHost;
+    dryRun: boolean;
+    spawn?: (hqRoot: string, lane: LaneRecord) => LaneRecord;
+    spawnRepair?: (hqRoot: string, lane: LaneRecord, input: EnvelopeRepairSpawnInput) => number;
+    spawnLaneDeps?: SpawnLaneDeps;
+    throttleDeps?: ThrottleDeps;
+    livenessDeps?: LivenessDeps;
+    isAlive?: (pid: number) => boolean;
+    readSessionSenior?: (sessionId: string) => SeniorRef;
+    presenceConnected?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** Detached mesh seam for dead-watcher recovery. */
+    mesh?: LaneMesh | null;
+    /** Bound on one terminal mesh emit during dead-host recovery. Default 10 s. */
+    meshEmitTimeoutMs?: number;
+    /**
+     * Awaited after lane/question records and liveness are loaded, before any
+     * CAS write. Test seam so two in-process passes can share a snapshot.
+     */
+    afterLoad?: () => Promise<void>;
+}
+export declare function reconcileHeartbeatPath(hqRoot: string): string;
+export declare function timeoutPath(hqRoot: string, laneId: string): string;
+export declare function laneRunsHere(lane: LaneRecord, host: ReconcileHost): boolean;
+export declare function agedAdvanceCount(question: QuestionRecord): number;
+export declare function currentHopStartedAtMs(question: QuestionRecord): number;
+export declare function shouldAgeQuestion(question: QuestionRecord, audience: SeniorRef, nowMs: number): boolean;
+export declare function shouldAdvanceAudienceEnded(audience: SeniorRef, liveness: LivenessState | null): boolean;
+export declare function readTimeoutDeadline(hqRoot: string, laneId: string): {
+    deadline_at: string;
+    timeout_secs?: number;
+} | null;
+export declare function isDeadlinePassed(deadlineAt: string, nowMs: number): boolean;
+export declare function resolveQuestionAudience(question: QuestionRecord, readLaneSenior: (laneId: string) => SeniorRef, readSessionSenior: (sessionId: string) => SeniorRef): SeniorRef;
+/** Unlocked pass body. `runReconcilePass` takes the process lock around this. */
+export declare function runPassBody(hqRoot: string, deps: ReconcileDeps): Promise<ReconcileSummary>;
+/**
+ * One idempotent reconcile pass. Throws only when the store directory itself
+ * cannot be listed; per-record failures are logged onto the summary and set
+ * `ok: false` rather than being swallowed.
+ */
+export declare function runReconcilePass(hqRoot: string, deps: ReconcileDeps): Promise<ReconcileSummary>;
+//# sourceMappingURL=reconcile.d.ts.map