octaflow 0.14.0

package/dist/logger-BCus3AOa.d.ts

@@ -0,0 +1,10 @@
+//#region src/core/logger.d.ts
+type LogAttributes = Record<string, unknown>;
+interface Logger {
+  info(message: string, attributes?: LogAttributes): void;
+  warn(message: string, attributes?: LogAttributes): void;
+  error(message: string, error?: Error, attributes?: LogAttributes): void;
+}
+declare const noopLogger: Logger;
+//#endregion
+export { Logger as n, noopLogger as r, LogAttributes as t };

package/dist/observability-BsrvbhDr.d.ts

@@ -0,0 +1,249 @@
+import { F as StepId, G as WorkflowWithSteps, I as StepRecord, U as WorkflowRecord, V as WorkflowId, W as WorkflowStatus } from "./index-D_fOYfmf.js";
+//#region src/core/store.d.ts
+interface CreateWorkflowStep {
+  key: string;
+  type: string;
+  dependencies: string[];
+  input: Record<string, unknown> | null;
+}
+/** A map child step to insert at runtime. */
+interface AddChildStep {
+  /** Synthetic key, e.g. `${parentKey}#${index}`. */
+  key: string;
+  type: string;
+  input: Record<string, unknown> | null;
+}
+interface CreateWorkflowParams {
+  type: string;
+  input: Record<string, unknown>;
+  entityRef?: string;
+  metadata?: Record<string, unknown>;
+  /** Dedup key (per partition); a collision returns the existing workflow. */
+  idempotencyKey?: string;
+  /** Sub-workflow linkage: the parent workflow + step that started this child. */
+  parentWorkflowId?: WorkflowId;
+  parentStepId?: StepId;
+  startedAt: string;
+  steps: CreateWorkflowStep[];
+}
+interface CreatedWorkflow {
+  workflowId: WorkflowId;
+  /** The step rows (new on insert, existing on an idempotency hit) — used to enqueue roots. */
+  steps: StepRecord[];
+  /**
+   * True when `idempotencyKey` matched an existing workflow and nothing new was created.
+   * The engine then returns the existing workflow without re-enqueuing roots.
+   */
+  alreadyExisted: boolean;
+}
+interface CompleteStepParams {
+  workflowId: WorkflowId;
+  stepId: StepId;
+  output: Record<string, unknown>;
+  completedAt: string;
+}
+interface FailStepParams {
+  workflowId: WorkflowId;
+  stepId: StepId;
+  error: string;
+  completedAt: string;
+}
+interface FinishWorkflowParams {
+  workflowId: WorkflowId;
+  status: Extract<WorkflowStatus, 'completed' | 'failed' | 'cancelled'>;
+  output?: Record<string, unknown>;
+  error?: string;
+  completedAt: string;
+}
+interface ListWorkflowsFilters {
+  status?: WorkflowStatus;
+  type?: string;
+  entityRef?: string;
+  limit?: number;
+}
+/**
+ * Persistence boundary for the engine. Implementations are **partition-scoped at
+ * construction** (e.g. bound to one tenant) — exactly like the engine — so methods
+ * never take a partition key. The default adapter is Postgres/Drizzle.
+ *
+ * Counter ownership: `completeStep` MUST atomically increment the workflow's
+ * `completedSteps`; `failStep` MUST atomically increment `failedSteps`. The engine
+ * relies on these counters only for progress reporting — readiness and termination
+ * are computed from `listSteps`.
+ */
+interface WorkflowStore {
+  /** Create the workflow + all step rows atomically (transactional). */
+  createWorkflow(params: CreateWorkflowParams): Promise<CreatedWorkflow>;
+  getWorkflow(workflowId: WorkflowId): Promise<WorkflowRecord | null>;
+  getStep(stepId: StepId): Promise<StepRecord | null>;
+  listSteps(workflowId: WorkflowId): Promise<StepRecord[]>;
+  /**
+   * **Atomically claim** a step: flip it to `running`, set `startedAt` and increment
+   * `attempts` — but **only if it is still `pending`**. Returns `true` if this caller
+   * won the claim, `false` if the step had already left `pending` (another worker
+   * claimed it, or it was cancelled/skipped meanwhile).
+   *
+   * Implementations MUST make the status check and the write a single atomic
+   * operation (e.g. `UPDATE … WHERE id = $1 AND status = 'pending'` and report
+   * whether a row matched). A read-then-write would let two workers handed the
+   * same job by an at-least-once dispatcher both run the handler.
+   */
+  markStepRunning(stepId: StepId, startedAt: string): Promise<boolean>;
+  /** Reset a step to `pending` for a scheduled retry (leaves `attempts` as-is). */
+  markStepPending(stepId: StepId): Promise<void>;
+  /** Flip a ready step to `waiting` — it suspends until `resumeStep` (waitForEvent). */
+  markStepWaiting(stepId: StepId): Promise<void>;
+  /** Flip a map parent to `mapping` — it suspends until all spawned children finish. */
+  markStepMapping(stepId: StepId): Promise<void>;
+  /** Flip a completed step to `compensating` while its rollback handler runs. */
+  markStepCompensating(stepId: StepId): Promise<void>;
+  /** Flip a step to `compensated`; optionally record a compensation error for surfacing. */
+  markStepCompensated(stepId: StepId, error?: string): Promise<void>;
+  /** Insert map child step rows at runtime and return them with ids. */
+  addChildSteps(workflowId: WorkflowId, parentStepId: StepId, children: AddChildStep[]): Promise<StepRecord[]>;
+  /** List the child steps of a map parent, ordered by creation (item order). */
+  listChildSteps(parentStepId: StepId): Promise<StepRecord[]>;
+  /** Flip a step to `completed`, persist output, and increment `completedSteps`. */
+  completeStep(params: CompleteStepParams): Promise<void>;
+  /** Flip a step to `failed`, persist error, and increment `failedSteps`. */
+  failStep(params: FailStepParams): Promise<void>;
+  /** Flip a single pending/ready step to `skipped`. */
+  skipStep(stepId: StepId, reason: string): Promise<void>;
+  /** Flip every still-pending or `waiting` step of a workflow to `skipped` (used on cancel). */
+  skipPendingSteps(workflowId: WorkflowId, reason: string): Promise<void>;
+  /** Transition the workflow to a terminal state. */
+  finishWorkflow(params: FinishWorkflowParams): Promise<void>;
+  /** List workflows (with their steps) for status/dashboard reads. */
+  listWorkflows(filters: ListWorkflowsFilters): Promise<WorkflowWithSteps[]>;
+  /** All workflows currently in `running` state (for the stuck-step sweeper). */
+  listRunningWorkflows(): Promise<WorkflowRecord[]>;
+  /** Steps stuck in `running` with `startedAt` older than `cutoff` (ISO string). */
+  findStuckSteps(workflowId: WorkflowId, cutoff: string): Promise<StepRecord[]>;
+}
+//#endregion
+//#region src/core/gate.d.ts
+interface StepGateRequest {
+  partitionKey: string;
+  workflowId: WorkflowId;
+  stepId: StepId;
+  stepKey: string;
+  stepType: string;
+}
+type StepGateDecision = {
+  admitted: true;
+  release(): void | Promise<void>;
+} | {
+  admitted: false;
+  retryAfterSeconds: number;
+};
+/**
+ * Admission control consulted by the engine **before** a step runs. Return
+ * `{ admitted: false, retryAfterSeconds }` to defer the step — it is re-enqueued with
+ * that delay and **no attempt is consumed** — or `{ admitted: true, release }` with a
+ * `release` the engine calls when the step finishes (success, terminal failure, or
+ * retry-reschedule).
+ *
+ * The shipped {@link createInMemoryStepGate} is **per-process** — correct for a single
+ * worker and for tests. For a multi-worker concurrency cap, implement this against a
+ * shared store (e.g. a leases table); the contract is identical.
+ */
+interface StepGate {
+  acquire(req: StepGateRequest): Promise<StepGateDecision>;
+}
+/** Max concurrently-running steps of a given type (per process). */
+interface ConcurrencyRule {
+  maxConcurrent: number;
+}
+/** Token-bucket throughput limit for a given step type. */
+interface RateRule {
+  /** Sustained rate, tokens per second. */
+  perSecond: number;
+  /** Bucket capacity (max burst). Defaults to `max(1, ceil(perSecond))`. */
+  burst?: number;
+}
+interface InMemoryStepGateConfig {
+  /** Per-stepType concurrency caps. */
+  concurrency?: Record<string, ConcurrencyRule>;
+  /** Per-stepType token-bucket rate limits. */
+  rateLimit?: Record<string, RateRule>;
+  /** Retry delay (seconds) returned when a concurrency cap is hit. Default 1. */
+  concurrencyRetrySeconds?: number;
+  /** Clock injection for tests (ms epoch). Defaults to `Date.now`. */
+  now?: () => number;
+}
+/**
+ * A per-process {@link StepGate}: per-stepType concurrency caps (held slots) plus
+ * per-stepType token-bucket rate limits (throughput). Both are optional and checked
+ * per step type; a step type with no rule is always admitted.
+ *
+ * Concurrency is reserved first, then the rate token — so a rate denial does not waste
+ * a concurrency slot. Good for single-worker deployments; swap in a shared-store gate
+ * for multi-worker concurrency control.
+ */
+declare function createInMemoryStepGate(config?: InMemoryStepGateConfig): StepGate;
+//#endregion
+//#region src/core/observability.d.ts
+/** Lifecycle event types the engine emits at every workflow/step transition. */
+type FlowEventType = 'workflow.started' | 'workflow.completed' | 'workflow.failed' | 'workflow.cancelled' | 'step.started' | 'step.completed' | 'step.failed' | 'step.retrying' | 'step.skipped' | 'step.waiting' | 'step.resumed' | 'step.mapping' | 'step.compensating' | 'step.compensated';
+/**
+ * An append-only run-history record. The engine emits one per transition; an observer can
+ * persist it (a timeline), turn it into OpenTelemetry metrics (counters/histograms), or both.
+ */
+interface FlowEvent {
+  type: FlowEventType;
+  /** ISO timestamp of the transition. */
+  at: string;
+  partitionKey: string;
+  workflowId: WorkflowId;
+  workflowType?: string;
+  stepId?: StepId;
+  stepKey?: string;
+  stepType?: string;
+  /** Execution attempt number (for step events). */
+  attempt?: number;
+  /** Wall-clock duration of the step run in ms (for step.completed / step.failed). */
+  durationMs?: number;
+  error?: string;
+}
+/**
+ * Sink for run-history / metrics. Implementations **must not throw** and should be cheap
+ * (fire-and-forget) — the engine guards calls but never awaits them. Wire a Postgres event
+ * sink for history, or an OTel-meter adapter for metrics. Defaults to a no-op.
+ */
+interface FlowObserver {
+  record(event: FlowEvent): void;
+}
+declare const noopObserver: FlowObserver;
+/** In-memory observer that accumulates events — for tests and introspection. */
+interface RecordingObserver extends FlowObserver {
+  readonly events: FlowEvent[];
+  clear(): void;
+}
+declare function createRecordingObserver(): RecordingObserver;
+/** A minimal span handle. Maps 1:1 onto an OpenTelemetry span in an adapter. */
+interface FlowSpan {
+  setAttribute(key: string, value: string | number | boolean): void;
+  recordError(error: Error): void;
+  end(): void;
+}
+/**
+ * A minimal tracer. The engine wraps each `executeStep` in a span. Provide an OTel-backed
+ * adapter (`startSpan` → `tracer.startSpan`) to get distributed traces; defaults to a no-op.
+ */
+interface FlowTracer {
+  startSpan(name: string, attributes?: Record<string, string | number | boolean>): FlowSpan;
+}
+declare const noopTracer: FlowTracer;
+/** A span captured in memory — for tests. */
+interface RecordedSpan {
+  name: string;
+  attributes: Record<string, string | number | boolean>;
+  error?: string;
+  ended: boolean;
+}
+interface RecordingTracer extends FlowTracer {
+  readonly spans: RecordedSpan[];
+}
+declare function createRecordingTracer(): RecordingTracer;
+//#endregion
+export { CreateWorkflowStep as C, ListWorkflowsFilters as D, FinishWorkflowParams as E, WorkflowStore as O, CreateWorkflowParams as S, FailStepParams as T, StepGateDecision as _, FlowTracer as a, AddChildStep as b, RecordingTracer as c, noopObserver as d, noopTracer as f, StepGate as g, RateRule as h, FlowSpan as i, createRecordingObserver as l, InMemoryStepGateConfig as m, FlowEventType as n, RecordedSpan as o, ConcurrencyRule as p, FlowObserver as r, RecordingObserver as s, FlowEvent as t, createRecordingTracer as u, StepGateRequest as v, CreatedWorkflow as w, CompleteStepParams as x, createInMemoryStepGate as y };

