@smithers-orchestrator/db 0.16.0

package/src/output.js

@@ -0,0 +1,240 @@
+import { and, eq } from "drizzle-orm";
+import { getTableColumns } from "drizzle-orm/utils";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { Effect } from "effect";
+import { z } from "zod";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { withSqliteWriteRetryEffect } from "./write-retry.js";
+/** @typedef {import("drizzle-orm").AnyColumn} AnyColumn */
+/** @typedef {import("./output/OutputKey.ts").OutputKey} _OutputKey */
+/** @typedef {import("drizzle-orm").Table} _Table */
+/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} BunSQLiteDatabase */
+
+/**
+ * @param {_Table} table
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ * @param {unknown} payload
+ * @returns {Record<string, unknown>}
+ */
+export function buildOutputRow(table, runId, nodeId, iteration, payload) {
+    const cols = getTableColumns(table);
+    const keys = Object.keys(cols);
+    const hasPayload = keys.includes("payload");
+    const payloadOnly = hasPayload && keys.every((key) => key === "runId" || key === "nodeId" || key === "iteration" || key === "payload");
+    if (payloadOnly) {
+        return { runId, nodeId, iteration, payload: (payload ?? null) };
+    }
+    return {
+        ...(/** @type {Record<string, unknown>} */ (payload ?? {})),
+        runId, nodeId, iteration,
+    };
+}
+/**
+ * @param {unknown} payload
+ * @returns {unknown}
+ */
+export function stripAutoColumns(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return payload;
+    }
+    const { runId: _runId, nodeId: _nodeId, iteration: _iteration, ...rest } = /** @type {Record<string, unknown>} */ (payload);
+    return rest;
+}
+/**
+ * @param {_Table} table
+ * @returns {{ runId: AnyColumn; nodeId: AnyColumn; iteration?: AnyColumn; }}
+ */
+export function getKeyColumns(table) {
+    const cols = getTableColumns(table);
+    const runId = cols.runId;
+    const nodeId = cols.nodeId;
+    const iteration = cols.iteration;
+    if (!runId || !nodeId) {
+        throw new SmithersError("DB_MISSING_COLUMNS", `Output table ${table["_"]?.name ?? ""} must include runId and nodeId columns.`);
+    }
+    return { runId, nodeId, iteration };
+}
+/**
+ * @param {_Table} table
+ * @param {_OutputKey} key
+ * @returns {ReturnType<typeof and>}
+ */
+export function buildKeyWhere(table, key) {
+    const cols = getKeyColumns(table);
+    const clauses = [eq(cols.runId, key.runId), eq(cols.nodeId, key.nodeId)];
+    if (cols.iteration) clauses.push(eq(cols.iteration, key.iteration ?? 0));
+    return and(...clauses);
+}
+/**
+ * @template T
+ * @param {BunSQLiteDatabase<Record<string, unknown>>} db
+ * @param {_Table} table
+ * @param {_OutputKey} key
+ * @returns {Effect.Effect<T | undefined, SmithersError>}
+ */
+export function selectOutputRowEffect(db, table, key) {
+    const where = buildKeyWhere(table, key);
+    return Effect.tryPromise({
+        try: () => db.select().from(table).where(where).limit(1),
+        catch: (cause) => toSmithersError(cause, `select output ${table["_"]?.name ?? "output"}`, {
+            code: "DB_QUERY_FAILED",
+            details: { outputTable: table["_"]?.name ?? "output" },
+        }),
+    }).pipe(Effect.map((rows) => rows[0]), Effect.annotateLogs({
+        outputTable: table["_"]?.name ?? "output",
+        runId: key.runId,
+        nodeId: key.nodeId,
+        iteration: key.iteration ?? 0,
+    }), Effect.withLogSpan("db:select-output-row"));
+}
+/**
+ * @template T
+ * @param {BunSQLiteDatabase<Record<string, unknown>>} db
+ * @param {_Table} table
+ * @param {_OutputKey} key
+ * @returns {Promise<T | undefined>}
+ */
+export function selectOutputRow(db, table, key) {
+    return Effect.runPromise(selectOutputRowEffect(db, table, key));
+}
+/**
+ * @param {BunSQLiteDatabase<Record<string, unknown>>} db
+ * @param {_Table} table
+ * @param {_OutputKey} key
+ * @param {Record<string, unknown>} payload
+ * @returns {Effect.Effect<void, SmithersError>}
+ */
+export function upsertOutputRowEffect(db, table, key, payload) {
+    const cols = getKeyColumns(table);
+    /** @type {Record<string, unknown>} */
+    const values = { ...payload };
+    values.runId = key.runId;
+    values.nodeId = key.nodeId;
+    if (cols.iteration) values.iteration = key.iteration ?? 0;
+    const target = cols.iteration ? [cols.runId, cols.nodeId, cols.iteration] : [cols.runId, cols.nodeId];
+    return withSqliteWriteRetryEffect(() => Effect.tryPromise({
+        try: () => db.insert(table).values(values).onConflictDoUpdate({ target, set: values }),
+        catch: (cause) => toSmithersError(cause, `upsert output ${table["_"]?.name ?? "output"}`, {
+            code: "DB_WRITE_FAILED",
+            details: { outputTable: table["_"]?.name ?? "output" },
+        }),
+    }), { label: `upsert output ${table["_"]?.name ?? "output"}` }).pipe(Effect.asVoid, Effect.annotateLogs({
+        outputTable: table["_"]?.name ?? "output",
+        runId: key.runId,
+        nodeId: key.nodeId,
+        iteration: key.iteration ?? 0,
+    }), Effect.withLogSpan("db:upsert-output-row"));
+}
+/**
+ * @param {BunSQLiteDatabase<Record<string, unknown>>} db
+ * @param {_Table} table
+ * @param {_OutputKey} key
+ * @param {Record<string, unknown>} payload
+ * @returns {Promise<void>}
+ */
+export function upsertOutputRow(db, table, key, payload) {
+    return Effect.runPromise(upsertOutputRowEffect(db, table, key, payload));
+}
+/**
+ * @param {_Table} table
+ * @param {unknown} payload
+ * @returns {{ ok: boolean; data?: unknown; error?: z.ZodError; }}
+ */
+export function validateOutput(table, payload) {
+    const schema = createInsertSchema(table);
+    const result = schema.safeParse(payload);
+    if (result.success) return { ok: true, data: result.data };
+    return { ok: false, error: result.error };
+}
+/**
+ * @param {_Table} table
+ * @param {unknown} payload
+ * @returns {{ ok: boolean; data?: unknown; error?: z.ZodError; }}
+ */
+export function validateExistingOutput(table, payload) {
+    const schema = createSelectSchema(table);
+    const result = schema.safeParse(payload);
+    if (result.success) return { ok: true, data: result.data };
+    return { ok: false, error: result.error };
+}
+/**
+ * @param {_Table} table
+ * @returns {z.ZodObject}
+ */
+export function getAgentOutputSchema(table) {
+    const baseSchema = createInsertSchema(table);
+    const rest = { ...baseSchema.shape };
+    delete rest.runId;
+    delete rest.nodeId;
+    delete rest.iteration;
+    return z.object(rest);
+}
+/**
+ * @param {_Table | z.ZodObject} tableOrSchema
+ * @param {z.ZodObject} [zodSchema]
+ * @returns {string}
+ */
+export function describeSchemaShape(tableOrSchema, zodSchema) {
+    const schema = zodSchema ?? (isZodSchema(tableOrSchema) ? tableOrSchema : null);
+    if (schema && typeof schema.toJSONSchema === "function") {
+        const jsonSchema = schema.toJSONSchema();
+        return JSON.stringify(jsonSchema, null, 2);
+    }
+    if (!isZodSchema(tableOrSchema)) {
+        const agentSchema = getAgentOutputSchema(tableOrSchema);
+        if (typeof agentSchema.toJSONSchema === "function") {
+            const jsonSchema = agentSchema.toJSONSchema();
+            return JSON.stringify(jsonSchema, null, 2);
+        }
+    }
+    const target = schema ?? (isZodSchema(tableOrSchema) ? tableOrSchema : getAgentOutputSchema(tableOrSchema));
+    const shape = target.shape;
+    /** @type {Record<string, string>} */
+    const fields = {};
+    for (const [key, zodType] of Object.entries(shape)) {
+        fields[key] = describeZodType(/** @type {z.ZodType} */ (zodType));
+    }
+    return JSON.stringify(fields, null, 2);
+}
+/**
+ * @param {unknown} val
+ * @returns {val is z.ZodObject}
+ */
+function isZodSchema(val) {
+    return (!!val && typeof val === "object" && "shape" in val && typeof (/** @type {{ shape: unknown }} */ (val)).shape === "object");
+}
+/**
+ * @param {z.ZodType} schema
+ * @returns {string}
+ */
+function describeZodType(schema) {
+    const internal = /** @type {{ _zod?: { def?: Record<string, unknown> } }} */ (/** @type {unknown} */ (schema));
+    if (internal._zod?.def) {
+        const def = internal._zod.def;
+        const typeName = /** @type {string} */ (def.type);
+        if (typeName === "optional" || typeName === "default" || typeName === "nullable") {
+            const inner = def.innerType ? describeZodType(/** @type {z.ZodType} */ (def.innerType)) : "unknown";
+            if (typeName === "optional") return `${inner} (optional)`;
+            if (typeName === "nullable") return `${inner} | null`;
+            return inner;
+        }
+        if (typeName === "string") return "string";
+        if (typeName === "number" || typeName === "int" || typeName === "float") return "number";
+        if (typeName === "boolean") return "boolean";
+        if (typeName === "array") {
+            const itemType = def.element ? describeZodType(/** @type {z.ZodType} */ (def.element)) : "unknown";
+            return `${itemType}[]`;
+        }
+        if (typeName === "object") return "object";
+        if (typeName === "enum") return `enum(${(/** @type {unknown[]} */ (def.values ?? [])).join(" | ")})`;
+        if (typeName === "literal") return `literal(${JSON.stringify(def.value)})`;
+        if (typeName === "union") {
+            const options = (/** @type {z.ZodType[]} */ (def.options ?? [])).map((o) => describeZodType(o));
+            return options.join(" | ");
+        }
+    }
+    return "unknown";
+}

