octaflow 0.24.0 → 0.25.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 The Octabits Authors
+Copyright (c) 2025–2026 The Octabits Authors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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,63 @@ 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 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/index.d.ts

@@ -58,7 +58,7 @@ export declare function createInstrumentedEmbeddingModel(model: EmbeddingModelV4
  * (1 USD = 1,000,000 microdollars) to avoid float accumulation.
  *
  * The pricing table is injectable: pass your own to `createCostEstimator` for a
- * different provider/model set. A default Anthropic/OpenAI-embedding table ships.
+ * different provider/model set. A default table for the registry's vendors ships.
  */
 export interface ModelPricing {
   inputPerMillion: number;

package/dist/ai/providers/index.js

@@ -125,6 +125,7 @@ function checkEndpoint(config) {
 		url = void 0;
 	}
 	if (url === void 0 || url.protocol !== "http:" && url.protocol !== "https:") throw new AiProviderConfigError("ai_base_url_invalid", `baseUrl must be an absolute http(s) URL, got ${JSON.stringify(config.baseUrl)}`);
+	if (url.protocol === "http:" && residency.value.region !== "self-hosted") throw new AiProviderConfigError("ai_base_url_invalid", `baseUrl must be https for a vendor endpoint (residency ${residency.value.region}); http is for self-hosted endpoints only, got ${JSON.stringify(config.baseUrl)}`);
 	return residency.value;
 }
 function requireModel(modelId, field) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.24.0",
+  "version": "0.25.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
     },
@@ -115,6 +125,7 @@
     "@types/node": "^26.5.1",
     "@types/pg": "^8.23.1",
     "ai": "^7.0.97",
+    "drizzle-orm": "^0.45.2",
     "pg": "^8.23.0",
     "pg-boss": "^12.30.0",
     "testcontainers": "^12.1.0",