octaflow 0.19.0 → 0.20.0

package/README.md

@@ -203,7 +203,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.0",
   "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",