package/src/react-output.js

@@ -0,0 +1,10 @@
+/**
+ * @param {unknown} payload
+ */
+export function stripAutoColumns(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return payload;
+    }
+    const { runId: _runId, nodeId: _nodeId, iteration: _iteration, ...rest } = payload;
+    return rest;
+}

package/src/runState/ComputeRunStateOptions.ts

@@ -0,0 +1,4 @@
+export type ComputeRunStateOptions = {
+  now?: number;
+  staleThresholdMs?: number;
+};

package/src/runState/DeriveRunStateInput.ts

@@ -0,0 +1,10 @@
+import type { RunRow } from "../adapter/RunRow.ts";
+
+export type DeriveRunStateInput = {
+  run: RunRow;
+  pendingApproval?: { nodeId: string; requestedAtMs: number } | null;
+  pendingTimer?: { nodeId: string; firesAtMs: number } | null;
+  pendingEvent?: { nodeId: string; correlationKey: string } | null;
+  now?: number;
+  staleThresholdMs?: number;
+};

package/src/runState/RUN_STATE_HEARTBEAT_STALE_MS.js

@@ -0,0 +1 @@
+export const RUN_STATE_HEARTBEAT_STALE_MS = 30_000;

package/src/runState/ReasonBlocked.ts

@@ -0,0 +1,10 @@
+export type ReasonBlocked =
+  | { kind: "approval"; nodeId: string; requestedAt: string }
+  | { kind: "event"; nodeId: string; correlationKey: string }
+  | { kind: "timer"; nodeId: string; wakeAt: string }
+  | {
+      kind: "provider";
+      nodeId: string;
+      code: "rate-limit" | "auth" | "timeout";
+    }
+  | { kind: "tool"; nodeId: string; toolName: string; code: string };

