octaflow 0.14.0

package/dist/store-pg/index.js

@@ -0,0 +1,671 @@
+//#region src/store-pg/ddl.ts
+/**
+* Schema for the Postgres WorkflowStore adapter. Two tables mirror flow-core's
+* record shapes. Apply once at deploy time (or call `applySchema`).
+*
+* `partition_key` is the generic multi-tenancy column (the engine/store are bound
+* to one partition). Add Row Level Security on top if you need hard isolation.
+*/
+function flowStoreDdl(schema = "public") {
+	const wf = `${schema}.flow_workflow`;
+	const step = `${schema}.flow_workflow_step`;
+	return `
+${createSchemaDdl(schema)}CREATE TABLE IF NOT EXISTS ${wf} (
+  id              bigserial PRIMARY KEY,
+  partition_key   text        NOT NULL,
+  type            text        NOT NULL,
+  status          text        NOT NULL,
+  input           jsonb       NOT NULL DEFAULT '{}'::jsonb,
+  output          jsonb,
+  error           text,
+  entity_ref      text,
+  total_steps     integer     NOT NULL,
+  completed_steps integer     NOT NULL DEFAULT 0,
+  failed_steps    integer     NOT NULL DEFAULT 0,
+  metadata        jsonb,
+  idempotency_key text,
+  parent_workflow_id bigint,
+  parent_step_id     bigint,
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  started_at      timestamptz,
+  completed_at    timestamptz
+);
+
+CREATE INDEX IF NOT EXISTS flow_workflow_partition_status_idx ON ${wf} (partition_key, status);
+CREATE INDEX IF NOT EXISTS flow_workflow_parent_idx          ON ${wf} (parent_workflow_id);
+CREATE INDEX IF NOT EXISTS flow_workflow_partition_type_idx   ON ${wf} (partition_key, type);
+CREATE INDEX IF NOT EXISTS flow_workflow_partition_entity_idx ON ${wf} (partition_key, entity_ref);
+CREATE UNIQUE INDEX IF NOT EXISTS flow_workflow_idempotency_idx ON ${wf} (partition_key, idempotency_key) WHERE idempotency_key IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS ${step} (
+  id            bigserial PRIMARY KEY,
+  workflow_id   bigint      NOT NULL REFERENCES ${wf}(id) ON DELETE CASCADE,
+  partition_key text        NOT NULL,
+  key           text        NOT NULL,
+  type          text        NOT NULL,
+  status        text        NOT NULL,
+  dependencies  jsonb       NOT NULL DEFAULT '[]'::jsonb,
+  input         jsonb,
+  output        jsonb,
+  error         text,
+  metadata      jsonb,
+  attempts      integer     NOT NULL DEFAULT 0,
+  parent_step_id bigint     REFERENCES ${step}(id) ON DELETE CASCADE,
+  started_at    timestamptz,
+  completed_at  timestamptz,
+  UNIQUE (workflow_id, key)
+);
+
+CREATE INDEX IF NOT EXISTS flow_workflow_step_workflow_idx ON ${step} (workflow_id);
+CREATE INDEX IF NOT EXISTS flow_workflow_step_status_idx   ON ${step} (workflow_id, status);
+CREATE INDEX IF NOT EXISTS flow_workflow_step_parent_idx   ON ${step} (parent_step_id);
+`;
+}
+/** Default-schema DDL string. */
+const FLOW_STORE_DDL = flowStoreDdl();
+/** `CREATE SCHEMA IF NOT EXISTS` line for non-default schemas; empty for 'public'. */
+function createSchemaDdl(schema) {
+	return schema === "public" ? "" : `CREATE SCHEMA IF NOT EXISTS ${schema};\n\n`;
+}
+//#endregion
+//#region src/store-pg/executor.ts
+/**
+* Build a {@link SqlExecutor} over a `pg` {@link Pool}: top-level queries run on
+* the pool (autocommit); `transaction` checks out a client and wraps `fn` in
+* `BEGIN`/`COMMIT` (rolling back and always releasing on error). This is the
+* batteries-included executor used by the `createPg*` adapters.
+*/
+function poolExecutor(pool) {
+	const fromClient = (client) => ({
+		async query(sql, params) {
+			const res = await client.query(sql, params);
+			return {
+				rows: res.rows,
+				rowCount: res.rowCount
+			};
+		},
+		transaction(fn) {
+			return fn(fromClient(client));
+		}
+	});
+	return {
+		async query(sql, params) {
+			const res = await pool.query(sql, params);
+			return {
+				rows: res.rows,
+				rowCount: res.rowCount
+			};
+		},
+		async transaction(fn) {
+			const client = await pool.connect();
+			try {
+				await client.query("BEGIN");
+				const result = await fn(fromClient(client));
+				await client.query("COMMIT");
+				return result;
+			} catch (e) {
+				await client.query("ROLLBACK").catch(() => {});
+				throw e;
+			} finally {
+				client.release();
+			}
+		}
+	};
+}
+/**
+* Normalize a `Pool | SqlExecutor` argument to a {@link SqlExecutor}. Lets the
+* read helpers accept either the batteries-included pool or a host's RLS-scoped
+* executor without a breaking signature change. `SqlExecutor` is discriminated by
+* its `transaction` method (a `pg` `Pool` has none).
+*/
+function toExecutor(db) {
+	return "transaction" in db ? db : poolExecutor(db);
+}
+//#endregion
+//#region src/store-pg/store.ts
+const iso = (v) => v == null ? null : v instanceof Date ? v.toISOString() : v;
+function mapWorkflow(r) {
+	return {
+		id: Number(r.id),
+		type: r.type,
+		status: r.status,
+		partitionKey: r.partition_key,
+		input: r.input ?? {},
+		output: r.output ?? null,
+		error: r.error ?? null,
+		entityRef: r.entity_ref ?? null,
+		totalSteps: Number(r.total_steps),
+		completedSteps: Number(r.completed_steps),
+		failedSteps: Number(r.failed_steps),
+		metadata: r.metadata ?? null,
+		idempotencyKey: r.idempotency_key ?? null,
+		parentWorkflowId: r.parent_workflow_id == null ? null : Number(r.parent_workflow_id),
+		parentStepId: r.parent_step_id == null ? null : Number(r.parent_step_id),
+		createdAt: iso(r.created_at),
+		startedAt: iso(r.started_at),
+		completedAt: iso(r.completed_at)
+	};
+}
+function mapStep(r) {
+	return {
+		id: Number(r.id),
+		workflowId: Number(r.workflow_id),
+		key: r.key,
+		type: r.type,
+		status: r.status,
+		dependencies: r.dependencies ?? [],
+		input: r.input ?? null,
+		output: r.output ?? null,
+		error: r.error ?? null,
+		metadata: r.metadata ?? null,
+		attempts: Number(r.attempts ?? 0),
+		parentStepId: r.parent_step_id == null ? null : Number(r.parent_step_id),
+		startedAt: iso(r.started_at),
+		completedAt: iso(r.completed_at)
+	};
+}
+/**
+* A `WorkflowStore` over Postgres, addressing raw parameterized SQL through an
+* injected {@link SqlExecutor}. Partition-scoped at construction; every query is
+* additionally filtered by `partition_key` as defense-in-depth. Requires the two
+* tables from `flowStoreDdl()`.
+*
+* The executor decides *how* queries run: {@link createPgWorkflowStore} wires a
+* plain pool; a host that wants Row Level Security injects an executor whose
+* `transaction` sets the tenant GUC, so the store's own transactions run scoped.
+*/
+function createWorkflowStore(deps) {
+	const { exec, partitionKey } = deps;
+	const schema = deps.schema ?? "public";
+	const WF = `${schema}.flow_workflow`;
+	const STEP = `${schema}.flow_workflow_step`;
+	async function createWorkflow(params) {
+		return exec.transaction(async (client) => {
+			const wfRes = await client.query(`INSERT INTO ${WF} (partition_key, type, status, input, total_steps, entity_ref, idempotency_key, metadata, parent_workflow_id, parent_step_id, created_at, started_at)
+         VALUES ($1, $2, 'running', $3::jsonb, $4, $5, $6, $7::jsonb, $8, $9, $10, $10)
+         ON CONFLICT (partition_key, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
+         RETURNING id`, [
+				partitionKey,
+				params.type,
+				JSON.stringify(params.input ?? {}),
+				params.steps.length,
+				params.entityRef ?? null,
+				params.idempotencyKey ?? null,
+				params.metadata != null ? JSON.stringify(params.metadata) : null,
+				params.parentWorkflowId ?? null,
+				params.parentStepId ?? null,
+				params.startedAt
+			]);
+			if (wfRes.rows.length === 0) {
+				const existing = await client.query(`SELECT id FROM ${WF} WHERE partition_key = $1 AND idempotency_key = $2`, [partitionKey, params.idempotencyKey]);
+				const existingId = Number(existing.rows[0].id);
+				return {
+					workflowId: existingId,
+					steps: (await client.query(`SELECT * FROM ${STEP} WHERE workflow_id = $1 AND partition_key = $2 ORDER BY id`, [existingId, partitionKey])).rows.map(mapStep),
+					alreadyExisted: true
+				};
+			}
+			const workflowId = Number(wfRes.rows[0].id);
+			const steps = [];
+			for (const s of params.steps) {
+				const stepRes = await client.query(`INSERT INTO ${STEP} (workflow_id, partition_key, key, type, status, dependencies, input)
+           VALUES ($1, $2, $3, $4, 'pending', $5::jsonb, $6::jsonb)
+           RETURNING *`, [
+					workflowId,
+					partitionKey,
+					s.key,
+					s.type,
+					JSON.stringify(s.dependencies ?? []),
+					s.input != null ? JSON.stringify(s.input) : null
+				]);
+				steps.push(mapStep(stepRes.rows[0]));
+			}
+			return {
+				workflowId,
+				steps,
+				alreadyExisted: false
+			};
+		});
+	}
+	async function getWorkflow(workflowId) {
+		const res = await exec.query(`SELECT * FROM ${WF} WHERE id = $1 AND partition_key = $2`, [workflowId, partitionKey]);
+		return res.rows[0] ? mapWorkflow(res.rows[0]) : null;
+	}
+	async function getStep(stepId) {
+		const res = await exec.query(`SELECT * FROM ${STEP} WHERE id = $1 AND partition_key = $2`, [stepId, partitionKey]);
+		return res.rows[0] ? mapStep(res.rows[0]) : null;
+	}
+	async function listSteps(workflowId) {
+		return (await exec.query(`SELECT * FROM ${STEP} WHERE workflow_id = $1 AND partition_key = $2 ORDER BY id`, [workflowId, partitionKey])).rows.map(mapStep);
+	}
+	async function markStepRunning(stepId, startedAt) {
+		return ((await exec.query(`UPDATE ${STEP} SET status = 'running', started_at = $2, attempts = attempts + 1 WHERE id = $1 AND partition_key = $3 AND status = 'pending'`, [
+			stepId,
+			startedAt,
+			partitionKey
+		])).rowCount ?? 0) > 0;
+	}
+	async function markStepPending(stepId) {
+		await exec.query(`UPDATE ${STEP} SET status = 'pending' WHERE id = $1 AND partition_key = $2`, [stepId, partitionKey]);
+	}
+	async function markStepWaiting(stepId) {
+		await exec.query(`UPDATE ${STEP} SET status = 'waiting' WHERE id = $1 AND partition_key = $2`, [stepId, partitionKey]);
+	}
+	async function markStepMapping(stepId) {
+		await exec.query(`UPDATE ${STEP} SET status = 'mapping' WHERE id = $1 AND partition_key = $2`, [stepId, partitionKey]);
+	}
+	async function markStepCompensating(stepId) {
+		await exec.query(`UPDATE ${STEP} SET status = 'compensating' WHERE id = $1 AND partition_key = $2`, [stepId, partitionKey]);
+	}
+	async function markStepCompensated(stepId, error) {
+		await exec.query(`UPDATE ${STEP} SET status = 'compensated', error = COALESCE($3, error) WHERE id = $1 AND partition_key = $2`, [
+			stepId,
+			partitionKey,
+			error ?? null
+		]);
+	}
+	async function addChildSteps(workflowId, parentStepId, children) {
+		return exec.transaction(async (client) => {
+			const created = [];
+			for (const c of children) {
+				const res = await client.query(`INSERT INTO ${STEP} (workflow_id, partition_key, key, type, status, dependencies, input, parent_step_id)
+           VALUES ($1, $2, $3, $4, 'pending', '[]'::jsonb, $5::jsonb, $6)
+           RETURNING *`, [
+					workflowId,
+					partitionKey,
+					c.key,
+					c.type,
+					c.input != null ? JSON.stringify(c.input) : null,
+					parentStepId
+				]);
+				created.push(mapStep(res.rows[0]));
+			}
+			await client.query(`UPDATE ${WF} SET total_steps = total_steps + $2 WHERE id = $1 AND partition_key = $3`, [
+				workflowId,
+				children.length,
+				partitionKey
+			]);
+			return created;
+		});
+	}
+	async function listChildSteps(parentStepId) {
+		return (await exec.query(`SELECT * FROM ${STEP} WHERE parent_step_id = $1 AND partition_key = $2 ORDER BY id`, [parentStepId, partitionKey])).rows.map(mapStep);
+	}
+	async function completeStep(params) {
+		await exec.transaction(async (client) => {
+			await client.query(`UPDATE ${STEP} SET status = 'completed', output = $2::jsonb, completed_at = $3 WHERE id = $1 AND partition_key = $4`, [
+				params.stepId,
+				JSON.stringify(params.output),
+				params.completedAt,
+				partitionKey
+			]);
+			await client.query(`UPDATE ${WF} SET completed_steps = completed_steps + 1 WHERE id = $1 AND partition_key = $2`, [params.workflowId, partitionKey]);
+		});
+	}
+	async function failStep(params) {
+		await exec.transaction(async (client) => {
+			await client.query(`UPDATE ${STEP} SET status = 'failed', error = $2, completed_at = $3 WHERE id = $1 AND partition_key = $4`, [
+				params.stepId,
+				params.error,
+				params.completedAt,
+				partitionKey
+			]);
+			await client.query(`UPDATE ${WF} SET failed_steps = failed_steps + 1 WHERE id = $1 AND partition_key = $2`, [params.workflowId, partitionKey]);
+		});
+	}
+	async function skipStep(stepId, reason) {
+		await exec.query(`UPDATE ${STEP} SET status = 'skipped', error = $2 WHERE id = $1 AND partition_key = $3`, [
+			stepId,
+			reason,
+			partitionKey
+		]);
+	}
+	async function skipPendingSteps(workflowId, reason) {
+		await exec.query(`UPDATE ${STEP} SET status = 'skipped', error = $2 WHERE workflow_id = $1 AND partition_key = $3 AND status IN ('pending', 'waiting')`, [
+			workflowId,
+			reason,
+			partitionKey
+		]);
+	}
+	async function finishWorkflow(params) {
+		await exec.query(`UPDATE ${WF}
+         SET status = $2,
+             output = COALESCE($3::jsonb, output),
+             error = COALESCE($4, error),
+             completed_at = $5
+       WHERE id = $1 AND partition_key = $6`, [
+			params.workflowId,
+			params.status,
+			params.output != null ? JSON.stringify(params.output) : null,
+			params.error ?? null,
+			params.completedAt,
+			partitionKey
+		]);
+	}
+	async function listWorkflows(filters) {
+		const conds = ["partition_key = $1"];
+		const args = [partitionKey];
+		if (filters.status) {
+			args.push(filters.status);
+			conds.push(`status = $${args.length}`);
+		}
+		if (filters.type) {
+			args.push(filters.type);
+			conds.push(`type = $${args.length}`);
+		}
+		if (filters.entityRef) {
+			args.push(filters.entityRef);
+			conds.push(`entity_ref = $${args.length}`);
+		}
+		args.push(filters.limit ?? 50);
+		const limitIdx = args.length;
+		const wfRes = await exec.query(`SELECT * FROM ${WF} WHERE ${conds.join(" AND ")} ORDER BY id DESC LIMIT $${limitIdx}`, args);
+		if (wfRes.rows.length === 0) return [];
+		const ids = wfRes.rows.map((r) => Number(r.id));
+		const stepRes = await exec.query(`SELECT * FROM ${STEP} WHERE workflow_id = ANY($1::bigint[]) AND partition_key = $2 ORDER BY id`, [ids, partitionKey]);
+		const stepsByWf = /* @__PURE__ */ new Map();
+		for (const row of stepRes.rows) {
+			const s = mapStep(row);
+			const list = stepsByWf.get(s.workflowId) ?? [];
+			list.push(s);
+			stepsByWf.set(s.workflowId, list);
+		}
+		return wfRes.rows.map((r) => ({
+			...mapWorkflow(r),
+			steps: stepsByWf.get(Number(r.id)) ?? []
+		}));
+	}
+	async function listRunningWorkflows() {
+		return (await exec.query(`SELECT * FROM ${WF} WHERE partition_key = $1 AND status = 'running'`, [partitionKey])).rows.map(mapWorkflow);
+	}
+	async function findStuckSteps(workflowId, cutoff) {
+		return (await exec.query(`SELECT * FROM ${STEP}
+        WHERE workflow_id = $1 AND partition_key = $2 AND status = 'running' AND started_at IS NOT NULL AND started_at < $3::timestamptz`, [
+			workflowId,
+			partitionKey,
+			cutoff
+		])).rows.map(mapStep);
+	}
+	return {
+		createWorkflow,
+		getWorkflow,
+		getStep,
+		listSteps,
+		markStepRunning,
+		markStepPending,
+		markStepWaiting,
+		markStepMapping,
+		markStepCompensating,
+		markStepCompensated,
+		addChildSteps,
+		listChildSteps,
+		completeStep,
+		failStep,
+		skipStep,
+		skipPendingSteps,
+		finishWorkflow,
+		listWorkflows,
+		listRunningWorkflows,
+		findStuckSteps
+	};
+}
+/**
+* A `WorkflowStore` backed by a `pg` {@link Pool} — the batteries-included
+* adapter that owns its own connections/transactions (via {@link poolExecutor})
+* and requires the tables from `flowStoreDdl()`. Unchanged public surface: hosts
+* that need Row Level Security or their own migrations should instead build an
+* executor and call {@link createWorkflowStore}.
+*/
+function createPgWorkflowStore(deps) {
+	return createWorkflowStore({
+		exec: poolExecutor(deps.pool),
+		partitionKey: deps.partitionKey,
+		schema: deps.schema
+	});
+}
+/** Convenience: apply the flow-store schema to a database. */
+async function applySchema(pool, ddl) {
+	await pool.query(ddl);
+}
+//#endregion
+//#region src/store-pg/gate.ts
+const DEFAULT_RATE_TABLE = "flow_rate_bucket";
+const DEFAULT_LEASE_TABLE = "flow_step_lease";
+/** DDL for the gate's two tables. Apply once at deploy time (or via `applySchema`). */
+function flowGateDdl(opts = {}) {
+	const schema = opts.schema ?? "public";
+	const rateName = opts.rateBucketTable ?? DEFAULT_RATE_TABLE;
+	const leaseName = opts.leaseTable ?? DEFAULT_LEASE_TABLE;
+	const rate = `${schema}.${rateName}`;
+	const lease = `${schema}.${leaseName}`;
+	return `
+${createSchemaDdl(schema)}CREATE TABLE IF NOT EXISTS ${rate} (
+  partition_key text             NOT NULL,
+  step_type     text             NOT NULL,
+  tokens        double precision NOT NULL,
+  updated_at    timestamptz      NOT NULL DEFAULT now(),
+  PRIMARY KEY (partition_key, step_type)
+);
+
+CREATE TABLE IF NOT EXISTS ${lease} (
+  partition_key text        NOT NULL,
+  step_type     text        NOT NULL,
+  step_id       bigint      NOT NULL,
+  acquired_at   timestamptz NOT NULL DEFAULT now(),
+  expires_at    timestamptz NOT NULL,
+  PRIMARY KEY (partition_key, step_type, step_id)
+);
+CREATE INDEX IF NOT EXISTS ${leaseName}_active_idx ON ${lease} (partition_key, step_type, expires_at);
+`;
+}
+/** Default-schema gate DDL string. */
+const FLOW_GATE_DDL = flowGateDdl();
+/** Sentinel thrown to roll back the acquire transaction when the concurrency cap is hit. */
+const CAP_HIT = Symbol("flow.gate.capHit");
+/**
+* A Postgres-backed {@link StepGate} addressing all SQL through an injected
+* {@link SqlExecutor}, so a host can run the concurrency/rate SQL under Row Level
+* Security (inject an executor that sets the tenant GUC) instead of a plain pool.
+* Global concurrency caps + rate limits shared across all workers; drop-in for
+* the in-memory gate via `WorkflowEngineDeps.gate`.
+*/
+function createStepGate(config) {
+	const { exec, partitionKey } = config;
+	const schema = config.schema ?? "public";
+	const RATE = `${schema}.${config.tables?.rateBucket ?? DEFAULT_RATE_TABLE}`;
+	const LEASE = `${schema}.${config.tables?.lease ?? DEFAULT_LEASE_TABLE}`;
+	const leaseTtl = Math.max(1, config.leaseTtlSeconds ?? 600);
+	const concurrencyRetry = Math.max(1, config.concurrencyRetrySeconds ?? 1);
+	async function releaseLease(req) {
+		await exec.query(`DELETE FROM ${LEASE} WHERE partition_key = $1 AND step_type = $2 AND step_id = $3`, [
+			partitionKey,
+			req.stepType,
+			req.stepId
+		]);
+	}
+	/** Reserve a concurrency slot atomically. Returns whether a slot was granted. */
+	async function acquireLease(req, cap) {
+		try {
+			return await exec.transaction(async (tx) => {
+				await tx.query("SELECT pg_advisory_xact_lock(hashtext($1))", [`${partitionKey}:${req.stepType}`]);
+				await tx.query(`DELETE FROM ${LEASE} WHERE partition_key = $1 AND step_type = $2 AND expires_at < now()`, [partitionKey, req.stepType]);
+				if (((await tx.query(`SELECT count(*)::int AS n FROM ${LEASE} WHERE partition_key = $1 AND step_type = $2 AND step_id <> $3`, [
+					partitionKey,
+					req.stepType,
+					req.stepId
+				])).rows[0]?.n ?? 0) >= cap) throw CAP_HIT;
+				await tx.query(`INSERT INTO ${LEASE} (partition_key, step_type, step_id, expires_at)
+           VALUES ($1, $2, $3, now() + ($4 || ' seconds')::interval)
+           ON CONFLICT (partition_key, step_type, step_id)
+           DO UPDATE SET acquired_at = now(), expires_at = EXCLUDED.expires_at`, [
+					partitionKey,
+					req.stepType,
+					req.stepId,
+					String(leaseTtl)
+				]);
+				return true;
+			});
+		} catch (e) {
+			if (e === CAP_HIT) return false;
+			throw e;
+		}
+	}
+	/** Consume a rate token atomically (refill-then-decrement in one UPDATE). */
+	async function consumeToken(req, rule) {
+		const capacity = rule.burst ?? Math.max(1, Math.ceil(rule.perSecond));
+		return ((await exec.query(`INSERT INTO ${RATE} AS bucket (partition_key, step_type, tokens, updated_at)
+       VALUES ($1, $2, $3, now())
+       ON CONFLICT (partition_key, step_type) DO UPDATE
+       SET tokens = LEAST($4, bucket.tokens + EXTRACT(EPOCH FROM (now() - bucket.updated_at)) * $5) - 1,
+           updated_at = now()
+       WHERE LEAST($4, bucket.tokens + EXTRACT(EPOCH FROM (now() - bucket.updated_at)) * $5) >= 1
+       RETURNING tokens`, [
+			partitionKey,
+			req.stepType,
+			capacity - 1,
+			capacity,
+			rule.perSecond
+		])).rowCount ?? 0) > 0;
+	}
+	return { async acquire(req) {
+		const cRule = config.concurrency?.[req.stepType];
+		const rRule = config.rateLimit?.[req.stepType];
+		let leaseHeld = false;
+		if (cRule) {
+			if (!await acquireLease(req, cRule.maxConcurrent)) return {
+				admitted: false,
+				retryAfterSeconds: concurrencyRetry
+			};
+			leaseHeld = true;
+		}
+		if (rRule) {
+			if (!await consumeToken(req, rRule)) {
+				if (leaseHeld) await releaseLease(req);
+				return {
+					admitted: false,
+					retryAfterSeconds: Math.max(1, Math.ceil(1 / rRule.perSecond))
+				};
+			}
+		}
+		return {
+			admitted: true,
+			release: async () => {
+				if (leaseHeld) await releaseLease(req);
+			}
+		};
+	} };
+}
+/**
+* A Postgres-backed {@link StepGate} over a `pg` {@link Pool} — the
+* batteries-included adapter (via {@link poolExecutor}). Hosts that need Row
+* Level Security should build an executor and call {@link createStepGate}.
+*/
+function createPgStepGate(config) {
+	const { pool, ...rest } = config;
+	return createStepGate({
+		exec: poolExecutor(pool),
+		...rest
+	});
+}
+//#endregion
+//#region src/store-pg/event-sink.ts
+/**
+* DDL for the append-only run-history table. Apply once at deploy time (alongside
+* `flowStoreDdl`), or call `applySchema(pool, flowEventDdl())`.
+*/
+function flowEventDdl(schema = "public") {
+	const evt = `${schema}.flow_step_event`;
+	return `
+${createSchemaDdl(schema)}CREATE TABLE IF NOT EXISTS ${evt} (
+  id            bigserial PRIMARY KEY,
+  partition_key text        NOT NULL,
+  workflow_id   bigint      NOT NULL,
+  workflow_type text,
+  step_id       bigint,
+  step_key      text,
+  step_type     text,
+  event_type    text        NOT NULL,
+  attempt       integer,
+  duration_ms   integer,
+  error         text,
+  at            timestamptz NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS flow_step_event_workflow_idx ON ${evt} (partition_key, workflow_id, id);
+`;
+}
+/** Default-schema event-table DDL string. */
+const FLOW_EVENT_DDL = flowEventDdl();
+/**
+* A `FlowObserver` that appends engine events to `flow_step_event` through an
+* injected {@link SqlExecutor}, so a host can run the write under Row Level
+* Security (inject an executor that sets the tenant GUC) instead of a plain pool.
+* `record` is fire-and-forget (never throws, never blocks the engine); `flush()`
+* awaits the in-flight inserts.
+*/
+function createEventSink(deps) {
+	const { exec, partitionKey } = deps;
+	const EVT = `${deps.schema ?? "public"}.flow_step_event`;
+	const pending = /* @__PURE__ */ new Set();
+	return {
+		record(event) {
+			if (event.partitionKey !== partitionKey) return;
+			const p = exec.query(`INSERT INTO ${EVT}
+             (partition_key, workflow_id, workflow_type, step_id, step_key, step_type, event_type, attempt, duration_ms, error, at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`, [
+				partitionKey,
+				event.workflowId,
+				event.workflowType ?? null,
+				event.stepId ?? null,
+				event.stepKey ?? null,
+				event.stepType ?? null,
+				event.type,
+				event.attempt ?? null,
+				event.durationMs ?? null,
+				event.error ?? null,
+				event.at
+			]).catch(() => {}).finally(() => {
+				pending.delete(p);
+			});
+			pending.add(p);
+		},
+		async flush() {
+			await Promise.all(Array.from(pending));
+		}
+	};
+}
+/**
+* A `FlowObserver` backed by a `pg` {@link Pool} — the batteries-included sink
+* (via {@link poolExecutor}). Hosts that need Row Level Security should build an
+* executor and call {@link createEventSink} instead.
+*/
+function createPgEventSink(deps) {
+	return createEventSink({
+		exec: poolExecutor(deps.pool),
+		partitionKey: deps.partitionKey,
+		schema: deps.schema
+	});
+}
+/**
+* Read a workflow's run history, ordered oldest-first. Accepts either a
+* `pg` {@link Pool} (batteries-included) or a host's {@link SqlExecutor} (e.g.
+* RLS-scoped) — both route through the same seam.
+*/
+async function readFlowEvents(db, params) {
+	const EVT = `${params.schema ?? "public"}.flow_step_event`;
+	return (await toExecutor(db).query(`SELECT * FROM ${EVT} WHERE partition_key = $1 AND workflow_id = $2 ORDER BY id`, [params.partitionKey, params.workflowId])).rows.map((r) => ({
+		type: r.event_type,
+		at: r.at instanceof Date ? r.at.toISOString() : String(r.at),
+		partitionKey: r.partition_key,
+		workflowId: Number(r.workflow_id),
+		workflowType: r.workflow_type ?? void 0,
+		stepId: r.step_id == null ? void 0 : Number(r.step_id),
+		stepKey: r.step_key ?? void 0,
+		stepType: r.step_type ?? void 0,
+		attempt: r.attempt == null ? void 0 : Number(r.attempt),
+		durationMs: r.duration_ms == null ? void 0 : Number(r.duration_ms),
+		error: r.error ?? void 0
+	}));
+}
+//#endregion
+export { FLOW_EVENT_DDL, FLOW_GATE_DDL, FLOW_STORE_DDL, applySchema, createEventSink, createPgEventSink, createPgStepGate, createPgWorkflowStore, createSchemaDdl, createStepGate, createWorkflowStore, flowEventDdl, flowGateDdl, flowStoreDdl, poolExecutor, readFlowEvents, toExecutor };