package/dist/store-pg/index.d.ts

@@ -0,0 +1,195 @@
+import { V as WorkflowId } from "../index-D_fOYfmf.js";
+import { O as WorkflowStore, g as StepGate, h as RateRule, p as ConcurrencyRule, r as FlowObserver, t as FlowEvent } from "../observability-BsrvbhDr.js";
+import { Pool } from "pg";
+//#region src/store-pg/ddl.d.ts
+/**
+ * Schema for the Postgres WorkflowStore adapter. Two tables mirror flow-core's
+ * record shapes. Apply once at deploy time (or call `applySchema`).
+ *
+ * `partition_key` is the generic multi-tenancy column (the engine/store are bound
+ * to one partition). Add Row Level Security on top if you need hard isolation.
+ */
+declare function flowStoreDdl(schema?: string): string;
+/** Default-schema DDL string. */
+declare const FLOW_STORE_DDL: string;
+/** `CREATE SCHEMA IF NOT EXISTS` line for non-default schemas; empty for 'public'. */
+declare function createSchemaDdl(schema: string): string;
+//#endregion
+//#region src/store-pg/executor.d.ts
+/** Minimal query result shape the adapters consume (a structural subset of `pg`'s `QueryResult`). */
+interface SqlResult<R> {
+  rows: R[];
+  rowCount: number | null;
+}
+/**
+ * A Postgres adapter's only contact with the database. Adapters issue raw
+ * parameterized SQL through this seam and never open their own connections, so
+ * the *host* decides how queries run: a plain pool ({@link poolExecutor}), or a
+ * connection that first sets transaction-local GUCs for Row Level Security.
+ *
+ * `transaction(fn)` MUST run every `fn` query on a single connection inside one
+ * DB transaction; the passed executor is that same-connection handle. Adapters
+ * never nest transactions.
+ */
+interface SqlExecutor {
+  query<R = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<SqlResult<R>>;
+  transaction<T>(fn: (tx: SqlExecutor) => Promise<T>): Promise<T>;
+}
+/**
+ * Build a {@link SqlExecutor} over a `pg` {@link Pool}: top-level queries run on
+ * the pool (autocommit); `transaction` checks out a client and wraps `fn` in
+ * `BEGIN`/`COMMIT` (rolling back and always releasing on error). This is the
+ * batteries-included executor used by the `createPg*` adapters.
+ */
+declare function poolExecutor(pool: Pool): SqlExecutor;
+/**
+ * Normalize a `Pool | SqlExecutor` argument to a {@link SqlExecutor}. Lets the
+ * read helpers accept either the batteries-included pool or a host's RLS-scoped
+ * executor without a breaking signature change. `SqlExecutor` is discriminated by
+ * its `transaction` method (a `pg` `Pool` has none).
+ */
+declare function toExecutor(db: Pool | SqlExecutor): SqlExecutor;
+//#endregion
+//#region src/store-pg/store.d.ts
+interface PgWorkflowStoreDeps {
+  pool: Pool;
+  /** Partition this store instance is bound to (e.g. a tenant id). */
+  partitionKey: string;
+  /** Schema the flow tables live in. Default 'public'. */
+  schema?: string;
+}
+interface WorkflowStoreDeps {
+  /** How the store talks to Postgres (pool-backed, RLS-scoped, …). */
+  exec: SqlExecutor;
+  /** Partition this store instance is bound to (e.g. a tenant id). */
+  partitionKey: string;
+  /** Schema the flow tables live in. Default 'public'. */
+  schema?: string;
+}
+/**
+ * A `WorkflowStore` over Postgres, addressing raw parameterized SQL through an
+ * injected {@link SqlExecutor}. Partition-scoped at construction; every query is
+ * additionally filtered by `partition_key` as defense-in-depth. Requires the two
+ * tables from `flowStoreDdl()`.
+ *
+ * The executor decides *how* queries run: {@link createPgWorkflowStore} wires a
+ * plain pool; a host that wants Row Level Security injects an executor whose
+ * `transaction` sets the tenant GUC, so the store's own transactions run scoped.
+ */
+declare function createWorkflowStore(deps: WorkflowStoreDeps): WorkflowStore;
+/**
+ * A `WorkflowStore` backed by a `pg` {@link Pool} — the batteries-included
+ * adapter that owns its own connections/transactions (via {@link poolExecutor})
+ * and requires the tables from `flowStoreDdl()`. Unchanged public surface: hosts
+ * that need Row Level Security or their own migrations should instead build an
+ * executor and call {@link createWorkflowStore}.
+ */
+declare function createPgWorkflowStore(deps: PgWorkflowStoreDeps): WorkflowStore;
+/** Convenience: apply the flow-store schema to a database. */
+declare function applySchema(pool: Pool, ddl: string): Promise<void>;
+//#endregion
+//#region src/store-pg/gate.d.ts
+/** DDL for the gate's two tables. Apply once at deploy time (or via `applySchema`). */
+declare function flowGateDdl(opts?: {
+  schema?: string;
+  rateBucketTable?: string;
+  leaseTable?: string;
+}): string;
+/** Default-schema gate DDL string. */
+declare const FLOW_GATE_DDL: string;
+interface PgStepGateConfig {
+  pool: Pool;
+  /** Partition this gate is bound to (matches the engine/store partition). */
+  partitionKey: string;
+  /** Schema the gate tables live in. Default 'public'. */
+  schema?: string;
+  /** Per-stepType concurrency caps (held leases). */
+  concurrency?: Record<string, ConcurrencyRule>;
+  /** Per-stepType token-bucket rate limits. */
+  rateLimit?: Record<string, RateRule>;
+  /** Lease TTL in seconds — crash-safety for held concurrency slots. Default 600. */
+  leaseTtlSeconds?: number;
+  /** Retry delay (seconds) returned when a concurrency cap is hit. Default 1. */
+  concurrencyRetrySeconds?: number;
+  /** Table name overrides. */
+  tables?: {
+    rateBucket?: string;
+    lease?: string;
+  };
+}
+interface StepGateConfig extends Omit<PgStepGateConfig, 'pool'> {
+  /** How the gate talks to Postgres (pool-backed, RLS-scoped, …). */
+  exec: SqlExecutor;
+}
+/**
+ * A Postgres-backed {@link StepGate} addressing all SQL through an injected
+ * {@link SqlExecutor}, so a host can run the concurrency/rate SQL under Row Level
+ * Security (inject an executor that sets the tenant GUC) instead of a plain pool.
+ * Global concurrency caps + rate limits shared across all workers; drop-in for
+ * the in-memory gate via `WorkflowEngineDeps.gate`.
+ */
+declare function createStepGate(config: StepGateConfig): StepGate;
+/**
+ * A Postgres-backed {@link StepGate} over a `pg` {@link Pool} — the
+ * batteries-included adapter (via {@link poolExecutor}). Hosts that need Row
+ * Level Security should build an executor and call {@link createStepGate}.
+ */
+declare function createPgStepGate(config: PgStepGateConfig): StepGate;
+//#endregion
+//#region src/store-pg/event-sink.d.ts
+/**
+ * DDL for the append-only run-history table. Apply once at deploy time (alongside
+ * `flowStoreDdl`), or call `applySchema(pool, flowEventDdl())`.
+ */
+declare function flowEventDdl(schema?: string): string;
+/** Default-schema event-table DDL string. */
+declare const FLOW_EVENT_DDL: string;
+interface PgEventSinkDeps {
+  pool: Pool;
+  /** Partition this sink is bound to (e.g. a tenant id). */
+  partitionKey: string;
+  /** Schema the flow tables live in. Default 'public'. */
+  schema?: string;
+}
+interface EventSinkDeps {
+  /** How the sink talks to Postgres (pool-backed, RLS-scoped, …). */
+  exec: SqlExecutor;
+  /** Partition this sink is bound to (e.g. a tenant id). */
+  partitionKey: string;
+  /** Schema the flow tables live in. Default 'public'. */
+  schema?: string;
+}
+/**
+ * A `FlowObserver` that appends every engine event to `flow_step_event`. `record` is
+ * fire-and-forget (it never throws and never blocks the engine); call `flush()` to await the
+ * in-flight inserts — useful in tests and before shutdown.
+ */
+interface PgEventSink extends FlowObserver {
+  flush(): Promise<void>;
+}
+/**
+ * A `FlowObserver` that appends engine events to `flow_step_event` through an
+ * injected {@link SqlExecutor}, so a host can run the write under Row Level
+ * Security (inject an executor that sets the tenant GUC) instead of a plain pool.
+ * `record` is fire-and-forget (never throws, never blocks the engine); `flush()`
+ * awaits the in-flight inserts.
+ */
+declare function createEventSink(deps: EventSinkDeps): PgEventSink;
+/**
+ * A `FlowObserver` backed by a `pg` {@link Pool} — the batteries-included sink
+ * (via {@link poolExecutor}). Hosts that need Row Level Security should build an
+ * executor and call {@link createEventSink} instead.
+ */
+declare function createPgEventSink(deps: PgEventSinkDeps): PgEventSink;
+/**
+ * Read a workflow's run history, ordered oldest-first. Accepts either a
+ * `pg` {@link Pool} (batteries-included) or a host's {@link SqlExecutor} (e.g.
+ * RLS-scoped) — both route through the same seam.
+ */
+declare function readFlowEvents(db: Pool | SqlExecutor, params: {
+  workflowId: WorkflowId;
+  partitionKey: string;
+  schema?: string;
+}): Promise<FlowEvent[]>;
+//#endregion
+export { EventSinkDeps, FLOW_EVENT_DDL, FLOW_GATE_DDL, FLOW_STORE_DDL, PgEventSink, PgEventSinkDeps, PgStepGateConfig, PgWorkflowStoreDeps, SqlExecutor, SqlResult, StepGateConfig, WorkflowStoreDeps, applySchema, createEventSink, createPgEventSink, createPgStepGate, createPgWorkflowStore, createSchemaDdl, createStepGate, createWorkflowStore, flowEventDdl, flowGateDdl, flowStoreDdl, poolExecutor, readFlowEvents, toExecutor };