package/src/runState/ReasonUnhealthy.ts

@@ -0,0 +1,6 @@
+export type ReasonUnhealthy =
+  | { kind: "engine-heartbeat-stale"; lastHeartbeatAt: string }
+  | { kind: "ui-heartbeat-stale"; lastSeenAt: string }
+  | { kind: "db-lock" }
+  | { kind: "sandbox-unreachable" }
+  | { kind: "supervisor-backoff"; attempt: number; nextAt: string };

package/src/runState/RunState.ts

@@ -0,0 +1,12 @@
+export type RunState =
+  | "running"
+  | "waiting-approval"
+  | "waiting-event"
+  | "waiting-timer"
+  | "recovering"
+  | "stale"
+  | "orphaned"
+  | "failed"
+  | "cancelled"
+  | "succeeded"
+  | "unknown";

package/src/runState/RunStateView.ts

@@ -0,0 +1,11 @@
+import type { ReasonBlocked } from "./ReasonBlocked.ts";
+import type { ReasonUnhealthy } from "./ReasonUnhealthy.ts";
+import type { RunState } from "./RunState.ts";
+
+export type RunStateView = {
+  runId: string;
+  state: RunState;
+  blocked?: ReasonBlocked;
+  unhealthy?: ReasonUnhealthy;
+  computedAt: string;
+};

