@blokjs/runner 0.2.2 → 0.6.0

package/dist/tracing/RunTracker.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "node:events";
+import type { ConcurrencyBackend } from "../concurrency/ConcurrencyBackend";
 import type { RunStore } from "./RunStore";
-import type { Dashboard, MetricsResult, NodeRun, RunEvent, StartNodeOptions, StartRunOptions, TraceLogEntry, WorkflowRun, WorkflowRunStatus, WorkflowSummary } from "./types";
+import type { ConcurrencySlotResult, Dashboard, MetricsResult, NodeRun, RunEvent, RunQuery, SavedFilter, StartNodeOptions, StartRunOptions, TraceLogEntry, WorkflowRun, WorkflowSample, WorkflowSummary } from "./types";
 /** Webhook registration for run event notifications. */
 export interface Webhook {
     id: string;
@@ -29,8 +30,237 @@ export declare class RunTracker extends EventEmitter {
     startRun(opts: StartRunOptions): WorkflowRun;
     completeRun(runId: string, data?: unknown): void;
     failRun(runId: string, error: Error | unknown): void;
+    /**
+     * Tier 2 #6 — mark a run as throttled because the concurrency gate
+     * denied it before any step executed. Distinct from `failRun` because
+     * no step ran; nothing produced an error. Studio surfaces a Throttled
+     * badge and SSE subscribers see a granular `RUN_THROTTLED` event.
+     */
+    markRunThrottled(runId: string, info: {
+        concurrencyKey: string;
+        concurrencyLimit: number;
+        currentInFlight: number;
+    }): void;
+    /**
+     * Tier 2 #6 follow-up — mark a run as queued because the concurrency
+     * gate denied it AND the trigger is configured with `onLimit: "queue"`.
+     * The run will be re-attempted after `scheduledAt`; `scheduledAt` is
+     * persisted on the run record so Studio can render a "queued · retries
+     * at <time>" badge.
+     *
+     * Distinct from `markRunThrottled` because queued runs WILL eventually
+     * execute (or stay queued indefinitely until a slot frees), while
+     * throttled runs are terminal and `failRun` semantics are skipped.
+     *
+     * Caller is responsible for actually scheduling the retry via
+     * `DeferredRunScheduler`. This method only flips status + emits the
+     * `RUN_QUEUED` event. Re-marking with a later `scheduledAt` updates
+     * the field (used when re-defer happens after a timer-fired re-acquire
+     * also fails).
+     */
+    markRunQueued(runId: string, info: {
+        concurrencyKey: string;
+        concurrencyLimit: number;
+        currentInFlight: number;
+        scheduledAt: number;
+    }): void;
+    /**
+     * Tier 2 #5 — mark a run as `delayed`. Called immediately after
+     * `startRun` for runs that should be deferred. The run record carries
+     * `scheduledAt` (and optionally `expiresAt`) so Studio can render a
+     * "Delayed → fires at <time>" badge.
+     *
+     * Caller is responsible for actually scheduling the dispatch via
+     * `DeferredRunScheduler`. This method only flips status + emits the
+     * `RUN_DELAYED` event.
+     */
+    markRunDelayed(runId: string, info: {
+        scheduledAt: number;
+        delayMs: number;
+        expiresAt?: number;
+    }): void;
+    /**
+     * Tier 2 #5 — mark a run as `expired` because its TTL was exceeded
+     * before dispatch. Distinct from `failed` (no step ran) and
+     * `cancelled` (operator action — TTL is automatic).
+     */
+    markRunExpired(runId: string, info: {
+        expiresAt: number;
+        expiredAt: number;
+    }): void;
+    /**
+     * Tier 2 #7 — mark a run as `debounced`. In **leading** mode this is
+     * terminal: the ping was suppressed because a sibling fired
+     * immediately (`intoRunId` carries the sibling's id). In **trailing**
+     * mode this is transient: the same run is marked `debounced` while
+     * the timer is active and flips to `running` when the window closes
+     * (no separate transition method needed — `tracker` updates status
+     * directly via store before invoking the runner).
+     */
+    markRunDebounced(runId: string, info: {
+        debounceKey: string;
+        mode: "leading" | "trailing";
+        intoRunId?: string;
+        pingCount?: number;
+        scheduledAt?: number;
+    }): void;
+    /**
+     * Tier 2 quick-wins — mark a run as `crashed` (uncaught exception,
+     * OOM, signal). Distinct from `failRun` because the failure was
+     * NOT a step's `process()` throwing — it was the runner itself
+     * giving up. Currently manual; call from custom triggers / ops
+     * harnesses when uncaught failures are detected.
+     */
+    markRunCrashed(runId: string, info: {
+        error: Error | unknown;
+    }): void;
+    /**
+     * Tier 2 quick-wins follow-up — bulk-flip every run currently in
+     * `running` status to `crashed`. Returns the count flipped.
+     *
+     * Used by:
+     * - Process-level uncaught-exception handlers
+     *   (`TriggerBase.installCrashHandlers`) — flip in-flight runs
+     *   before the process dies.
+     * - Boot recovery (`TriggerBase.recoverOrphanedRuns`) — flip runs
+     *   that were `running` from the previous (dead) process.
+     *
+     * Synchronous + safe to call from a `process.on("uncaughtException")`
+     * handler (which can't await). Backed by sync sqlite/in-memory
+     * writes that complete before the handler returns.
+     *
+     * Optional `opts.maxStartedAt` filter — only flip runs whose
+     * `startedAt` is at or before this timestamp. Used by boot recovery
+     * to avoid flipping runs from the current (live) process.
+     */
+    markAllRunningRunsAsCrashed(error: Error | unknown, opts?: {
+        maxStartedAt?: number;
+    }): number;
+    /**
+     * Tier 2 quick-wins — mark a run as `timedOut` because a step's
+     * final retry attempt exceeded its `maxDuration` cap. Distinct
+     * from `failed` so SLA dashboards can separate timeout-driven
+     * failures (network / capacity) from logic failures (bugs).
+     * Auto-called by `RunnerSteps` on final-attempt `StepTimeoutError`.
+     */
+    markRunTimedOut(runId: string, info: {
+        stepId: string;
+        maxDurationMs: number;
+        attemptsExhausted: number;
+    }): void;
+    /**
+     * Tier 2 #7 — record an additional ping into an existing trailing-mode
+     * debounce window. Increments `pingCount` and updates `scheduledAt`.
+     * Does NOT emit a new event (avoid event-stream bloat under burst).
+     */
+    recordDebouncePing(runId: string, opts: {
+        pingCount: number;
+        scheduledAt: number;
+    }): void;
+    /**
+     * Tier 2 #7 — transition a `delayed`/`debounced` run into `running`
+     * when its timer fires. Studio sees the status change via the
+     * existing run-update SSE stream.
+     */
+    transitionRunToRunning(runId: string): void;
+    /**
+     * Tier 2 polish — cancel a pending (delayed/debounced/queued) run.
+     * Idempotent. Returns true when the run existed AND was in a cancellable
+     * state; false when the run doesn't exist OR is already running/completed/
+     * failed/throttled/expired/crashed/timedOut/cancelled.
+     *
+     * **Caller responsibility**: this method only updates the run record
+     * (status → `"cancelled"`) and emits `RUN_CANCELLED`. The caller must
+     * separately clear any pending scheduler timers via
+     * `DeferredRunScheduler.getInstance().cancel(runId)` and (when applicable)
+     * `DebounceCoordinator.getInstance().cancel(workflowName, debounceKey)`.
+     * Done this way to avoid an import cycle from tracing → scheduling.
+     */
+    cancelRun(runId: string, options?: {
+        cascade?: boolean;
+    }): boolean;
+    /**
+     * Per-process map from runId to the AbortController owned by the
+     * trigger's createContext call. Populated by TriggerBase right after
+     * `startRun()`; cleared in TriggerBase's finally block. Used by
+     * `abortRunningRun` to fire the signal when an operator cancels a
+     * `running` run via the cancel API.
+     */
+    private abortControllers;
+    registerAbortController(runId: string, controller: AbortController): void;
+    unregisterAbortController(runId: string): void;
+    /**
+     * Tier 2 follow-up · cooperative cancellation for `running` runs.
+     *
+     * Fires the run's AbortController (so `ctx.signal.aborted` becomes
+     * true and any node consulting it can abort early) AND flips the run
+     * status to `"cancelled"` immediately via `cancelRun`. RunnerSteps'
+     * between-step abort check throws `RunCancelledError` shortly after,
+     * which TriggerBase catches without re-flipping the status.
+     *
+     * Returns true when an AbortController was registered for this run
+     * AND the status was successfully flipped; false otherwise (run not
+     * found, run not in `running` status, or no controller registered —
+     * e.g. controller already cleaned up).
+     */
+    abortRunningRun(runId: string): boolean;
+    /**
+     * Tier 2 #6 follow-up · cross-process concurrency backend.
+     *
+     * When set (via {@link setConcurrencyBackend}), the tracker's
+     * `acquireConcurrencySlot` and `releaseConcurrencySlot` methods
+     * delegate to the backend instead of the local sync `RunStore` impl.
+     * Used to coordinate across processes via NATS KV / Redis.
+     *
+     * Default `null` — preserves zero-overhead in-process behavior.
+     * Trigger packages install a backend in `listen()` when the operator
+     * sets `BLOK_CONCURRENCY_BACKEND=nats-kv`.
+     */
+    private concurrencyBackend;
+    setConcurrencyBackend(backend: ConcurrencyBackend | null): void;
+    getConcurrencyBackend(): ConcurrencyBackend | null;
+    /**
+     * Acquire a concurrency slot for `(workflowName, concurrencyKey)`.
+     * Delegates to the configured cross-process backend when set; falls
+     * back to the local sync `RunStore` impl otherwise.
+     *
+     * Async — the cross-process backend (NATS KV) is async-only. The
+     * sync fallback is wrapped in `Promise.resolve()` so the call site
+     * is uniform.
+     */
+    acquireConcurrencySlot(workflowName: string, concurrencyKey: string, concurrencyLimit: number, runId: string, leaseExpiresAt: number): Promise<ConcurrencySlotResult>;
+    /** Release a slot acquired via `acquireConcurrencySlot`. Idempotent. */
+    releaseConcurrencySlot(workflowName: string, concurrencyKey: string, runId: string): Promise<void>;
     startNode(runId: string, opts: StartNodeOptions): NodeRun;
     completeNode(nodeRunId: string, outputs?: unknown, nodeMetrics?: NodeRun["metrics"]): void;
+    /**
+     * Tier 1 idempotency cache hit. Marks the node as completed without
+     * having actually run, attaches the source-run/source-node lineage so
+     * Studio can render a CACHED badge with click-through, and emits a
+     * `NODE_CACHED` event so SSE subscribers see the short-circuit live.
+     *
+     * Caller is responsible for replaying the cached result through
+     * `PersistenceHelper.applyStepOutput` — this method only records the
+     * tracing side. Caching layers ABOVE persistence, never within it.
+     */
+    markNodeCached(nodeRunId: string, source: {
+        sourceRunId: string;
+        sourceNodeRunId: string;
+        cachedAt: number;
+    }, outputs?: unknown): void;
+    /**
+     * Tier 1 retry: record a single failed attempt before the next retry. The
+     * node stays in `running` status — `failNode` is the terminal call that
+     * fires only after `retry.maxAttempts` is exhausted.
+     *
+     * Per-node attempt history is capped at {@link MAX_STORED_ATTEMPTS} (10)
+     * to bound store growth on extreme retry counts. The cap matches the
+     * risk-register decision in `tier1-idempotency-replay-retry.md`.
+     */
+    recordNodeAttemptFailed(nodeRunId: string, info: {
+        attempt: number;
+        error: unknown;
+    }): void;
     failNode(nodeRunId: string, error: Error | unknown): void;
     skipNode(runId: string, nodeName: string, stepIndex: number, reason?: string): void;
     /**
@@ -57,20 +287,19 @@ export declare class RunTracker extends EventEmitter {
     addLog(entry: Omit<TraceLogEntry, "id" | "timestamp">): void;
     trackVarsUpdate(runId: string, nodeName: string, nodeId: string | undefined, vars: Record<string, unknown>): void;
     getRun(runId: string): WorkflowRun | undefined;
-    getRuns(opts?: {
-        workflow?: string;
-        status?: WorkflowRunStatus;
-        tags?: string[];
-        limit?: number;
-        offset?: number;
-        sort?: "asc" | "desc";
-    }): {
+    getRuns(opts?: RunQuery): {
         runs: WorkflowRun[];
         total: number;
     };
     getNodeRuns(runId: string): NodeRun[];
     getNodeRun(nodeRunId: string): NodeRun | undefined;
     getEvents(runId: string, since?: number): RunEvent[];
+    /**
+     * Tier 2 sub-workflow lineage. Returns every run that was started by
+     * a `subworkflow:` step inside the given parent run. Powers Studio's
+     * "Sub-runs" list on a parent's run-detail page.
+     */
+    getRunsByParent(parentRunId: string): WorkflowRun[];
     getLogs(runId: string, nodeId?: string): TraceLogEntry[];
     getWorkflowSummaries(): WorkflowSummary[];
     addTag(runId: string, tag: string): boolean;
@@ -84,6 +313,12 @@ export declare class RunTracker extends EventEmitter {
     listDashboards(): Dashboard[];
     deleteDashboard(dashboardId: string): boolean;
     updateDashboard(dashboardId: string, updates: Partial<Dashboard>): void;
+    upsertSavedFilter(filter: SavedFilter): SavedFilter;
+    listSavedFilters(): SavedFilter[];
+    deleteSavedFilter(name: string): boolean;
+    recordWorkflowSample(sample: WorkflowSample): WorkflowSample;
+    getWorkflowSample(workflowName: string): WorkflowSample | undefined;
+    deleteWorkflowSample(workflowName: string): boolean;
     registerWebhook(opts: {
         url: string;
         events: string[];