@bratsos/workflow-engine-console 1.0.0-alpha.2

package/dist/index.js

@@ -0,0 +1,31 @@
+export { createWorkflowConsole } from './chunk-4RL6UAMS.js';
+export { PrismaConsoleReadPort, createPrismaConsoleReadPort } from './chunk-HUHLRNNM.js';
+export { ALL_CAPABILITIES, CONSOLE_STATUSES, ConsoleBadRequestError, ConsoleQueryTimeoutError, DEFAULT_RUN_LIMIT, MAX_LIMIT, clampLimit, decodeCursor, encodeCursor, isConsoleStatus, isStatementTimeout } from './chunk-THOZTVDT.js';
+
+// src/actions.ts
+var CONSOLE_ACTIONS = [
+  "runs.read",
+  "run.read",
+  "queue.read",
+  "suspended.read",
+  "deadLetters.read",
+  "workers.read",
+  "costs.read",
+  "run.cancel",
+  "run.rerun",
+  "step.signal",
+  "deadLetters.replay"
+];
+var WRITE_ACTIONS = [
+  "run.cancel",
+  "run.rerun",
+  "step.signal",
+  "deadLetters.replay"
+];
+function isWriteAction(action) {
+  return WRITE_ACTIONS.includes(action);
+}
+
+export { CONSOLE_ACTIONS, WRITE_ACTIONS, isWriteAction };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/actions.ts"],"names":[],"mappings":";;;;;AAcO,IAAM,eAAA,GAAkB;AAAA,EAC7B,WAAA;AAAA,EACA,UAAA;AAAA,EACA,YAAA;AAAA,EACA,gBAAA;AAAA,EACA,kBAAA;AAAA,EACA,cAAA;AAAA,EACA,YAAA;AAAA,EACA,YAAA;AAAA,EACA,WAAA;AAAA,EACA,aAAA;AAAA,EACA;AACF;AAKO,IAAM,aAAA,GAA0C;AAAA,EACrD,YAAA;AAAA,EACA,WAAA;AAAA,EACA,aAAA;AAAA,EACA;AACF;AAEO,SAAS,cAAc,MAAA,EAAgC;AAC5D,EAAA,OAAO,aAAA,CAAc,SAAS,MAAM,CAAA;AACtC","file":"index.js","sourcesContent":["/**\n * The console's write vocabulary.\n *\n * Modelled on verbs rather than HTTP methods, so an `authorize` callback\n * grants \"may cancel a run\" rather than \"may POST\". Every write dispatches\n * a kernel command — the console never issues SQL of its own. That is not\n * squeamishness: the kernel owns run state, and a console that wrote\n * `UPDATE workflow_runs SET status='CANCELLED'` would be a second,\n * unaudited writer against state the kernel believes it is alone in\n * changing, skipping the leases, idempotency and outbox events every other\n * path goes through.\n */\n\n/** Every action the console can be asked to perform, read or write. */\nexport const CONSOLE_ACTIONS = [\n  \"runs.read\",\n  \"run.read\",\n  \"queue.read\",\n  \"suspended.read\",\n  \"deadLetters.read\",\n  \"workers.read\",\n  \"costs.read\",\n  \"run.cancel\",\n  \"run.rerun\",\n  \"step.signal\",\n  \"deadLetters.replay\",\n] as const;\n\nexport type ConsoleAction = (typeof CONSOLE_ACTIONS)[number];\n\n/** The subset that changes state. Each is refused unless `actions` is enabled. */\nexport const WRITE_ACTIONS: readonly ConsoleAction[] = [\n  \"run.cancel\",\n  \"run.rerun\",\n  \"step.signal\",\n  \"deadLetters.replay\",\n] as const;\n\nexport function isWriteAction(action: ConsoleAction): boolean {\n  return WRITE_ACTIONS.includes(action);\n}\n\n/**\n * The minimum of the engine's kernel the console needs: a dispatcher.\n *\n * Declared structurally rather than imported so the package carries no\n * runtime dependency on the engine and nothing in the engine can come to\n * depend on the console.\n */\nexport interface ConsoleKernel {\n  dispatch(command: {\n    readonly type: string;\n    readonly [key: string]: unknown;\n  }): Promise<unknown>;\n}\n\n/** What `authorize` is asked, and what `onAction` is told afterwards. */\nexport interface ConsoleAuthorizeContext {\n  action: ConsoleAction;\n  request: Request;\n  /** Present for the actions scoped to one run. */\n  runId?: string;\n  /** Present for the actions scoped to one durable step (`step.signal`). */\n  stageId?: string;\n  stepId?: string;\n}\n\nexport interface ConsoleActionEvent {\n  action: ConsoleAction;\n  runId?: string;\n  stageId?: string;\n  stepId?: string;\n  request: Request;\n  result: unknown;\n  at: Date;\n}\n"]}