package/src/runState/computeRunState.js

@@ -0,0 +1,22 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { computeRunStateFromRow } from "./computeRunStateFromRow.js";
+
+/** @typedef {import("../adapter/SmithersDb.js").SmithersDb} SmithersDb */
+/** @typedef {import("./RunStateView.ts").RunStateView} RunStateView */
+/** @typedef {import("./ComputeRunStateOptions.ts").ComputeRunStateOptions} ComputeRunStateOptions */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ * @param {ComputeRunStateOptions} [options]
+ * @returns {Promise<RunStateView>}
+ */
+export async function computeRunState(adapter, runId, options = {}) {
+    const run = await adapter.getRun(runId);
+    if (!run) {
+        throw new SmithersError("RUN_NOT_FOUND", `Run not found: ${runId}`, {
+            runId,
+        });
+    }
+    return computeRunStateFromRow(adapter, run, options);
+}

package/src/runState/computeRunStateFromRow.js

@@ -0,0 +1,102 @@
+import { deriveRunState } from "./deriveRunState.js";
+import { parseEventMeta } from "./parseEventMeta.js";
+import { parseTimerMeta } from "./parseTimerMeta.js";
+
+/** @typedef {import("../adapter/RunRow.ts").RunRow} RunRow */
+/** @typedef {import("../adapter/SmithersDb.js").SmithersDb} SmithersDb */
+/** @typedef {import("./RunStateView.ts").RunStateView} RunStateView */
+/** @typedef {import("./ComputeRunStateOptions.ts").ComputeRunStateOptions} ComputeRunStateOptions */
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {RunRow} run
+ * @param {ComputeRunStateOptions} [options]
+ * @returns {Promise<RunStateView>}
+ */
+export async function computeRunStateFromRow(adapter, run, options = {}) {
+    let pendingApproval = null;
+    let pendingTimer = null;
+    let pendingEvent = null;
+
+    if (run.status === "waiting-approval") {
+        pendingApproval = await loadPendingApproval(adapter, run.runId);
+    } else if (run.status === "waiting-timer") {
+        pendingTimer = await loadPendingTimer(adapter, run.runId);
+    } else if (run.status === "waiting-event") {
+        pendingEvent = await loadPendingEvent(adapter, run.runId);
+    }
+
+    return deriveRunState({
+        run,
+        pendingApproval,
+        pendingTimer,
+        pendingEvent,
+        now: options.now,
+        staleThresholdMs: options.staleThresholdMs,
+    });
+}
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ */
+async function loadPendingApproval(adapter, runId) {
+    const approvals = await adapter.listPendingApprovals(runId);
+    let earliest = null;
+    for (const a of approvals) {
+        if (typeof a.requestedAtMs !== "number") continue;
+        if (earliest == null || a.requestedAtMs < earliest.requestedAtMs) {
+            earliest = { nodeId: a.nodeId, requestedAtMs: a.requestedAtMs };
+        }
+    }
+    return earliest;
+}
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ */
+async function loadPendingTimer(adapter, runId) {
+    const nodes = await adapter.listNodes(runId);
+    let earliest = null;
+    for (const node of nodes) {
+        if (node.state !== "waiting-timer") continue;
+        const attempts = await adapter.listAttempts(
+            runId,
+            node.nodeId,
+            node.iteration ?? 0,
+        );
+        const waiting =
+            attempts.find((a) => a.state === "waiting-timer") ?? attempts[0];
+        const parsed = parseTimerMeta(waiting?.metaJson);
+        if (parsed == null) continue;
+        if (earliest == null || parsed.firesAtMs < earliest.firesAtMs) {
+            earliest = { nodeId: node.nodeId, firesAtMs: parsed.firesAtMs };
+        }
+    }
+    return earliest;
+}
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ */
+async function loadPendingEvent(adapter, runId) {
+    const nodes = await adapter.listNodes(runId);
+    for (const node of nodes) {
+        if (node.state !== "waiting-event") continue;
+        const attempts = await adapter.listAttempts(
+            runId,
+            node.nodeId,
+            node.iteration ?? 0,
+        );
+        const waiting =
+            attempts.find((a) => a.state === "waiting-event") ?? attempts[0];
+        const parsed = parseEventMeta(waiting?.metaJson);
+        return {
+            nodeId: node.nodeId,
+            correlationKey: parsed?.correlationKey ?? "",
+        };
+    }
+    return null;
+}

