octaflow 0.24.1 → 0.26.0

package/README.md

@@ -230,6 +230,9 @@ what the layers you import need:
 # Postgres store / gate / event sink
 pnpm add pg
 
+# the same tables as Drizzle column sets, for a host that lets drizzle-kit own its migrations
+pnpm add drizzle-orm
+
 # pg-boss dispatcher, workers, cron scheduler
 pnpm add pg-boss
 
@@ -240,6 +243,67 @@ pnpm add ai @ai-sdk/provider
 > Pure in-memory usage (great for tests and single-process apps) needs **nothing** beyond
 > `zod` — the engine, `defineStep`/`buildWorkflow`, and the in-memory store are all in the core.
 
+### The Postgres tables
+
+`octaflow/postgres` owns five tables and ships their DDL: `flowStoreDdl()` (`flow_workflow`,
+`flow_workflow_step`), `flowEventDdl()` (`flow_step_event`) and `flowGateDdl()`
+(`flow_rate_bucket`, `flow_step_lease`). Each is idempotent `CREATE TABLE IF NOT EXISTS`, takes
+a `schema`, and is meant to be pasted into your own migration system; `applySchema(pool, ddl)`
+is the dev and test shortcut.
+
+#### The Drizzle columns
+
+The rule for every table-owning capability on the platform: `./postgres` ships the store over
+the structural executor plus its `xDdl()`, and `./drizzle` ships the same table as a spreadable
+column set, so a host on Drizzle declares it in its own schema and drizzle-kit owns the
+migration. Where the store's queries are one SQL statement by nature — every one of octaflow's
+is — `./drizzle` ships the columns only, and the store stays the SQL one. So
+`octaflow/drizzle` exports `flowWorkflowColumns`, `flowWorkflowStepColumns`,
+`flowStepEventColumns`, `flowRateBucketColumns` and `flowStepLeaseColumns` (`drizzle-orm` an
+optional peer) and nothing that runs a query. The foreign keys, the composite keys, the unique
+constraint and the indexes are yours to declare on the `pgTable`; each column set's doc lists
+the ones its DDL creates, and two of them the store relies on:
+
+```ts
+import { sql } from 'drizzle-orm';
+import { foreignKey, index, pgTable, primaryKey, unique, uniqueIndex } from 'drizzle-orm/pg-core';
+import { flowWorkflowColumns, flowWorkflowStepColumns, flowStepLeaseColumns } from 'octaflow/drizzle';
+
+export const flowWorkflow = pgTable('flow_workflow', flowWorkflowColumns, (t) => [
+  index('flow_workflow_partition_status_idx').on(t.partitionKey, t.status),
+  index('flow_workflow_partition_type_idx').on(t.partitionKey, t.type),
+  index('flow_workflow_partition_entity_idx').on(t.partitionKey, t.entityRef),
+  index('flow_workflow_parent_idx').on(t.parentWorkflowId),
+  // The deadline sweep reads only live runs that have one.
+  index('flow_workflow_deadline_idx').on(t.deadlineAt).where(sql`deadline_at IS NOT NULL`),
+  // `start` with an idempotency key upserts against this index: without it a repeated start is a second run.
+  uniqueIndex('flow_workflow_idempotency_idx').on(t.partitionKey, t.idempotencyKey).where(sql`idempotency_key IS NOT NULL`),
+]);
+
+export const flowWorkflowStep = pgTable('flow_workflow_step', flowWorkflowStepColumns, (t) => [
+  foreignKey({ columns: [t.workflowId], foreignColumns: [flowWorkflow.id] }).onDelete('cascade'),
+  foreignKey({ columns: [t.parentStepId], foreignColumns: [t.id] }).onDelete('cascade'),
+  unique('flow_workflow_step_workflow_id_key_unique').on(t.workflowId, t.key),
+  index('flow_workflow_step_workflow_idx').on(t.workflowId),
+  index('flow_workflow_step_status_idx').on(t.workflowId, t.status),
+  index('flow_workflow_step_parent_idx').on(t.parentStepId),
+]);
+
+export const flowStepLease = pgTable('flow_step_lease', flowStepLeaseColumns, (t) => [
+  primaryKey({ columns: [t.partitionKey, t.stepType, t.stepId] }),
+  index('flow_step_lease_active_idx').on(t.partitionKey, t.stepType, t.expiresAt),
+]);
+```
+
+The names are yours: the store's `ON CONFLICT` clauses target column lists, never a
+constraint by name, so what must match is each index's columns and its partial `WHERE`,
+not what you call it.
+
+The store stays plain SQL, bound to the `schema` you hand `createPgWorkflowStore`,
+`createPgStepGate` and `createPgEventSink` — and, for the gate, to the `tables` names — so
+declare the tables under the same schema and names. A test in the package holds every column
+set and its DDL equal, column for column: a column added to one side alone fails the build.
+
 ---
 
 ---

