@blokjs/runner 0.2.1 → 0.4.0

package/dist/tracing/RunStore.d.ts

@@ -1,4 +1,4 @@
-import type { Dashboard, MetricsResult, NodeRun, RunEvent, RunQuery, TraceLogEntry, WorkflowRun, WorkflowSummary } from "./types";
+import type { CachedStepResult, ConcurrencySlotResult, Dashboard, MetricsResult, NodeRun, RunEvent, RunQuery, ScheduledDispatchRow, TraceLogEntry, WorkflowRun, WorkflowSummary } from "./types";
 /**
  * Storage abstraction for trace data.
  *
@@ -31,8 +31,107 @@ export interface RunStore {
     listDashboards(): Dashboard[];
     deleteDashboard(dashboardId: string): boolean;
     updateDashboard(dashboardId: string, updates: Partial<Dashboard>): void;
+    /**
+     * Return every run whose `parentRunId` matches the given run id, sorted
+     * oldest-first. Used by Studio's "Sub-runs" list on a parent's run-detail
+     * page. Returns `[]` when the run has no children.
+     */
+    getRunsByParent(parentRunId: string): WorkflowRun[];
     clearAll(): number;
     deleteRunsBefore(timestamp: number): number;
     evictOldRuns(maxRuns: number): void;
+    /**
+     * Look up a previously-cached step result. Returns null on miss or
+     * when the entry has expired (expired entries are lazily purged on read).
+     */
+    getIdempotencyCache(workflowName: string, stepId: string, key: string): CachedStepResult | null;
+    /**
+     * Store a step result keyed by (workflowName, stepId, key). Overwrites any
+     * previous entry for the same triple. Pass `expiresAt: null` for no TTL.
+     */
+    setIdempotencyCache(workflowName: string, stepId: string, key: string, entry: CachedStepResult): void;
+    /**
+     * Delete every entry whose `expiresAt` is non-null and `<= now`. Returns
+     * the number of rows removed. Cheap to call periodically; safe under
+     * concurrent reads.
+     */
+    purgeExpiredIdempotencyCache(now: number): number;
+    /**
+     * Try to acquire a slot for `(workflowName, concurrencyKey)`. Lazily
+     * purges expired leases for the same key first, then grants the slot
+     * iff `currentInFlight < concurrencyLimit`.
+     *
+     * Returns:
+     *   `{ acquired: true,  currentInFlight: <new count> }` on success
+     *   `{ acquired: false, currentInFlight: <observed count> }` on denial
+     *
+     * The lease has a hard upper bound (`leaseExpiresAt` in ms since epoch).
+     * Callers MUST release the slot in a `finally` block; the lease is the
+     * crash-safety net for processes that die before release.
+     */
+    acquireConcurrencySlot(workflowName: string, concurrencyKey: string, concurrencyLimit: number, runId: string, leaseExpiresAt: number): ConcurrencySlotResult;
+    /**
+     * Release a slot previously acquired by `runId`. Idempotent — releasing
+     * an unknown `runId` is a no-op (covers double-release races between
+     * the happy-path `finally` block and the lazy-purge fallback).
+     */
+    releaseConcurrencySlot(workflowName: string, concurrencyKey: string, runId: string): void;
+    /**
+     * Delete every lease whose `expiresAt <= now`. Returns the number of
+     * rows removed. Cheap to call periodically (e.g. from a janitor task);
+     * the gate also lazy-purges per-key on every acquire call.
+     */
+    purgeExpiredConcurrencySlots(now: number): number;
+    /**
+     * Snapshot of in-flight concurrency slots — used by the
+     * `/__blok/concurrency/state` endpoint and Studio's in-flight tile.
+     *
+     * Returns one entry per `(workflowName, concurrencyKey)` bucket with
+     * an array of currently-held leases (un-expired). Empty buckets are
+     * omitted. Sort order is unspecified — caller sorts as needed.
+     */
+    getConcurrencySnapshot(now: number): Array<{
+        workflowName: string;
+        concurrencyKey: string;
+        leases: Array<{
+            runId: string;
+            expiresAt: number;
+        }>;
+    }>;
+    /**
+     * Persist a scheduled dispatch row, or replace an existing one with
+     * the same `runId` (debounce reset, queue re-defer). Idempotent.
+     *
+     * Called by `DeferredRunScheduler.schedule()` when a `persist` payload
+     * is provided. The row carries everything the trigger needs to
+     * reconstruct dispatch on boot.
+     */
+    upsertScheduledDispatch(row: ScheduledDispatchRow): void;
+    /**
+     * Delete a scheduled dispatch row. Returns true when a row existed.
+     * Idempotent — safe to call on rows that have already been deleted
+     * (e.g. after the timer fires + cancel races).
+     */
+    deleteScheduledDispatch(runId: string): boolean;
+    /**
+     * List scheduled dispatches, optionally filtered by trigger type
+     * and/or status. Used by trigger boot recovery (HttpTrigger) to
+     * find rows it owns.
+     */
+    getScheduledDispatches(opts?: {
+        triggerType?: string;
+        status?: string;
+    }): ScheduledDispatchRow[];
+    /**
+     * Janitor sweep — delete every `scheduled_dispatches` row whose
+     * `expires_at` has elapsed (`expires_at IS NOT NULL AND expires_at < now`).
+     * Rows without a TTL are left alone (their owning runs may legitimately
+     * stay queued indefinitely). Returns the count of deleted rows.
+     *
+     * Forward-scheduled rows whose owning runs were deleted (orphan dispatch
+     * rows) get reaped on the next `HttpTrigger.recoverDispatches()` call,
+     * not here. This sweep only handles past-TTL rows.
+     */
+    purgeExpiredScheduledDispatches(now: number): number;
     close(): void;
 }

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, StartNodeOptions, StartRunOptions, TraceLogEntry, WorkflowRun, WorkflowSummary } from "./types";
 /** Webhook registration for run event notifications. */
 export interface Webhook {
     id: string;
@@ -28,28 +29,277 @@ export declare class RunTracker extends EventEmitter {
     get active(): boolean;
     startRun(opts: StartRunOptions): WorkflowRun;
     completeRun(runId: string, data?: unknown): void;
-    failRun(runId: string, error: Error): 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;
-    failNode(nodeRunId: string, error: Error): 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;
+    /**
+     * Record a streaming `Progress` frame for an in-flight node. Overwrites
+     * any previous progress (only the latest milestone is preserved on
+     * the {@link NodeRun} record). Emits a `NODE_PROGRESS` event so SSE
+     * subscribers (Studio) get the live update too.
+     *
+     * Master plan §17 Phase 5 follow-up — wires the proto `Progress`
+     * frame from `ExecuteStream` into the trace store + Studio.
+     *
+     * @param percent 0–100; values outside the range are clamped.
+     * @param phase optional free-form phase label (may be empty).
+     */
+    recordProgress(nodeRunId: string, percent: number, phase: string): void;
+    /**
+     * Record a streaming `PartialResult` snapshot for an in-flight node.
+     * Overwrites any previous snapshot. Emits a `NODE_PARTIAL_RESULT`
+     * event for SSE subscribers.
+     *
+     * Master plan §17 Phase 5 follow-up.
+     */
+    recordPartialResult(nodeRunId: string, snapshot: unknown): void;
     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;