octaflow 0.19.0 → 0.20.1

package/README.md

@@ -85,7 +85,7 @@ npx tsx scripts/demo.ts    # reproduce it
 ## Contents
 
 - [How it compares](#how-it-compares)
-- [When not to use Flow](#when-not-to-use-flow)
+- [When not to use it](#when-not-to-use-it)
 - [Performance](#performance)
 - [Features](#features)
 - [Installation](#installation)
@@ -115,7 +115,7 @@ you already run Postgres, it adds no infrastructure — the queue ([pg-boss](htt
 is Postgres too. You give up the dashboards, the polyglot SDKs, and the operational maturity
 that the others have earned.
 
-## When not to use Flow
+## When not to use it
 
 Reach for something else if:
 
@@ -130,6 +130,14 @@ Reach for something else if:
   ([`toPublicWorkflow`](https://octaflow.octabits.io/extending/http/)) and lifecycle events, not a
   dashboard. You build it.
 - **You need non-TypeScript workers.** The DAG and its schemas are TypeScript values.
+- **The caller is waiting.** Every step is a persisted transition, and in production a queue hop:
+  a step starts when a worker fetches it — on the next poll, unless `burstWhenBatchFull` is
+  keeping it busy — and adds engine time on top of your handler. Anything inside a
+  request/response — validate, transform, answer — is a function call. Put a workflow behind a
+  request only to *start* it, and let the page poll or subscribe for the outcome.
+- **One job with retries.** A single step that must run later and try again is a queue job;
+  pg-boss on its own does that with less. A DAG earns its keep when steps depend on each other,
+  run in parallel, or must be resumed and read back.
 - **You can't run Postgres**, or you need throughput past what a Postgres-backed queue gives you.
 - **You need a support contract**, or an API frozen by a 1.0 promise. This is pre-1.0 and 0.x
   minors can break.
@@ -203,7 +211,7 @@ next to what your steps actually do.
 | ↩️ | **Saga compensation** — run rollback handlers in reverse order on failure |
 | 🚑 | **Crash recovery** — a step whose worker died is re-queued while its attempt budget lasts |
 | 💓 | **Heartbeats** — a long step proves it is alive, so a dead one is caught in seconds, not minutes |
-| 🔭 | **Observability** — lifecycle events (run history) + per-step spans, both pluggable |
+| 🔭 | **Observability** — lifecycle events (run history), per-step spans, and `createMeterObserver` turning the events into OpenTelemetry-style metrics — all pluggable, all structural |
 | 🤖 | **AI add-on** — instrumented models, token/cost capture, quota, daily rollups |
 | 🧱 | **Pluggable everything** — `WorkflowStore`, `Dispatcher`, `StepGate`, `FlowObserver`, hooks |
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { $ as computeReadiness, A as StepConditionHandler, B as StepStatus, C as defineWaitStep, D as StartOptions, E as RetryPolicy, F as StepHandlerNotFoundError, G as WorkflowNotFoundError, H as WorkflowCreatedResult, I as StepHandlerRegistry, J as WorkflowStatus, K as WorkflowNotRetryableError, L as StepId, M as StepError, N as StepExecutionContext, O as StepCompensateHandler, P as StepHandler, Q as ReadinessPlan, R as StepRecord, S as defineSubWorkflowStep, T as InvalidWorkflowDefinitionError, U as WorkflowDefinition, V as WaitTimeoutPolicy, W as WorkflowId, X as JoinRule, Y as WorkflowWithSteps, Z as PlannedSkip, _ as WorkflowOutput, a as STEP_DISPLAY_STATUS, b as defineSleepStep, c as WORKFLOW_STATUS_SCHEMA, d as toPublicWorkflow, et as isTerminalStepStatus, f as StepDeps, g as TypedWorkflow, h as TypedStepContext, i as PublicWorkflowStep, it as ok, j as StepDefinition, k as StepCompensationContext, l as toDisplayStepStatus, m as TypedStep, n as PUBLIC_WORKFLOW_STEP_SCHEMA, nt as Result, o as STEP_DISPLAY_STATUS_SCHEMA, p as StepOutput, q as WorkflowRecord, r as PublicWorkflow, rt as err, s as StepDisplayStatus, t as PUBLIC_WORKFLOW_SCHEMA, tt as FlowErrorShape, u as toPublicStep, v as buildWorkflow, w as FlowError, x as defineStep, y as defineMapStep, z as StepRegistration } from "./index-BURAYZui.js";
 import { n as Logger, r as noopLogger, t as LogAttributes } from "./logger-BCus3AOa.js";
-import { A as WorkflowStore, C as CreateWorkflowStep, D as ListWorkflowsFilters, E as FinishWorkflowParams, O as ReopenWorkflowParams, S as CreateWorkflowParams, T as FailStepParams, _ as StepGateDecision, a as FlowTracer, b as AddChildStep, c as RecordingTracer, d as noopObserver, f as noopTracer, g as StepGate, h as RateRule, i as FlowSpan, k as TransactionalScope, l as createRecordingObserver, m as InMemoryStepGateConfig, n as FlowEventType, o as RecordedSpan, p as ConcurrencyRule, r as FlowObserver, s as RecordingObserver, t as FlowEvent, u as createRecordingTracer, v as StepGateRequest, w as CreatedWorkflow, x as CompleteStepParams, y as createInMemoryStepGate } from "./observability-B5KgSJfF.js";
+import { A as ListWorkflowsFilters, C as AddChildStep, D as CreatedWorkflow, E as CreateWorkflowStep, M as TransactionalScope, N as WorkflowStore, O as FailStepParams, S as createInMemoryStepGate, T as CreateWorkflowParams, _ as InMemoryStepGateConfig, a as FlowSpan, b as StepGateDecision, c as RecordingObserver, d as createMeterObserver, f as createRecordingObserver, g as ConcurrencyRule, h as noopTracer, i as FlowObserver, j as ReopenWorkflowParams, k as FinishWorkflowParams, l as RecordingTracer, m as noopObserver, n as FlowEventType, o as FlowTracer, p as createRecordingTracer, r as FlowMeter, s as RecordedSpan, t as FlowEvent, u as combineObservers, v as RateRule, w as CompleteStepParams, x as StepGateRequest, y as StepGate } from "./observability-Bu-SXLcS.js";
 import { i as EnqueueOptions, n as DispatchStepPayload, r as Dispatcher, t as DispatchKind } from "./dispatcher-g7Ct0J6w.js";
 import { a as WorkflowCompletedArgs, i as BuildStepContextArgs, n as BeforeStartArgs, o as WorkflowHooks, r as BeforeStartResult, t as AfterStepArgs } from "./hooks-BdxIcc92.js";
 //#region src/core/registry.d.ts
@@ -162,4 +162,4 @@ export declare function createInMemoryWorkflowStore(partitionKey?: string): Work
   };
 };
 //#endregion
-export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, DispatchKind, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, JoinRule, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PlannedSkip, PublicWorkflow, PublicWorkflowStep, RateRule, ReadinessPlan, RecordedSpan, RecordingObserver, RecordingTracer, ReopenWorkflowParams, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowNotRetryableError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStore, WorkflowWithSteps, buildWorkflow, computeReadiness, createInMemoryStepGate, createRecordingObserver, createRecordingTracer, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { AddChildStep, AfterStepArgs, BeforeStartArgs, BeforeStartResult, BuildStepContextArgs, CompleteStepParams, ConcurrencyRule, CreateWorkflowParams, CreateWorkflowStep, CreatedWorkflow, DispatchKind, DispatchStepPayload, Dispatcher, EnqueueOptions, FailStepParams, FinishWorkflowParams, FlowError, FlowErrorShape, FlowEvent, FlowEventType, FlowMeter, FlowObserver, FlowSpan, FlowTracer, InMemoryStepGateConfig, InvalidWorkflowDefinitionError, JoinRule, ListWorkflowsFilters, LogAttributes, Logger, PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, PlannedSkip, PublicWorkflow, PublicWorkflowStep, RateRule, ReadinessPlan, RecordedSpan, RecordingObserver, RecordingTracer, ReopenWorkflowParams, Result, RetryPolicy, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, StartOptions, StepCompensateHandler, StepCompensationContext, StepConditionHandler, StepDefinition, StepDeps, StepDisplayStatus, StepError, StepExecutionContext, StepGate, StepGateDecision, StepGateRequest, StepHandler, StepHandlerNotFoundError, StepHandlerRegistry, StepId, StepOutput, StepRecord, StepRegistration, StepStatus, TransactionalScope, TypedStep, TypedStepContext, TypedWorkflow, WORKFLOW_STATUS_SCHEMA, WaitTimeoutPolicy, WorkflowCompletedArgs, WorkflowCreatedResult, WorkflowDefinition, WorkflowHooks, WorkflowId, WorkflowNotFoundError, WorkflowNotRetryableError, WorkflowOutput, WorkflowRecord, WorkflowStatus, WorkflowStore, WorkflowWithSteps, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createMeterObserver, createRecordingObserver, createRecordingTracer, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, isTerminalStepStatus, noopLogger, noopObserver, noopTracer, ok, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

package/dist/index.js

@@ -153,6 +153,85 @@ function createRecordingObserver() {
 		}
 	};
 }
+/** Seconds-scale duration buckets, the OpenTelemetry semantic-convention set. */
+const DURATION_SECONDS_BOUNDARIES = [
+	.005,
+	.01,
+	.025,
+	.05,
+	.075,
+	.1,
+	.25,
+	.5,
+	.75,
+	1,
+	2.5,
+	5,
+	7.5,
+	10,
+	30,
+	60,
+	300
+];
+/**
+* A `FlowObserver` that turns the event stream into metrics:
+*
+* - `octaflow.workflow.events` (counter) — every workflow transition, by
+*   `workflow_type` and `event`.
+* - `octaflow.step.events` (counter) — every step transition, by
+*   `workflow_type`, `step_key`, `step_type` and `event`.
+* - `octaflow.step.duration` (histogram, seconds) — one point per
+*   `step.completed` / `step.failed`, by `workflow_type`, `step_key` and
+*   `outcome`.
+*
+* Attributes are the definitions' names, never ids — a workflow id in a
+* metric attribute is a cardinality leak. Pass it as `observer` to the engine;
+* combine with a history sink through `combineObservers`.
+*/
+function createMeterObserver(meter) {
+	const workflowEvents = meter.counter("octaflow.workflow.events", {
+		description: "Workflow lifecycle transitions.",
+		unit: "{event}"
+	});
+	const stepEvents = meter.counter("octaflow.step.events", {
+		description: "Step lifecycle transitions.",
+		unit: "{event}"
+	});
+	const stepDuration = meter.histogram("octaflow.step.duration", {
+		description: "Wall-clock duration of one step run.",
+		unit: "s",
+		boundaries: DURATION_SECONDS_BOUNDARIES
+	});
+	return { record(event) {
+		const workflowType = event.workflowType ?? "";
+		if (event.type.startsWith("workflow.")) {
+			workflowEvents.add(1, {
+				workflow_type: workflowType,
+				event: event.type
+			});
+			return;
+		}
+		stepEvents.add(1, {
+			workflow_type: workflowType,
+			step_key: event.stepKey ?? "",
+			step_type: event.stepType ?? "",
+			event: event.type
+		});
+		if ((event.type === "step.completed" || event.type === "step.failed") && event.durationMs !== void 0) stepDuration.record(event.durationMs / 1e3, {
+			workflow_type: workflowType,
+			step_key: event.stepKey ?? "",
+			outcome: event.type === "step.completed" ? "completed" : "failed"
+		});
+	} };
+}
+/** Fan one event out to several observers (history sink + metrics, say). Each is guarded. */
+function combineObservers(...observers) {
+	return { record(event) {
+		for (const observer of observers) try {
+			observer.record(event);
+		} catch {}
+	} };
+}
 const noopSpan = {
 	setAttribute() {},
 	recordError() {},
@@ -2154,4 +2233,4 @@ function createInMemoryWorkflowStore(partitionKey = "default") {
 	};
 }
 //#endregion
-export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, WORKFLOW_STATUS_SCHEMA, buildWorkflow, computeReadiness, createInMemoryStepGate, createInMemoryWorkflowStore, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, isRetryableError, isTerminalStepStatus, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };
+export { PUBLIC_WORKFLOW_SCHEMA, PUBLIC_WORKFLOW_STEP_SCHEMA, STEP_DISPLAY_STATUS, STEP_DISPLAY_STATUS_SCHEMA, WORKFLOW_STATUS_SCHEMA, buildWorkflow, combineObservers, computeReadiness, createInMemoryStepGate, createInMemoryWorkflowStore, createMeterObserver, createRecordingObserver, createRecordingTracer, createStepHandlerRegistry, createWorkflowEngine, defineMapStep, defineSleepStep, defineStep, defineSubWorkflowStep, defineWaitStep, err, explicitRetryability, isRetryableError, isTerminalStepStatus, markRetryable, nonRetryableError, noopLogger, noopObserver, noopTracer, ok, retryableError, toDisplayStepStatus, toPublicStep, toPublicWorkflow };

package/dist/{observability-B5KgSJfF.d.ts → observability-Bu-SXLcS.d.ts}

@@ -316,6 +316,45 @@ interface RecordingObserver extends FlowObserver {
   clear(): void;
 }
 declare function createRecordingObserver(): RecordingObserver;
+/**
+ * The slice of a metrics API the engine's meter observer needs. Structural:
+ * `@octabits-io/framework/telemetry`'s meter and an OpenTelemetry `Meter`
+ * both fit (the SDK's `createCounter`/`createHistogram` need a two-line
+ * adapter, the framework's meter none).
+ */
+interface FlowMeter {
+  counter(name: string, options?: {
+    description?: string;
+    unit?: string;
+  }): {
+    add(value: number, attributes?: Record<string, string | number | boolean>): void;
+  };
+  histogram(name: string, options?: {
+    description?: string;
+    unit?: string;
+    boundaries?: readonly number[];
+  }): {
+    record(value: number, attributes?: Record<string, string | number | boolean>): void;
+  };
+}
+/**
+ * A `FlowObserver` that turns the event stream into metrics:
+ *
+ * - `octaflow.workflow.events` (counter) — every workflow transition, by
+ *   `workflow_type` and `event`.
+ * - `octaflow.step.events` (counter) — every step transition, by
+ *   `workflow_type`, `step_key`, `step_type` and `event`.
+ * - `octaflow.step.duration` (histogram, seconds) — one point per
+ *   `step.completed` / `step.failed`, by `workflow_type`, `step_key` and
+ *   `outcome`.
+ *
+ * Attributes are the definitions' names, never ids — a workflow id in a
+ * metric attribute is a cardinality leak. Pass it as `observer` to the engine;
+ * combine with a history sink through `combineObservers`.
+ */
+declare function createMeterObserver(meter: FlowMeter): FlowObserver;
+/** Fan one event out to several observers (history sink + metrics, say). Each is guarded. */
+declare function combineObservers(...observers: FlowObserver[]): FlowObserver;
 /** A minimal span handle. Maps 1:1 onto an OpenTelemetry span in an adapter. */
 interface FlowSpan {
   setAttribute(key: string, value: string | number | boolean): void;
@@ -342,4 +381,4 @@ interface RecordingTracer extends FlowTracer {
 }
 declare function createRecordingTracer(): RecordingTracer;
 //#endregion
-export { WorkflowStore as A, CreateWorkflowStep as C, ListWorkflowsFilters as D, FinishWorkflowParams as E, ReopenWorkflowParams 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, TransactionalScope as k, 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 };
+export { ListWorkflowsFilters as A, AddChildStep as C, CreatedWorkflow as D, CreateWorkflowStep as E, TransactionalScope as M, WorkflowStore as N, FailStepParams as O, createInMemoryStepGate as S, CreateWorkflowParams as T, InMemoryStepGateConfig as _, FlowSpan as a, StepGateDecision as b, RecordingObserver as c, createMeterObserver as d, createRecordingObserver as f, ConcurrencyRule as g, noopTracer as h, FlowObserver as i, ReopenWorkflowParams as j, FinishWorkflowParams as k, RecordingTracer as l, noopObserver as m, FlowEventType as n, FlowTracer as o, createRecordingTracer as p, FlowMeter as r, RecordedSpan as s, FlowEvent as t, combineObservers as u, RateRule as v, CompleteStepParams as w, StepGateRequest as x, StepGate as y };

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

@@ -1,5 +1,5 @@
 import { W as WorkflowId } from "../index-BURAYZui.js";
-import { A as WorkflowStore, g as StepGate, h as RateRule, p as ConcurrencyRule, r as FlowObserver, t as FlowEvent } from "../observability-B5KgSJfF.js";
+import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-Bu-SXLcS.js";
 import { Pool } from "pg";
 //#region src/store-pg/ddl.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss, with an optional AI add-on (token/cost/quota). Layered single package.",
   "license": "MIT",
   "type": "module",