package/dist/ai/providers/index.d.ts

@@ -66,7 +66,7 @@ export interface LazyEmbeddingModelMeta {
  * next call rather than cached.
  */
 export declare function createLazyEmbeddingModel(meta: LazyEmbeddingModelMeta, load: () => Promise<EmbeddingModelV4>): EmbeddingModelV4;
-export type AiProviderConfigErrorKey = 'ai_residency_undeclared' | 'ai_residency_invalid' | 'ai_base_url_invalid' | 'ai_model_required' | 'ai_embedding_dimensions_invalid';
+export type AiProviderConfigErrorKey = 'ai_residency_undeclared' | 'ai_residency_invalid' | 'ai_base_url_invalid' | 'ai_model_required' | 'ai_model_undeclared' | 'ai_embedding_dimensions_invalid';
 /**
  * A provider configuration that cannot work. Thrown before any SDK is loaded
  * or any request is made: it is a deployment mistake, found at wiring time.
@@ -143,4 +143,66 @@ export interface OpenAiCompatibleEmbeddingProvider {
 export declare function createOpenAiCompatibleModelProvider(config: OpenAiCompatibleModelProviderConfig): Promise<OpenAiCompatibleModelProvider>;
 /** An embedding model on an OpenAI-compatible endpoint, with its declared width. */
 export declare function createOpenAiCompatibleEmbeddingProvider(config: OpenAiCompatibleEmbeddingProviderConfig): Promise<OpenAiCompatibleEmbeddingProvider>;
+export interface OpenAiCompatibleGatewayModel {
+  /** Where the gateway sends this alias. Validated like an endpoint's residency. */
+  residency: AiEndpointResidency;
+}
+/**
+ * `residency` is where the gateway itself runs, usually `{ region: 'self-hosted' }`.
+ * It decides whether plain http is acceptable for the hop to the gateway; where a
+ * call ends up is the alias's residency in `models`.
+ */
+export interface OpenAiCompatibleGatewayConfig extends OpenAiCompatibleEndpointConfig {
+  /** Every alias this deployment may call, keyed by the model name the gateway knows. */
+  models: Record<string, OpenAiCompatibleGatewayModel>;
+  /** As for {@link OpenAiCompatibleModelProviderConfig.structuredOutputs}. */
+  structuredOutputs?: boolean;
+  /** As for {@link OpenAiCompatibleModelProviderConfig.includeUsage}. */
+  includeUsage?: boolean;
+}
+export interface GatewayCallOptions {
+  /**
+   * Sent as the request body's `metadata`, which LiteLLM keeps in its spend log,
+   * so a call there can be matched to the host's own record: a workflow id, a
+   * scope key. It leaves the house as written and is never redacted: put ids
+   * here, never content. Added innermost, so a disclosure gate wrapped around the
+   * model neither digests nor redacts it.
+   */
+  metadata?: Record<string, string>;
+}
+export interface OpenAiCompatibleGatewayProvider {
+  providerId: OpenAiCompatibleProviderId;
+  /** Where the gateway itself runs. */
+  residency: AiEndpointResidency;
+  /** Every declared alias with its validated residency: what a settings page or a subprocessor annex lists. */
+  models: Readonly<Record<string, AiEndpointResidency>>;
+  /** The residency of one alias. Throws `ai_model_undeclared` for an alias the declaration does not name. */
+  residencyOf(alias: string): AiEndpointResidency;
+  /** A Chat Completions model for a declared alias, wrapped for refusal detection. */
+  languageModel(alias: string, options?: GatewayCallOptions): LanguageModelV4;
+}
+/**
+ * A model gateway — LiteLLM, or any router with the OpenAI-compatible API — as
+ * refusal-aware models, one per declared alias, each with the residency of
+ * where the gateway sends it.
+ *
+ * ```ts
+ * const gateway = await createOpenAiCompatibleGatewayProvider({
+ *   baseUrl: 'http://litellm.ai.svc:4000/v1',
+ *   apiKey: process.env.LITELLM_KEY,
+ *   residency: { region: 'self-hosted' },
+ *   models: {
+ *     'approval-confidential': { residency: { region: 'self-hosted' } },
+ *     'approval-public': { residency: { region: 'eu', legalName: 'Example Inference GmbH', country: 'DE' } },
+ *   },
+ * });
+ * const model = gateway.languageModel('approval-confidential', { metadata: { workflowId } });
+ * ```
+ *
+ * The declaration is what the gateway is configured to do, stated by the
+ * deployment: this provider cannot see the gateway's routing, and a fallback
+ * the gateway adds on its own breaks the declaration silently. Keep the two
+ * in the same review.
+ */
+export declare function createOpenAiCompatibleGatewayProvider(config: OpenAiCompatibleGatewayConfig): Promise<OpenAiCompatibleGatewayProvider>;
 //#endregion

package/dist/ai/providers/index.js

@@ -1,5 +1,6 @@
 import { r as createRefusalAwareModel } from "../../refusal-BsL2HPDb.js";
 import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, t as AI_PROVIDERS } from "../../provider-registry-BRwjC6_3.js";