package/src/runState/deriveRunState.js

@@ -0,0 +1,109 @@
+import { RUN_STATE_HEARTBEAT_STALE_MS } from "./RUN_STATE_HEARTBEAT_STALE_MS.js";
+
+/** @typedef {import("./DeriveRunStateInput.ts").DeriveRunStateInput} DeriveRunStateInput */
+/** @typedef {import("./RunStateView.ts").RunStateView} RunStateView */
+
+/**
+ * @param {DeriveRunStateInput} input
+ * @returns {RunStateView}
+ */
+export function deriveRunState(input) {
+    const {
+        run,
+        pendingApproval = null,
+        pendingTimer = null,
+        pendingEvent = null,
+        now = Date.now(),
+        staleThresholdMs = RUN_STATE_HEARTBEAT_STALE_MS,
+    } = input;
+
+    const computedAt = new Date(now).toISOString();
+    const base = { runId: run.runId, computedAt };
+
+    switch (run.status) {
+        case "finished":
+        case "continued":
+            return { ...base, state: "succeeded" };
+        case "failed":
+            return { ...base, state: "failed" };
+        case "cancelled":
+            return { ...base, state: "cancelled" };
+        case "waiting-approval":
+            return pendingApproval
+                ? {
+                      ...base,
+                      state: "waiting-approval",
+                      blocked: {
+                          kind: "approval",
+                          nodeId: pendingApproval.nodeId,
+                          requestedAt: new Date(
+                              pendingApproval.requestedAtMs,
+                          ).toISOString(),
+                      },
+                  }
+                : { ...base, state: "waiting-approval" };
+        case "waiting-timer":
+            return pendingTimer
+                ? {
+                      ...base,
+                      state: "waiting-timer",
+                      blocked: {
+                          kind: "timer",
+                          nodeId: pendingTimer.nodeId,
+                          wakeAt: new Date(pendingTimer.firesAtMs).toISOString(),
+                      },
+                  }
+                : { ...base, state: "waiting-timer" };
+        case "waiting-event":
+            return pendingEvent
+                ? {
+                      ...base,
+                      state: "waiting-event",
+                      blocked: {
+                          kind: "event",
+                          nodeId: pendingEvent.nodeId,
+                          correlationKey: pendingEvent.correlationKey,
+                      },
+                  }
+                : { ...base, state: "waiting-event" };
+        case "running":
+            return classifyRunning(run, now, staleThresholdMs, base);
+        default:
+            return { ...base, state: "unknown" };
+    }
+}
+
+/**
+ * @param {import("../adapter/RunRow.ts").RunRow} run
+ * @param {number} now
+ * @param {number} staleThresholdMs
+ * @param {{ runId: string; computedAt: string }} base
+ * @returns {RunStateView}
+ */
+function classifyRunning(run, now, staleThresholdMs, base) {
+    const heartbeat =
+        typeof run.heartbeatAtMs === "number" ? run.heartbeatAtMs : null;
+    const startedAt =
+        typeof run.startedAtMs === "number" ? run.startedAtMs : null;
+    // Fall back to startedAt so a brand-new run with no heartbeat yet
+    // isn't reported as stale.
+    const lastAlive = Math.max(heartbeat ?? 0, startedAt ?? 0);
+
+    if (lastAlive === 0) {
+        return { ...base, state: "unknown" };
+    }
+
+    if (now - lastAlive <= staleThresholdMs) {
+        return { ...base, state: "running" };
+    }
+
+    const lastHeartbeatAt = new Date(lastAlive).toISOString();
+    // Without a registered owner, supervisor has nothing to take over.
+    const orphaned =
+        run.runtimeOwnerId == null || run.runtimeOwnerId.length === 0;
+    return {
+        ...base,
+        state: orphaned ? "orphaned" : "stale",
+        unhealthy: { kind: "engine-heartbeat-stale", lastHeartbeatAt },
+    };
+}