package/dist/node.d.ts

@@ -0,0 +1,15 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { W as WorkflowConsoleHandler } from './handler-Cq2cVh7p.js';
+import './actions-DOP8plrl.js';
+import './read-port-CRmaGAKb.js';
+
+/**
+ * Adapt the fetch handler to Node's `http` request/response pair.
+ *
+ * Only Express, Fastify and bare `node:http` need this. Next.js route
+ * handlers, Hono, Cloudflare Workers, Deno and Bun all speak `Request` and
+ * `Response` natively, so they mount the handler directly — see the README.
+ */
+declare function toNodeHandler(handler: WorkflowConsoleHandler): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+
+export { toNodeHandler };

package/dist/node.js

@@ -0,0 +1,3 @@
+export { toNodeHandler } from './chunk-RCVZ3AP4.js';
+//# sourceMappingURL=node.js.map
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"node.js"}

package/dist/prisma-read-port-GPAHJEVC.js

@@ -0,0 +1,4 @@
+export { PrismaConsoleReadPort, createPrismaConsoleReadPort } from './chunk-HUHLRNNM.js';
+import './chunk-THOZTVDT.js';
+//# sourceMappingURL=prisma-read-port-GPAHJEVC.js.map
+//# sourceMappingURL=prisma-read-port-GPAHJEVC.js.map

package/dist/prisma-read-port-GPAHJEVC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"prisma-read-port-GPAHJEVC.js"}

package/dist/read-port-CRmaGAKb.d.ts