+import { wrapLanguageModel } from "ai";
 //#region src/ai/providers/index.ts
 const LLM_LOADERS = {
 	anthropic: async (apiKey, baseURL) => {
@@ -186,5 +187,90 @@ async function createOpenAiCompatibleEmbeddingProvider(config) {
 		embeddingModel: () => provider.embeddingModel(modelId)
 	};
 }
+/** Puts `metadata` into the request body under the provider's own options key, merged over any the call carries. */
+function withGatewayMetadata(model, optionsKey, metadata) {
+	const fixed = { ...metadata };
+	return wrapLanguageModel({
+		model,
+		middleware: {
+			specificationVersion: "v4",
+			transformParams: async ({ params }) => {
+				const own = params.providerOptions?.[optionsKey] ?? {};
+				const existing = own.metadata !== null && typeof own.metadata === "object" && !Array.isArray(own.metadata) ? own.metadata : {};
+				const merged = {
+					...own,
+					metadata: {
+						...existing,
+						...fixed
+					}
+				};
+				return {
+					...params,
+					providerOptions: {
+						...params.providerOptions,
+						[optionsKey]: merged
+					}
+				};
+			}
+		}
+	});
+}
+/**
+* A model gateway — LiteLLM, or any router with the OpenAI-compatible API — as
+* refusal-aware models, one per declared alias, each with the residency of
+* where the gateway sends it.
+*
+* ```ts
+* const gateway = await createOpenAiCompatibleGatewayProvider({
+*   baseUrl: 'http://litellm.ai.svc:4000/v1',
+*   apiKey: process.env.LITELLM_KEY,
+*   residency: { region: 'self-hosted' },
+*   models: {
+*     'approval-confidential': { residency: { region: 'self-hosted' } },
+*     'approval-public': { residency: { region: 'eu', legalName: 'Example Inference GmbH', country: 'DE' } },
+*   },
+* });
+* const model = gateway.languageModel('approval-confidential', { metadata: { workflowId } });
+* ```
+*
+* The declaration is what the gateway is configured to do, stated by the
+* deployment: this provider cannot see the gateway's routing, and a fallback
+* the gateway adds on its own breaks the declaration silently. Keep the two
+* in the same review.
+*/
+async function createOpenAiCompatibleGatewayProvider(config) {
+	const residency = checkEndpoint(config);
+	const declared = config.models;
+	if (declared === null || typeof declared !== "object" || Object.keys(declared).length === 0) throw new AiProviderConfigError("ai_model_required", "a gateway needs at least one declared model alias in models");
+	const models = {};
+	for (const [alias, model] of Object.entries(declared)) {
+		requireModel(alias, "a model alias");
+		const resolved = resolveEndpointResidency(model?.residency);
+		if (!resolved.ok) throw new AiProviderConfigError(resolved.error.key, `model ${JSON.stringify(alias)}: ${resolved.error.message}`);
+		models[alias] = resolved.value;
+	}
+	Object.freeze(models);
+	const provider = await loadOpenAiCompatible(config, {
+		structuredOutputs: config.structuredOutputs,
+		includeUsage: config.includeUsage
+	});
+	const optionsKey = config.name ?? "openai-compatible";
+	const residencyOf = (alias) => {
+		const found = Object.hasOwn(models, alias) ? models[alias] : void 0;
+		if (found === void 0) throw new AiProviderConfigError("ai_model_undeclared", `model ${JSON.stringify(alias)} is not declared for this gateway; declared: ${Object.keys(models).join(", ")}`);
+		return found;
+	};
+	return {
+		providerId: OPENAI_COMPATIBLE_PROVIDER_ID,
+		residency,
+		models,
+		residencyOf,
+		languageModel: (alias, options) => {
+			residencyOf(alias);
+			const chat = provider.chatModel(alias);
+			return createRefusalAwareModel(options?.metadata ? withGatewayMetadata(chat, optionsKey, options.metadata) : chat);
+		}
+	};
+}
 //#endregion
-export { AiProviderConfigError, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleModelProvider };
+export { AiProviderConfigError, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleGatewayProvider, createOpenAiCompatibleModelProvider };

package/dist/drizzle/index.d.ts

@@ -0,0 +1,173 @@
+//#region src/drizzle/index.d.ts
+/**
+ * `flow_workflow` — one row per run. `partition_key` is the engine's scoping
+ * column: the store is bound to one partition and every query filters by it.
+ *
+ * The DDL adds, and the host declares:
+ *
+ * ```ts
+ * import { index, pgTable, uniqueIndex } from 'drizzle-orm/pg-core';
+ * import { sql } from 'drizzle-orm';
+ * import { flowWorkflowColumns } from 'octaflow/drizzle';
+ *
+ * export const flowWorkflow = pgTable('flow_workflow', flowWorkflowColumns, (t) => [
+ *   index('flow_workflow_partition_status_idx').on(t.partitionKey, t.status),
+ *   index('flow_workflow_parent_idx').on(t.parentWorkflowId),
+ *   index('flow_workflow_partition_type_idx').on(t.partitionKey, t.type),
+ *   index('flow_workflow_partition_entity_idx').on(t.partitionKey, t.entityRef),
+ *   // Load-bearing: the deadline sweep reads only live runs that have one.
+ *   index('flow_workflow_deadline_idx').on(t.deadlineAt).where(sql`deadline_at IS NOT NULL`),
+ *   // Load-bearing: `start` with an idempotency key relies on this unique index
+ *   // to make a repeated start return the existing run instead of a second one.
+ *   uniqueIndex('flow_workflow_idempotency_idx').on(t.partitionKey, t.idempotencyKey).where(sql`idempotency_key IS NOT NULL`),
+ * ]);
+ * ```
+ *
+ * `parent_workflow_id` and `parent_step_id` carry no foreign key in the DDL
+ * (a parent may outlive or predate its child in a migration); add one if you
+ * want the constraint.
+ */
+export declare const flowWorkflowColumns: {
+  id: import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgBigSerial53BuilderInitial<"id">>>;
+  partitionKey: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"partition_key", [string, ...string[]]>>;
+  /** The workflow definition's name. */
+  type: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"type", [string, ...string[]]>>;
+  status: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"status", [string, ...string[]]>>;
+  input: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"input">>>;
+  output: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"output">;
+  error: import("drizzle-orm/pg-core").PgTextBuilderInitial<"error", [string, ...string[]]>;
+  /** The host's handle for what the run is about (`'record:88'`), for lookups by entity. */
+  entityRef: import("drizzle-orm/pg-core").PgTextBuilderInitial<"entity_ref", [string, ...string[]]>;
+  totalSteps: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"total_steps">>;
+  completedSteps: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"completed_steps">>>;
+  failedSteps: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"failed_steps">>>;
+  metadata: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"metadata">;
+  /** Set on a `start` that asked for one; unique per partition where present. */
+  idempotencyKey: import("drizzle-orm/pg-core").PgTextBuilderInitial<"idempotency_key", [string, ...string[]]>;
+  /** The run's deadline, when the definition set one; the sweep reads it. */
+  deadlineAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
+  /** For a sub-workflow: the run that started it, and the step in that run. */
+  parentWorkflowId: import("drizzle-orm/pg-core").PgBigInt53BuilderInitial<"parent_workflow_id">;
+  parentStepId: import("drizzle-orm/pg-core").PgBigInt53BuilderInitial<"parent_step_id">;
+  createdAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>>;
+  startedAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
+  completedAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
+};
+/**
+ * `flow_workflow_step` — one row per step of a run, including the children a
+ * fan-out creates at runtime.
+ *
+ * The DDL adds, and the host declares:
+ *
+ * ```ts
+ * import { foreignKey, index, pgTable, unique, type AnyPgColumn } from 'drizzle-orm/pg-core';
+ * import { flowWorkflowStepColumns } from 'octaflow/drizzle';
+ *
+ * export const flowWorkflowStep = pgTable('flow_workflow_step', flowWorkflowStepColumns, (t) => [
+ *   foreignKey({ columns: [t.workflowId], foreignColumns: [flowWorkflow.id] }).onDelete('cascade'),
+ *   foreignKey({ columns: [t.parentStepId], foreignColumns: [t.id] }).onDelete('cascade'),
+ *   // `(workflow_id, key)` is the step's identity within a run; the constraint
+ *   // is what refuses a second step under the same key.
+ *   unique('flow_workflow_step_workflow_id_key_unique').on(t.workflowId, t.key),
+ *   index('flow_workflow_step_workflow_idx').on(t.workflowId),
+ *   index('flow_workflow_step_status_idx').on(t.workflowId, t.status),
+ *   index('flow_workflow_step_parent_idx').on(t.parentStepId),
+ * ]);
+ * ```
+ */
+export declare const flowWorkflowStepColumns: {
+  id: import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgBigSerial53BuilderInitial<"id">>>;
+  workflowId: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgBigInt53BuilderInitial<"workflow_id">>;
+  partitionKey: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"partition_key", [string, ...string[]]>>;
+  /** The step's key within its workflow — unique per run. */
+  key: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"key", [string, ...string[]]>>;
+  /** The step handler's name. */
+  type: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"type", [string, ...string[]]>>;
+  status: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"status", [string, ...string[]]>>;
+  /** The keys of the steps this one waits for. */
+  dependencies: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"dependencies">>>;
+  input: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"input">;
+  output: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"output">;
+  error: import("drizzle-orm/pg-core").PgTextBuilderInitial<"error", [string, ...string[]]>;
+  metadata: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"metadata">;
+  attempts: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"attempts">>>;
+  /** For a fan-out child: the step that spawned it. */
+  parentStepId: import("drizzle-orm/pg-core").PgBigInt53BuilderInitial<"parent_step_id">;
+  /** The last heartbeat a long step sent; the sweep uses it to tell stalled from slow. */
+  heartbeatAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
+  startedAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
+  completedAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
+};
+/**
+ * `flow_step_event` — the append-only run history `createPgEventSink` writes,
+ * one row per engine event.
+ *
+ * The DDL adds, and the host declares:
+ *
+ * ```ts
+ * export const flowStepEvent = pgTable('flow_step_event', flowStepEventColumns, (t) => [
+ *   index('flow_step_event_workflow_idx').on(t.partitionKey, t.workflowId, t.id),
+ * ]);
+ * ```
+ *
+ * `workflow_id` carries no foreign key on purpose: the history outlives the run.
+ */
+export declare const flowStepEventColumns: {
+  id: import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgBigSerial53BuilderInitial<"id">>>;
+  partitionKey: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"partition_key", [string, ...string[]]>>;
+  workflowId: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgBigInt53BuilderInitial<"workflow_id">>;
+  workflowType: import("drizzle-orm/pg-core").PgTextBuilderInitial<"workflow_type", [string, ...string[]]>;
+  /** Null for a workflow-level event. */
+  stepId: import("drizzle-orm/pg-core").PgBigInt53BuilderInitial<"step_id">;
+  stepKey: import("drizzle-orm/pg-core").PgTextBuilderInitial<"step_key", [string, ...string[]]>;
+  stepType: import("drizzle-orm/pg-core").PgTextBuilderInitial<"step_type", [string, ...string[]]>;
+  eventType: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"event_type", [string, ...string[]]>>;
+  attempt: import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"attempt">;
+  durationMs: import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"duration_ms">;
+  error: import("drizzle-orm/pg-core").PgTextBuilderInitial<"error", [string, ...string[]]>;
+  at: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>;
+};
+/**
+ * `flow_rate_bucket` — one token bucket per `(partition_key, step_type)` for
+ * `createPgStepGate`'s rate limits. The table name is the DDL's default and
+ * the gate's `tables.rateBucket` option; the two must agree.
+ *
+ * The DDL adds a composite primary key, and the host declares it:
+ *
+ * ```ts
+ * export const flowRateBucket = pgTable('flow_rate_bucket', flowRateBucketColumns, (t) => [
+ *   primaryKey({ columns: [t.partitionKey, t.stepType] }),
+ * ]);
+ * ```
+ */
+export declare const flowRateBucketColumns: {
+  partitionKey: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"partition_key", [string, ...string[]]>>;
+  stepType: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"step_type", [string, ...string[]]>>;
+  /** The bucket's fill, refilled from `updated_at` on every read. */
+  tokens: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgDoublePrecisionBuilderInitial<"tokens">>;
+  updatedAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>>;
+};
+/**
+ * `flow_step_lease` — one row per running step under a concurrency cap, for
+ * `createPgStepGate`'s `maxConcurrent`. The table name is the DDL's default
+ * and the gate's `tables.lease` option; the two must agree.
+ *
+ * The DDL adds a composite primary key and one index, and the host declares
+ * them — the index name is derived from the table name in the DDL:
+ *
+ * ```ts
+ * export const flowStepLease = pgTable('flow_step_lease', flowStepLeaseColumns, (t) => [
+ *   primaryKey({ columns: [t.partitionKey, t.stepType, t.stepId] }),
+ *   index('flow_step_lease_active_idx').on(t.partitionKey, t.stepType, t.expiresAt),
+ * ]);
+ * ```
+ */
+export declare const flowStepLeaseColumns: {
+  partitionKey: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"partition_key", [string, ...string[]]>>;
+  stepType: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<"step_type", [string, ...string[]]>>;
+  stepId: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgBigInt53BuilderInitial<"step_id">>;
+  acquiredAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>>;
+  /** A lease past this instant is reaped on the next acquire. */
+  expiresAt: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>>;
+};
+//#endregion

package/dist/drizzle/index.js

@@ -0,0 +1,199 @@
+import { bigint, bigserial, doublePrecision, integer, jsonb, text, timestamp } from "drizzle-orm/pg-core";
+//#region src/drizzle/index.ts
+/**
+* `octaflow/drizzle` — the engine's tables as Drizzle column sets.
+*
+* One spreadable column set per table the Postgres adapters create: the
+* workflow store's two (`flowStoreDdl`), the event sink's one (`flowEventDdl`)
+* and the gate's two (`flowGateDdl`). A host on Drizzle declares the tables in
+* its own schema from these columns and lets drizzle-kit own the migrations;
+* the stores themselves stay plain SQL over the `schema` (and, for the gate,
+* the table names) the host hands them. Nothing here runs a query: no store
+* is rewritten on the ORM, because every one of the engine's writes is one
+* SQL statement by nature.
+*
+* What the DDL declares beyond the columns is the host's to mirror in its
+* `pgTable(...)` call — the foreign keys, the composite keys, the unique
+* constraint and the indexes. Each set's doc lists them; two of the indexes
+* are load-bearing for the store, not an optimisation, and are marked so.
+* A test holds these sets and the DDL equal column for column.
+*
+* `drizzle-orm` is an optional peer, loaded by this subpath alone.
+*/
+const timestamptz = (name) => timestamp(name, {
+	withTimezone: true,
+	mode: "date"
+});
+/**
+* `flow_workflow` — one row per run. `partition_key` is the engine's scoping
+* column: the store is bound to one partition and every query filters by it.
+*
+* The DDL adds, and the host declares:
+*
+* ```ts
+* import { index, pgTable, uniqueIndex } from 'drizzle-orm/pg-core';
+* import { sql } from 'drizzle-orm';
+* import { flowWorkflowColumns } from 'octaflow/drizzle';
+*
+* export const flowWorkflow = pgTable('flow_workflow', flowWorkflowColumns, (t) => [
+*   index('flow_workflow_partition_status_idx').on(t.partitionKey, t.status),
+*   index('flow_workflow_parent_idx').on(t.parentWorkflowId),
+*   index('flow_workflow_partition_type_idx').on(t.partitionKey, t.type),
+*   index('flow_workflow_partition_entity_idx').on(t.partitionKey, t.entityRef),
+*   // Load-bearing: the deadline sweep reads only live runs that have one.
+*   index('flow_workflow_deadline_idx').on(t.deadlineAt).where(sql`deadline_at IS NOT NULL`),
+*   // Load-bearing: `start` with an idempotency key relies on this unique index
+*   // to make a repeated start return the existing run instead of a second one.
+*   uniqueIndex('flow_workflow_idempotency_idx').on(t.partitionKey, t.idempotencyKey).where(sql`idempotency_key IS NOT NULL`),
+* ]);
+* ```
+*
+* `parent_workflow_id` and `parent_step_id` carry no foreign key in the DDL
+* (a parent may outlive or predate its child in a migration); add one if you
+* want the constraint.
+*/
+const flowWorkflowColumns = {
+	id: bigserial("id", { mode: "number" }).primaryKey(),
+	partitionKey: text("partition_key").notNull(),
+	/** The workflow definition's name. */
+	type: text("type").notNull(),
+	status: text("status").notNull(),
+	input: jsonb("input").notNull().default({}),
+	output: jsonb("output"),
+	error: text("error"),
+	/** The host's handle for what the run is about (`'record:88'`), for lookups by entity. */
+	entityRef: text("entity_ref"),
+	totalSteps: integer("total_steps").notNull(),
+	completedSteps: integer("completed_steps").notNull().default(0),
+	failedSteps: integer("failed_steps").notNull().default(0),
+	metadata: jsonb("metadata"),
+	/** Set on a `start` that asked for one; unique per partition where present. */
+	idempotencyKey: text("idempotency_key"),
+	/** The run's deadline, when the definition set one; the sweep reads it. */
+	deadlineAt: timestamptz("deadline_at"),
+	/** For a sub-workflow: the run that started it, and the step in that run. */
+	parentWorkflowId: bigint("parent_workflow_id", { mode: "number" }),
+	parentStepId: bigint("parent_step_id", { mode: "number" }),
+	createdAt: timestamptz("created_at").notNull().defaultNow(),
+	startedAt: timestamptz("started_at"),
+	completedAt: timestamptz("completed_at")
+};
+/**
+* `flow_workflow_step` — one row per step of a run, including the children a
+* fan-out creates at runtime.
+*
+* The DDL adds, and the host declares:
+*
+* ```ts
+* import { foreignKey, index, pgTable, unique, type AnyPgColumn } from 'drizzle-orm/pg-core';
+* import { flowWorkflowStepColumns } from 'octaflow/drizzle';
+*
+* export const flowWorkflowStep = pgTable('flow_workflow_step', flowWorkflowStepColumns, (t) => [
+*   foreignKey({ columns: [t.workflowId], foreignColumns: [flowWorkflow.id] }).onDelete('cascade'),
+*   foreignKey({ columns: [t.parentStepId], foreignColumns: [t.id] }).onDelete('cascade'),
+*   // `(workflow_id, key)` is the step's identity within a run; the constraint
+*   // is what refuses a second step under the same key.
+*   unique('flow_workflow_step_workflow_id_key_unique').on(t.workflowId, t.key),
+*   index('flow_workflow_step_workflow_idx').on(t.workflowId),
+*   index('flow_workflow_step_status_idx').on(t.workflowId, t.status),
+*   index('flow_workflow_step_parent_idx').on(t.parentStepId),
+* ]);
+* ```
+*/
+const flowWorkflowStepColumns = {
+	id: bigserial("id", { mode: "number" }).primaryKey(),
+	workflowId: bigint("workflow_id", { mode: "number" }).notNull(),
+	partitionKey: text("partition_key").notNull(),
+	/** The step's key within its workflow — unique per run. */
+	key: text("key").notNull(),
+	/** The step handler's name. */
+	type: text("type").notNull(),
+	status: text("status").notNull(),
+	/** The keys of the steps this one waits for. */
+	dependencies: jsonb("dependencies").notNull().default([]),
+	input: jsonb("input"),
+	output: jsonb("output"),
+	error: text("error"),
+	metadata: jsonb("metadata"),
+	attempts: integer("attempts").notNull().default(0),
+	/** For a fan-out child: the step that spawned it. */
+	parentStepId: bigint("parent_step_id", { mode: "number" }),
+	/** The last heartbeat a long step sent; the sweep uses it to tell stalled from slow. */
+	heartbeatAt: timestamptz("heartbeat_at"),
+	startedAt: timestamptz("started_at"),
+	completedAt: timestamptz("completed_at")
+};
+/**
+* `flow_step_event` — the append-only run history `createPgEventSink` writes,
+* one row per engine event.
+*
+* The DDL adds, and the host declares:
+*
+* ```ts
+* export const flowStepEvent = pgTable('flow_step_event', flowStepEventColumns, (t) => [
+*   index('flow_step_event_workflow_idx').on(t.partitionKey, t.workflowId, t.id),
+* ]);
+* ```
+*
+* `workflow_id` carries no foreign key on purpose: the history outlives the run.
+*/
+const flowStepEventColumns = {
+	id: bigserial("id", { mode: "number" }).primaryKey(),
+	partitionKey: text("partition_key").notNull(),
+	workflowId: bigint("workflow_id", { mode: "number" }).notNull(),
+	workflowType: text("workflow_type"),
+	/** Null for a workflow-level event. */
+	stepId: bigint("step_id", { mode: "number" }),
+	stepKey: text("step_key"),
+	stepType: text("step_type"),
+	eventType: text("event_type").notNull(),
+	attempt: integer("attempt"),
+	durationMs: integer("duration_ms"),
+	error: text("error"),
+	at: timestamptz("at").notNull()
+};
+/**
+* `flow_rate_bucket` — one token bucket per `(partition_key, step_type)` for
+* `createPgStepGate`'s rate limits. The table name is the DDL's default and
+* the gate's `tables.rateBucket` option; the two must agree.
+*
+* The DDL adds a composite primary key, and the host declares it:
+*
+* ```ts
+* export const flowRateBucket = pgTable('flow_rate_bucket', flowRateBucketColumns, (t) => [
+*   primaryKey({ columns: [t.partitionKey, t.stepType] }),
+* ]);
+* ```
+*/
+const flowRateBucketColumns = {
+	partitionKey: text("partition_key").notNull(),
+	stepType: text("step_type").notNull(),
+	/** The bucket's fill, refilled from `updated_at` on every read. */
+	tokens: doublePrecision("tokens").notNull(),
+	updatedAt: timestamptz("updated_at").notNull().defaultNow()
+};
+/**
+* `flow_step_lease` — one row per running step under a concurrency cap, for
+* `createPgStepGate`'s `maxConcurrent`. The table name is the DDL's default
+* and the gate's `tables.lease` option; the two must agree.
+*
+* The DDL adds a composite primary key and one index, and the host declares
+* them — the index name is derived from the table name in the DDL:
+*
+* ```ts
+* export const flowStepLease = pgTable('flow_step_lease', flowStepLeaseColumns, (t) => [
+*   primaryKey({ columns: [t.partitionKey, t.stepType, t.stepId] }),
+*   index('flow_step_lease_active_idx').on(t.partitionKey, t.stepType, t.expiresAt),
+* ]);
+* ```
+*/
+const flowStepLeaseColumns = {
+	partitionKey: text("partition_key").notNull(),
+	stepType: text("step_type").notNull(),
+	stepId: bigint("step_id", { mode: "number" }).notNull(),
+	acquiredAt: timestamptz("acquired_at").notNull().defaultNow(),
+	/** A lease past this instant is reaped on the next acquire. */
+	expiresAt: timestamptz("expires_at").notNull()
+};
+//#endregion
+export { flowRateBucketColumns, flowStepEventColumns, flowStepLeaseColumns, flowWorkflowColumns, flowWorkflowStepColumns };

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 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-CR9dEdLW.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-3wVqt3tZ.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

package/dist/{observability-CR9dEdLW.d.ts → observability-3wVqt3tZ.d.ts}

@@ -320,7 +320,7 @@ declare function createRecordingObserver(): RecordingObserver;
  * The slice of a metrics API the engine's meter observer needs. Structural:
  * `@octabits-io/telemetry`'s meter and an OpenTelemetry `Meter`
  * both fit (the SDK's `createCounter`/`createHistogram` need a two-line
- * adapter, the framework's meter none).
+ * adapter).
  */
 interface FlowMeter {
   counter(name: string, options?: {

package/dist/postgres/index.d.ts

@@ -1,5 +1,5 @@
 import { W as WorkflowId } from "../index-BURAYZui.js";
-import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-CR9dEdLW.js";
+import { N as WorkflowStore, g as ConcurrencyRule, i as FlowObserver, t as FlowEvent, v as RateRule, y as StepGate } from "../observability-3wVqt3tZ.js";
 import { Pool } from "pg";
 //#region src/postgres/ddl.d.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.24.1",
+  "version": "0.26.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",
@@ -20,6 +20,11 @@
       "import": "./dist/postgres/index.js",
       "default": "./dist/postgres/index.js"
     },
+    "./drizzle": {
+      "types": "./dist/drizzle/index.d.ts",
+      "import": "./dist/drizzle/index.js",
+      "default": "./dist/drizzle/index.js"
+    },
     "./pg-boss": {
       "types": "./dist/pg-boss/index.d.ts",
       "import": "./dist/pg-boss/index.js",
@@ -65,7 +70,8 @@
     "llm",
     "pg-boss",
     "postgres",
-    "zod"
+    "zod",
+    "drizzle"
   ],
   "peerDependencies": {
     "@ai-sdk/anthropic": "^4.0.0",
@@ -74,6 +80,7 @@
     "@ai-sdk/openai-compatible": "^3.0.0",
     "@ai-sdk/provider": "^4.0.0",
     "ai": "^7.0.0",
+    "drizzle-orm": ">=0.36.0 <1",
     "pg": "^8.0.0",
     "pg-boss": "^12.21.0",
     "typescript": "^5 || ^6 || ^7",
@@ -98,6 +105,9 @@
     "ai": {
       "optional": true
     },
+    "drizzle-orm": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },
@@ -106,22 +116,23 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^4.0.52",
-    "@ai-sdk/mistral": "^4.0.42",
-    "@ai-sdk/openai": "^4.0.65",
-    "@ai-sdk/openai-compatible": "^3.0.48",
-    "@ai-sdk/provider": "^4.0.13",
-    "@testcontainers/postgresql": "^12.1.0",
-    "@types/node": "^26.5.1",
+    "@ai-sdk/anthropic": "^4.0.69",
+    "@ai-sdk/mistral": "^4.0.55",
+    "@ai-sdk/openai": "^4.0.82",
+    "@ai-sdk/openai-compatible": "^3.0.60",
+    "@ai-sdk/provider": "^4.0.20",
+    "@testcontainers/postgresql": "^12.2.0",
+    "@types/node": "^26.6.3",
     "@types/pg": "^8.23.1",
-    "ai": "^7.0.97",
-    "pg": "^8.23.0",
-    "pg-boss": "^12.30.0",
-    "testcontainers": "^12.1.0",
+    "ai": "^7.0.123",
+    "drizzle-orm": "^0.45.3",
+    "pg": "^8.23.1",
+    "pg-boss": "^12.35.0",
+    "testcontainers": "^12.2.0",
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0",
-    "zod": "^4.6.0"
+    "vitest": "^5.0.3",
+    "zod": "^4.6.5"
   },
   "scripts": {
     "build": "tsdown",