@intx/workflow-host 0.2.2 → 0.3.0

package/dist/supervisor/supervisor.d.ts

@@ -1,3 +1,4 @@
+import { type CredentialDelivery } from "@intx/types/sidecar";
 import type { InferenceSource } from "@intx/types/runtime";
 import type { CancelOrigin } from "@intx/workflow";
 import { type EventPayload } from "../ipc/index.js";
@@ -5,20 +6,57 @@ import { type CredentialsSnapshot } from "./credentials.js";
 import { type RecycleAttempt, type RecycleOrigin } from "./recycle.js";
 import type { WorkflowSupervisorBindings } from "./types.js";
 /**
- * Default watchdog timeout for the supervisor's
- * `synchronouslyDispatchTerminalWrite`. The handler holds the
- * `substrate.write.response` back to the child until the dispatch
- * loop's `markConsumed` settles for the matching terminal event; an
- * unbounded wait would chain into a child / runtime / dispatch loop
- * deadlock if `markConsumed` never armed (bug in the dispatch loop, a
- * torn-down cohort, a stalled inbox primitive). 30s sits between the
- * recycle path's `DEFAULT_KILL_TIMEOUT_MS` (5s, a hard process-level
- * kill cap) and `DEFAULT_DRAIN_TIMEOUT_MS` (60s, the per-deployment
- * drain budget) -- generous enough to absorb a slow legitimate
- * markConsumed, tight enough to surface a real deadlock long before
- * the drainTimeout would otherwise mask it.
+ * Default crash-loop bound: the supervisor stops respawning and latches
+ * the deployment once the workflow-process child exits unexpectedly this
+ * many times within `DEFAULT_CRASH_LOOP_WINDOW_MS`. Overridable via
+ * `WorkflowSupervisorBindings.crashLoopMaxCount`.
  */
-export declare const DEFAULT_TERMINAL_WRITE_WATCHDOG_MS = 30000;
+export declare const DEFAULT_CRASH_LOOP_MAX_COUNT = 3;
+/**
+ * Default sliding window (ms) over which `DEFAULT_CRASH_LOOP_MAX_COUNT`
+ * unexpected exits latch the deployment. Overridable via
+ * `WorkflowSupervisorBindings.crashLoopWindowMs`.
+ */
+export declare const DEFAULT_CRASH_LOOP_WINDOW_MS = 60000;
+/**
+ * Default stable-run duration (ms): once a respawned child stays up this
+ * long, the crash counter resets so flapping followed by stability does
+ * not permanently latch. Overridable via
+ * `WorkflowSupervisorBindings.crashLoopStableResetMs`.
+ */
+export declare const DEFAULT_CRASH_LOOP_STABLE_RESET_MS = 60000;
+/**
+ * Default initial respawn backoff (ms): the wait before the first respawn
+ * after an unexpected exit. Overridable via
+ * `WorkflowSupervisorBindings.respawnBackoffInitialMs`.
+ */
+export declare const DEFAULT_RESPAWN_BACKOFF_INITIAL_MS = 1000;
+/**
+ * Default cap (ms) on the exponential respawn backoff. Kept below
+ * `DEFAULT_CRASH_LOOP_WINDOW_MS` so a slow flapper's crashes still fall
+ * within the window and latch the guard. Overridable via
+ * `WorkflowSupervisorBindings.respawnBackoffMaxMs`.
+ */
+export declare const DEFAULT_RESPAWN_BACKOFF_MAX_MS = 30000;
+/**
+ * Default watchdog for `reEmitParkedCorrelations`' wait on the child's
+ * `parked-correlations.response`. 30s is generous enough for a healthy child
+ * to enumerate its in-flight runs and load each parked snapshot, tight
+ * enough that a wedged-but-alive child does not hang the reconnect caller
+ * until some coarser timeout intervenes.
+ */
+export declare const DEFAULT_PARKED_QUERY_WATCHDOG_MS = 30000;
+/**
+ * Backstop for `waitForRunTerminalOrPark`. A dispatch waits here for the child
+ * to park or terminate the run before releasing `markConsumed`; a lost park
+ * wake or a wedged child would otherwise hang the deployment's dispatch loop
+ * forever. Five minutes is far beyond any healthy per-message dispatch (which
+ * settles in well under a second), so this never fires on a legitimately long
+ * run without also being a genuine fault -- and when it does fire it is logged
+ * loudly and fails the dispatch (the mail is left reclaimable, never consumed
+ * on the assumption the run made progress), not silently swallowed.
+ */
+export declare const TERMINAL_OR_PARK_BACKSTOP_MS = 300000;
 /**
  * Public surface returned by `createWorkflowSupervisor`. Each method
  * advances the supervisor through one lifecycle transition; the
@@ -89,6 +127,29 @@ export interface WorkflowSupervisor {
      * closing pipe. Throws otherwise.
      */
     deliverSources(opts: DeliverSourcesOpts): Promise<void>;
+    /**
+     * Push refreshed credential material to the child's in-memory cell. Mirrors
+     * `deliverSources`: the supervisor is the single producer of
+     * `credentials-updated` control frames, phase-guarded to starting/running so
+     * a frame is never written into a recycling child's closing pipe. A revoked
+     * credential is delivered by omitting its material so the child evicts it.
+     */
+    deliverCredentials(opts: DeliverCredentialsOpts): Promise<void>;
+    /**
+     * Re-register every correlation the child is currently parked on by
+     * querying it for its parked correlations and re-emitting each through
+     * `onSuspensionRegister`. Recovers a `park.notify` register the hub may have
+     * missed while it was down at suspend time.
+     *
+     * Best-effort and safe to call at any time, including concurrently. Unlike
+     * `deliverSignal`/`deliverSources`, which throw when the child is not
+     * addressable, this NO-OPS on a non-addressable phase (idle / stopping /
+     * stopped / recycling): a re-establishment landing mid-recycle must not
+     * crash, and the next spawn re-drives it. A query that fails or times out is
+     * logged and dropped; the hub co-write is idempotent, so the next
+     * re-establishment re-drives it. The caller need not guard the call site.
+     */
+    reEmitParkedCorrelations(): Promise<void>;
     /**
      * Current snapshot of the credentials pushed to the child. Surfaced
      * so the host can audit the per-step contentHash without
@@ -172,6 +233,14 @@ export type DeliverSourcesOpts = {
     /** The default source id; the wire boundary requires it to equal `sources[0].id`. */
     defaultSource: string;
 };
+export type DeliverCredentialsOpts = {
+    /**
+     * The refreshed credential material and per-handle descriptors. A revoked
+     * credential is delivered by omitting its material entry, so the child's
+     * wholesale swap evicts it.
+     */
+    delivery: CredentialDelivery;
+};
 export type RecycleOpts = {
     reason: string;
     /**
@@ -182,18 +251,6 @@ export type RecycleOpts = {
      */
     origin?: RecycleOrigin;
 };
-/**
- * Raised when a `pendingMerges` entry or a
- * `markConsumedCompletionWaiters` waiter is rejected because the
- * cohort it was registered against has been aborted (cohort transition
- * during a recycle, or a supervisor shutdown). Callers awaiting the
- * resolved value receive an instance of this error so the failure mode
- * is recognisable from a generic substrate-merge or markConsumed
- * failure.
- */
-export declare class MergeAbortedError extends Error {
-    constructor(reason: string);
-}
 /**
  * Construct a per-deployment supervisor. All host-specific
  * dependencies are pulled in via `bindings`; nothing in the