package/src/runState/parseEventMeta.js

@@ -0,0 +1,18 @@
+/**
+ * @param {string | null | undefined} metaJson
+ * @returns {{ correlationKey: string } | null}
+ */
+export function parseEventMeta(metaJson) {
+    if (!metaJson) return null;
+    try {
+        const parsed = JSON.parse(metaJson);
+        const key =
+            parsed?.event?.correlationKey ??
+            parsed?.correlationKey ??
+            parsed?.event?.eventName ??
+            null;
+        return typeof key === "string" ? { correlationKey: key } : null;
+    } catch {
+        return null;
+    }
+}

package/src/runState/parseTimerMeta.js

@@ -0,0 +1,16 @@
+/**
+ * @param {string | null | undefined} metaJson
+ * @returns {{ firesAtMs: number } | null}
+ */
+export function parseTimerMeta(metaJson) {
+    if (!metaJson) return null;
+    try {
+        const parsed = JSON.parse(metaJson);
+        const candidate = Number(parsed?.timer?.firesAtMs);
+        return Number.isFinite(candidate)
+            ? { firesAtMs: Math.floor(candidate) }
+            : null;
+    } catch {
+        return null;
+    }
+}

package/src/runState-types.ts

@@ -0,0 +1,23 @@
+export type { RunState } from "./runState/RunState.ts";
+export type { RunStateView } from "./runState/RunStateView.ts";
+
+import type { DeriveRunStateInput } from "./runState/DeriveRunStateInput.ts";
+import type { RunStateView } from "./runState/RunStateView.ts";
+
+export type ComputeRunStateOptions = {
+  now?: number;
+  staleThresholdMs?: number;
+};
+
+export declare const RUN_STATE_HEARTBEAT_STALE_MS: number;
+export declare function deriveRunState(input: DeriveRunStateInput): RunStateView;
+export declare function computeRunState(
+  adapter: unknown,
+  runId: string,
+  options?: ComputeRunStateOptions,
+): Promise<RunStateView>;
+export declare function computeRunStateFromRow(
+  adapter: unknown,
+  run: unknown,
+  options?: ComputeRunStateOptions,
+): Promise<RunStateView>;

package/src/runState.js

@@ -0,0 +1,7 @@
+/** @typedef {import("./runState/RunState.ts").RunState} RunState */
+/** @typedef {import("./runState/RunStateView.ts").RunStateView} RunStateView */
+
+export { computeRunState } from "./runState/computeRunState.js";
+export { computeRunStateFromRow } from "./runState/computeRunStateFromRow.js";
+export { deriveRunState } from "./runState/deriveRunState.js";
+export { RUN_STATE_HEARTBEAT_STALE_MS } from "./runState/RUN_STATE_HEARTBEAT_STALE_MS.js";

package/src/schema-signature.js

@@ -0,0 +1,22 @@
+import { getTableName } from "drizzle-orm";
+import { getTableColumns } from "drizzle-orm/utils";
+import { createHash } from "node:crypto";
+/** @typedef {import("drizzle-orm").Table} _Table */
+
+/**
+ * @param {_Table} table
+ * @returns {string}
+ */
+export function schemaSignature(table) {
+    const cols = getTableColumns(table);
+    const keys = Object.keys(cols).sort();
+    const parts = [getTableName(table)];
+    for (const key of keys) {
+        const col = cols[key];
+        const type = col?.columnType ?? col?.dataType ?? col?.getSQLType?.() ?? "unknown";
+        const notNull = col?.notNull ? "1" : "0";
+        const primary = col?.primary ? "1" : "0";
+        parts.push(`${key}:${type}:${notNull}:${primary}`);
+    }
+    return createHash("sha256").update(parts.join("|")).digest("hex");
+}