@@ -0,0 +1,257 @@
+/**
+ * The console's read contract.
+ *
+ * Everything the console can show is expressed here, and nothing else in
+ * the package reaches for a database. An implementation is handed the
+ * connection its caller already has — a Prisma client, or the transaction
+ * client the caller opened — and never opens one of its own. That is the
+ * property the whole design exists to preserve: a consumer running the
+ * kernel inside one transaction per tenant, under row-level security, gets
+ * the console's reads inside that same transaction, evaluated against the
+ * same policies, with authentication already decided upstream. A reader
+ * that dialled the database itself would be a second session and therefore
+ * a second security context, and no amount of configuration recovers the
+ * tenant scoping once that happens.
+ *
+ * The interface is declared here rather than added to the engine's
+ * `PersistenceCore` on purpose — see the note in the package README. It is
+ * a small, optional surface; making it a required part of the persistence
+ * port would break every third-party adapter for a feature that is
+ * explicitly optional.
+ */
+/** Run/stage/job lifecycle states, mirroring the engine's `Status` enum. */
+type ConsoleStatus = "PENDING" | "RUNNING" | "SUSPENDED" | "COMPLETED" | "FAILED" | "CANCELLED" | "SKIPPED";
+declare const CONSOLE_STATUSES: readonly ConsoleStatus[];
+declare function isConsoleStatus(value: string): value is ConsoleStatus;
+/** One row of the runs list. Deliberately excludes `input`/`output`/`config`: a list page must not carry payloads. */
+interface RunSummary {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+    workflowId: string;
+    workflowName: string;
+    workflowType: string;
+    status: ConsoleStatus;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    duration: number | null;
+    totalCost: number;
+    totalTokens: number;
+    priority: number;
+    definitionVersion: string | null;
+    redriveCount: number;
+}
+interface StageSummary {
+    id: string;
+    workflowRunId: string;
+    stageId: string;
+    stageName: string;
+    stageNumber: number;
+    executionGroup: number;
+    attempt: number;
+    status: ConsoleStatus;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    duration: number | null;
+    nextPollAt: Date | null;
+    pollInterval: number | null;
+    maxWaitUntil: Date | null;
+    errorMessage: string | null;
+}
+/** A durable-step ledger entry. `status` is a free-form string in the schema, so it stays one here. */
+interface StepSummary {
+    id: string;
+    stageRecordId: string;
+    stepId: string;
+    seq: number;
+    kind: string;
+    status: string;
+    attempt: number;
+    leaseExpiresAt: Date | null;
+    deadlineAt: Date | null;
+    /** Deterministic name of the external effect a `run` step creates; null for other kinds. */
+    externalKey: string | null;
+    error: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface AnnotationSummary {
+    id: string;
+    createdAt: Date;
+    workflowRunId: string;
+    workflowStageRecordId: string | null;
+    attempt: number;
+    scope: string;
+    scopeId: string | null;
+    actorKind: string | null;
+    actorId: string | null;
+    key: string;
+    value: unknown;
+}
+interface LogEntry {
+    id: string;
+    createdAt: Date;
+    workflowRunId: string | null;
+    workflowStageId: string | null;
+    level: string;
+    message: string;
+}
+/**
+ * One retained outbox row, read as a run's event timeline. The engine marks
+ * events published rather than deleting them, and `(workflowRunId, sequence)`
+ * is unique, so a run timeline is an index range scan.
+ */
+interface RunEvent {
+    id: string;
+    workflowRunId: string;
+    sequence: number;
+    eventType: string;
+    occurredAt: Date;
+    publishedAt: Date | null;
+    retryCount: number;
+    dlqAt: Date | null;
+}
+interface RunDetail {
+    run: RunSummary & {
+        input: unknown;
+        output: unknown;
+        config: unknown;
+        metadata: unknown;
+    };
+    stages: StageSummary[];
+    steps: StepSummary[];
+    annotations: AnnotationSummary[];
+    logs: LogEntry[];
+    events: RunEvent[];
+    /** True when a list was cut off by its limit, so the UI can say so instead of implying completeness. */
+    truncated: {
+        steps: boolean;
+        annotations: boolean;
+        logs: boolean;
+        events: boolean;
+    };
+}
+interface RunListFilters {
+    status?: ConsoleStatus[];
+    workflowId?: string;
+    workflowType?: string;
+    createdAfter?: Date;
+    createdBefore?: Date;
+    definitionVersion?: string;
+}
+interface RunListQuery {
+    filters?: RunListFilters;
+    /** Opaque cursor from a previous page's `nextCursor`. Keyset, not offset. */
+    cursor?: string;
+    limit?: number;
+}
+interface RunListPage {
+    runs: RunSummary[];
+    nextCursor: string | null;
+}
+interface QueueHealth {
+    countsByStatus: Record<ConsoleStatus, number>;
+    /** Enqueue time of the oldest job still waiting to be picked up. */
+    oldestPendingAt: Date | null;
+    /** `lockedAt` of the longest-held lease among running jobs — a lease older than your reaper's threshold is a stuck worker. */
+    oldestLeaseAt: Date | null;
+    /** Suspended jobs whose `nextPollAt` is already in the past. */
+    overduePolls: number;
+}
+/**
+ * A worker, derived from the leases it holds. The engine has no worker
+ * registry table; `touchJob` refreshes `job_queue.lockedAt`, so the newest
+ * lease a worker holds is the best available heartbeat, and a worker with
+ * no running job is invisible here by construction.
+ */
+interface WorkerInstance {
+    workerId: string;
+    runningJobs: number;
+    oldestLockedAt: Date | null;
+    /** Most recent `touchJob`; the console renders `now - lastSeenAt` as heartbeat age. */
+    lastSeenAt: Date | null;
+}
+interface SuspendedStage {
+    id: string;
+    workflowRunId: string;
+    workflowId: string;
+    stageId: string;
+    stageName: string;
+    attempt: number;
+    nextPollAt: Date | null;
+    pollInterval: number | null;
+    maxWaitUntil: Date | null;
+}
+interface DeadLetter {
+    id: string;
+    workflowRunId: string;
+    sequence: number;
+    eventType: string;
+    retryCount: number;
+    occurredAt: Date;
+    dlqAt: Date | null;
+}
+interface CostBucket {
+    /** A workflow id, or an ISO date (`YYYY-MM-DD`) when bucketing by day. */
+    key: string;
+    runs: number;
+    cost: number;
+    tokens: number;
+}
+interface CostQuery {
+    by: "workflow" | "day";
+    from?: Date;
+    to?: Date;
+}
+/**
+ * What a given reader can actually serve, so the UI hides what is not there
+ * rather than rendering an empty page. Adapters that predate a view, or
+ * schemas whose migrations lag, report `false` and the tab disappears.
+ */
+interface ConsoleCapabilities {
+    runs: boolean;
+    steps: boolean;
+    annotations: boolean;
+    queue: boolean;
+    suspended: boolean;
+    deadLetters: boolean;
+    workers: boolean;
+    costs: boolean;
+}
+declare const ALL_CAPABILITIES: ConsoleCapabilities;
+interface RunDetailOptions {
+    stepLimit?: number;
+    annotationLimit?: number;
+    logLimit?: number;
+    eventLimit?: number;
+}
+interface ConsoleReadPort {
+    readonly capabilities: ConsoleCapabilities;
+    listRuns(query: RunListQuery): Promise<RunListPage>;
+    getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
+    /** Incremental tail of one run's timeline. `afterSequence` of 0 returns from the start. */
+    listRunEvents(runId: string, afterSequence: number, limit?: number): Promise<RunEvent[]>;
+    getQueueHealth(): Promise<QueueHealth>;
+    listSuspendedStages(limit?: number): Promise<SuspendedStage[]>;
+    listDeadLetters(limit?: number): Promise<DeadLetter[]>;
+    listWorkers(): Promise<WorkerInstance[]>;
+    getCosts(query: CostQuery): Promise<CostBucket[]>;
+}
+/** Default page size for the runs list. */
+declare const DEFAULT_RUN_LIMIT = 50;
+/** Hard ceiling on any page size, whatever the request asks for. */
+declare const MAX_LIMIT = 200;
+declare function clampLimit(requested: number | undefined, fallback?: number): number;
+/**
+ * Keyset cursors are `(createdAt, id)` — the exact tuple the composite
+ * indexes carry — encoded as opaque text so callers cannot turn one into an
+ * offset. Offset pagination is what makes page 400 a sequential scan.
+ */
+interface RunCursor {
+    createdAt: Date;
+    id: string;
+}
+declare function encodeCursor(cursor: RunCursor): string;
+declare function decodeCursor(raw: string): RunCursor | null;
+
+export { ALL_CAPABILITIES as A, type ConsoleReadPort as C, type DeadLetter as D, type LogEntry as L, MAX_LIMIT as M, type QueueHealth as Q, type RunListQuery as R, type SuspendedStage as S, type WorkerInstance as W, type ConsoleCapabilities as a, type RunListPage as b, type RunDetailOptions as c, type RunDetail as d, type RunEvent as e, type CostQuery as f, type CostBucket as g, type AnnotationSummary as h, CONSOLE_STATUSES as i, type ConsoleStatus as j, DEFAULT_RUN_LIMIT as k, type RunCursor as l, type RunListFilters as m, type RunSummary as n, type StageSummary as o, type StepSummary as p, clampLimit as q, decodeCursor as r, encodeCursor as s, isConsoleStatus as t };

package/dist/testing.d.ts

@@ -0,0 +1,50 @@
+import { n as RunSummary, o as StageSummary, p as StepSummary, h as AnnotationSummary, L as LogEntry, e as RunEvent, j as ConsoleStatus, C as ConsoleReadPort, a as ConsoleCapabilities, R as RunListQuery, b as RunListPage, c as RunDetailOptions, d as RunDetail, Q as QueueHealth, S as SuspendedStage, D as DeadLetter, W as WorkerInstance, f as CostQuery, g as CostBucket } from './read-port-CRmaGAKb.js';
+
+/** Mutable fixture store. Every array defaults to empty. */
+interface ConsoleFixtures {
+    runs?: Array<Omit<RunSummary, "definitionVersion" | "redriveCount"> & {
+        definitionVersion?: string | null;
+        redriveCount?: number;
+        input?: unknown;
+        output?: unknown;
+        config?: unknown;
+        metadata?: unknown;
+    }>;
+    stages?: StageSummary[];
+    steps?: StepSummary[];
+    annotations?: AnnotationSummary[];
+    logs?: LogEntry[];
+    events?: RunEvent[];
+    /** job_queue rows, reduced to what the console reads off them. */
+    jobs?: Array<{
+        id: string;
+        workflowRunId: string;
+        stageId: string;
+        status: ConsoleStatus;
+        createdAt: Date;
+        workerId?: string | null;
+        lockedAt?: Date | null;
+        nextPollAt?: Date | null;
+    }>;
+}
+interface InMemoryConsoleReadPortOptions {
+    now?: () => Date;
+    capabilities?: Partial<ConsoleCapabilities>;
+}
+declare class InMemoryConsoleReadPort implements ConsoleReadPort {
+    readonly capabilities: ConsoleCapabilities;
+    readonly fixtures: Required<ConsoleFixtures>;
+    private readonly now;
+    constructor(fixtures?: ConsoleFixtures, options?: InMemoryConsoleReadPortOptions);
+    listRuns(query: RunListQuery): Promise<RunListPage>;
+    getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
+    listRunEvents(runId: string, afterSequence: number, limit?: number): Promise<RunEvent[]>;
+    getQueueHealth(): Promise<QueueHealth>;
+    listSuspendedStages(limit?: number): Promise<SuspendedStage[]>;
+    listDeadLetters(limit?: number): Promise<DeadLetter[]>;
+    listWorkers(): Promise<WorkerInstance[]>;
+    getCosts(query: CostQuery): Promise<CostBucket[]>;
+}
+declare function createInMemoryConsoleReadPort(fixtures?: ConsoleFixtures, options?: InMemoryConsoleReadPortOptions): InMemoryConsoleReadPort;
+
+export { type ConsoleFixtures, InMemoryConsoleReadPort, type InMemoryConsoleReadPortOptions, createInMemoryConsoleReadPort };