@gencow/core 0.1.23 → 0.1.24

package/dist/index.d.ts

@@ -9,6 +9,10 @@ export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe,
 export type { Storage } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
 export type { Scheduler, ScheduleOptions, FailedJob, CreateSchedulerOptions, ScheduledJobRecord } from "./scheduler.js";
+export { workflow, getWorkflowDef, getRegisteredWorkflows, getWorkflowResumeActionName, getWorkflowRealtimeKey, createWorkflowRealtimeToken, serializeWorkflowValue, deserializeWorkflowValue, parseWorkflowDurationMs, DEFAULT_WORKFLOW_MAX_DURATION_MS, DEFAULT_WORKFLOW_MAX_RETRIES, WORKFLOW_RESUME_ACTION_PREFIX, WORKFLOW_REALTIME_KEY_PREFIX } from "./workflow.js";
+export { deriveWorkflowStatus } from "./workflow-types.js";
+export type { WorkflowCtx, WorkflowHandler, WorkflowOptions, WorkflowDef, WorkflowResumePayload, WorkflowStartResult, WorkflowSignalResult, WorkflowStatus, WorkflowDerivedStatus, WorkflowSummary, WorkflowSnapshot, WorkflowStepSnapshot, WorkflowListArgs, WorkflowDuration } from "./workflow-types.js";
+export { loadWorkflowSnapshot } from "./workflows-api.js";
 export { v, parseArgs, GencowValidationError } from "./v.js";
 export type { Validator, Infer, InferArgs } from "./v.js";
 export { withRetry } from "./retry.js";

package/dist/index.js

@@ -6,6 +6,9 @@
  */
 export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions } from "./reactive.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
+export { workflow, getWorkflowDef, getRegisteredWorkflows, getWorkflowResumeActionName, getWorkflowRealtimeKey, createWorkflowRealtimeToken, serializeWorkflowValue, deserializeWorkflowValue, parseWorkflowDurationMs, DEFAULT_WORKFLOW_MAX_DURATION_MS, DEFAULT_WORKFLOW_MAX_RETRIES, WORKFLOW_RESUME_ACTION_PREFIX, WORKFLOW_REALTIME_KEY_PREFIX } from "./workflow.js";
+export { deriveWorkflowStatus } from "./workflow-types.js";
+export { loadWorkflowSnapshot } from "./workflows-api.js";
 export { v, parseArgs, GencowValidationError } from "./v.js";
 export { withRetry } from "./retry.js";
 export { cronJobs } from "./crons.js";

package/dist/workflow-types.d.ts

@@ -0,0 +1,81 @@
+import type { GencowCtx } from "./reactive.js";
+import type { InferArgs } from "./v.js";
+export type WorkflowStatus = "pending" | "running" | "completed" | "failed";
+export type WorkflowDuration = number | string;
+export type WorkflowDerivedStatus = WorkflowStatus | "queued" | "waiting" | "sleeping";
+export declare function deriveWorkflowStatus(status: WorkflowStatus, currentStep: string | null | undefined): WorkflowDerivedStatus;
+export interface WorkflowSummary {
+    id: string;
+    name: string;
+    status: WorkflowStatus;
+    derivedStatus: WorkflowDerivedStatus;
+    currentStep: string | null;
+    error: string | null;
+    retryCount: number;
+    maxRetries: number;
+    maxDurationMs: number;
+    startedAt: string;
+    updatedAt: string;
+    completedAt: string | null;
+}
+export interface WorkflowStepSnapshot {
+    name: string;
+    status: WorkflowStatus;
+    output: unknown;
+    error: string | null;
+    startedAt: string | null;
+    updatedAt: string;
+    completedAt: string | null;
+}
+export interface WorkflowSnapshot extends WorkflowSummary {
+    args: unknown;
+    result: unknown;
+    steps: WorkflowStepSnapshot[];
+    /** Opaque realtime channel for exact-id workflow updates. */
+    realtimeKey: string;
+}
+export interface WorkflowListArgs {
+    limit?: number;
+    status?: WorkflowDerivedStatus;
+}
+export interface WorkflowStartResult {
+    id: string;
+    name: string;
+    status: "pending";
+    scheduledJobId: string;
+}
+export interface WorkflowSignalResult {
+    ok: boolean;
+    workflowId: string;
+    event: string;
+    scheduledJobId: string | null;
+}
+export interface WorkflowResumePayload {
+    workflowId: string;
+}
+export interface WorkflowCtx extends GencowCtx {
+    workflowId: string;
+    workflowName: string;
+    step<TResult>(name: string, run: () => Promise<TResult>): Promise<TResult>;
+    sleep(duration: WorkflowDuration): Promise<void>;
+    waitForEvent<TPayload = unknown>(name: string, timeout?: WorkflowDuration): Promise<TPayload>;
+    parallel<TTasks extends ReadonlyArray<() => Promise<any>>>(tasks: TTasks): Promise<{
+        [K in keyof TTasks]: Awaited<ReturnType<TTasks[K]>>;
+    }>;
+}
+export type WorkflowHandler<TArgs, TReturn> = (wf: WorkflowCtx, args: TArgs) => Promise<TReturn>;
+export interface WorkflowOptions<TSchema = any, TReturn = any> {
+    args?: TSchema;
+    public?: boolean;
+    maxDuration?: WorkflowDuration;
+    retries?: number;
+    handler: WorkflowHandler<InferArgs<TSchema>, TReturn>;
+}
+export interface WorkflowDef<TSchema = any, TReturn = any> {
+    name: string;
+    argsSchema?: TSchema;
+    isPublic: boolean;
+    maxDurationMs: number;
+    maxRetries: number;
+    handler: WorkflowHandler<InferArgs<TSchema>, TReturn>;
+}

package/dist/workflow-types.js

@@ -0,0 +1,12 @@
+export function deriveWorkflowStatus(status, currentStep) {
+    if (status !== "pending") {
+        return status;
+    }
+    if (currentStep?.startsWith("sleep#")) {
+        return "sleeping";
+    }
+    if (currentStep?.startsWith("wait:")) {
+        return "waiting";
+    }
+    return "queued";
+}

package/dist/workflow.d.ts

@@ -0,0 +1,30 @@
+import type { MutationDef } from "./reactive.js";
+import type { WorkflowDef, WorkflowDuration, WorkflowOptions, WorkflowStartResult } from "./workflow-types.js";
+declare global {
+    var __gencow_workflowRegistry: Map<string, WorkflowDef<any, any>>;
+}
+export declare const DEFAULT_WORKFLOW_MAX_DURATION_MS: number;
+export declare const DEFAULT_WORKFLOW_MAX_RETRIES = 3;
+export declare const WORKFLOW_RESUME_ACTION_PREFIX = "__gencow.workflow.resume";
+export declare const WORKFLOW_REALTIME_KEY_PREFIX = "__gencow.workflow.state";
+type SerializedWorkflowValue = {
+    __gencowUndefined: true;
+} | {
+    value: unknown;
+};
+export declare function serializeWorkflowValue(value: unknown): SerializedWorkflowValue;
+export declare function deserializeWorkflowValue(value: unknown): unknown;
+export declare function parseWorkflowDurationMs(raw: WorkflowDuration, label?: string): number;
+export declare function getWorkflowResumeActionName(name: string): string;
+export declare function createWorkflowRealtimeToken(): string;
+export declare function getWorkflowRealtimeKey(workflowId: string, realtimeToken: string): string;
+export declare function getWorkflowDef(name: string): WorkflowDef | undefined;
+export declare function getRegisteredWorkflows(): WorkflowDef[];
+/**
+ * workflow() — durable multi-step execution with step memoization.
+ *
+ * The returned value is still a mutation definition, so existing API codegen and
+ * frontend hooks keep working without extra workflow-specific tooling.
+ */
+export declare function workflow<TSchema = any, TReturn = any>(name: string, options: WorkflowOptions<TSchema, TReturn>): MutationDef<TSchema, WorkflowStartResult>;
+export {};

package/dist/workflow.js

@@ -0,0 +1,157 @@
+import { sql } from "drizzle-orm";
+import { mutation } from "./reactive.js";
+import { registerWorkflowsApi } from "./workflows-api.js";
+const workflowRegistry = globalThis.__gencow_workflowRegistry ??= new Map();
+export const DEFAULT_WORKFLOW_MAX_DURATION_MS = 30 * 60 * 1000;
+export const DEFAULT_WORKFLOW_MAX_RETRIES = 3;
+export const WORKFLOW_RESUME_ACTION_PREFIX = "__gencow.workflow.resume";
+export const WORKFLOW_REALTIME_KEY_PREFIX = "__gencow.workflow.state";
+function isSerializedWorkflowValue(value) {
+    return !!value && typeof value === "object" && ("__gencowUndefined" in value ||
+        "value" in value);
+}
+export function serializeWorkflowValue(value) {
+    const payload = value === undefined
+        ? { __gencowUndefined: true }
+        : { value };
+    try {
+        return JSON.parse(JSON.stringify(payload));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`workflow() only persists JSON-serializable values. Failed to serialize workflow payload: ${reason}`);
+    }
+}
+export function deserializeWorkflowValue(value) {
+    if (!isSerializedWorkflowValue(value))
+        return value;
+    if ("__gencowUndefined" in value)
+        return undefined;
+    return value.value;
+}
+function clampRetries(retries) {
+    if (retries == null)
+        return DEFAULT_WORKFLOW_MAX_RETRIES;
+    if (!Number.isFinite(retries) || retries < 0) {
+        throw new Error(`workflow() retries must be a non-negative finite number, got "${retries}"`);
+    }
+    return Math.floor(retries);
+}
+function parseDurationString(raw, label) {
+    const normalized = raw.trim().toLowerCase();
+    const match = normalized.match(/^(\d+)(ms|s|m|h|d)$/);
+    if (!match) {
+        throw new Error(`${label} must be a number of ms or a string like "30m", "90s", "1h" — got "${raw}"`);
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const unitMs = unit === "ms" ? 1 :
+        unit === "s" ? 1_000 :
+            unit === "m" ? 60_000 :
+                unit === "h" ? 3_600_000 :
+                    86_400_000;
+    return value * unitMs;
+}
+export function parseWorkflowDurationMs(raw, label = "workflow duration") {
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw) || raw <= 0) {
+            throw new Error(`${label} must be a positive finite number, got "${raw}"`);
+        }
+        return Math.floor(raw);
+    }
+    if (typeof raw !== "string") {
+        throw new Error(`${label} must be a positive finite number or a string like "30m", "90s", "1h" — got "${String(raw)}"`);
+    }
+    return parseDurationString(raw, label);
+}
+function normalizeMaxDurationMs(maxDuration) {
+    if (maxDuration == null)
+        return DEFAULT_WORKFLOW_MAX_DURATION_MS;
+    return parseWorkflowDurationMs(maxDuration, "workflow() maxDuration");
+}
+export function getWorkflowResumeActionName(name) {
+    return `${WORKFLOW_RESUME_ACTION_PREFIX}.${name}`;
+}
+export function createWorkflowRealtimeToken() {
+    return crypto.randomUUID().replace(/-/g, "");
+}
+export function getWorkflowRealtimeKey(workflowId, realtimeToken) {
+    return `${WORKFLOW_REALTIME_KEY_PREFIX}.${workflowId}.${realtimeToken}`;
+}
+export function getWorkflowDef(name) {
+    return workflowRegistry.get(name);
+}
+export function getRegisteredWorkflows() {
+    return Array.from(workflowRegistry.values());
+}
+/**
+ * workflow() — durable multi-step execution with step memoization.
+ *
+ * The returned value is still a mutation definition, so existing API codegen and
+ * frontend hooks keep working without extra workflow-specific tooling.
+ */
+export function workflow(name, options) {
+    registerWorkflowsApi();
+    const maxDurationMs = normalizeMaxDurationMs(options.maxDuration);
+    const maxRetries = clampRetries(options.retries);
+    const def = {
+        name,
+        argsSchema: options.args,
+        isPublic: options.public === true,
+        maxDurationMs,
+        maxRetries,
+        handler: options.handler,
+    };
+    workflowRegistry.set(name, def);
+    return mutation(name, {
+        args: options.args,
+        public: options.public,
+        handler: async (ctx, args) => {
+            const workflowId = crypto.randomUUID();
+            const resumeAction = getWorkflowResumeActionName(name);
+            const ownerId = ctx.auth.getUserIdentity()?.id ?? null;
+            const persistedArgs = serializeWorkflowValue(args ?? {});
+            const realtimeToken = createWorkflowRealtimeToken();
+            await ctx.unsafeDb.execute(sql `
+                INSERT INTO _gencow_workflows (
+                    id,
+                    name,
+                    args,
+                    realtime_token,
+                    status,
+                    retry_count,
+                    max_retries,
+                    max_duration_ms,
+                    user_id
+                )
+                VALUES (
+                    ${workflowId},
+                    ${name},
+                    ${JSON.stringify(persistedArgs)}::jsonb,
+                    ${realtimeToken},
+                    'pending',
+                    0,
+                    ${maxRetries},
+                    ${maxDurationMs},
+                    ${ownerId}
+                )
+            `);
+            try {
+                const scheduledJobId = ctx.scheduler.runAfter(0, resumeAction, { workflowId });
+                return {
+                    id: workflowId,
+                    name,
+                    status: "pending",
+                    scheduledJobId,
+                };
+            }
+            catch (error) {
+                await ctx.unsafeDb.execute(sql `
+                    DELETE FROM _gencow_workflows
+                    WHERE id = ${workflowId}
+                `);
+                throw error;
+            }
+        },
+    });
+}

package/dist/workflows-api.d.ts

@@ -0,0 +1,13 @@
+import type { WorkflowSnapshot } from "./workflow-types.js";
+declare global {
+    var __gencow_workflowsApiRegistered: boolean | undefined;
+}
+type WorkflowDbLike = {
+    execute: (query: unknown) => Promise<unknown>;
+};
+export declare function loadWorkflowSnapshot(db: WorkflowDbLike, workflowId: string, options?: {
+    viewerUserId?: string | null;
+    requireViewerMatch?: boolean;
+}): Promise<WorkflowSnapshot | null>;
+export declare function registerWorkflowsApi(): void;
+export {};

package/dist/workflows-api.js

@@ -0,0 +1,328 @@
+import { sql } from "drizzle-orm";
+import { mutation, query } from "./reactive.js";
+import { createWorkflowRealtimeToken, deserializeWorkflowValue, getWorkflowResumeActionName, getWorkflowRealtimeKey, serializeWorkflowValue, } from "./workflow.js";
+import { GencowValidationError, v } from "./v.js";
+import { deriveWorkflowStatus } from "./workflow-types.js";
+const WORKFLOW_STATUSES = new Set([
+    "pending",
+    "running",
+    "completed",
+    "failed",
+]);
+const WORKFLOW_DERIVED_PENDING_STATUSES = new Set([
+    "queued",
+    "waiting",
+    "sleeping",
+]);
+function rowsFromResult(result) {
+    if (Array.isArray(result))
+        return result;
+    if (result && typeof result === "object" && Array.isArray(result.rows)) {
+        return result.rows;
+    }
+    return [];
+}
+function parseJsonField(value) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function toIsoString(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) ? parsed.toISOString() : String(value);
+}
+function toOptionalIsoString(value) {
+    return value ? toIsoString(value) : null;
+}
+function mapWorkflowSummary(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        status: row.status,
+        derivedStatus: deriveWorkflowStatus(row.status, row.current_step),
+        currentStep: row.current_step,
+        error: row.error,
+        retryCount: row.retry_count,
+        maxRetries: row.max_retries,
+        maxDurationMs: Number(row.max_duration_ms),
+        startedAt: toIsoString(row.started_at),
+        updatedAt: toIsoString(row.updated_at),
+        completedAt: toOptionalIsoString(row.completed_at),
+    };
+}
+function mapWorkflowStep(row) {
+    return {
+        name: row.step_name,
+        status: row.status,
+        output: deserializeWorkflowValue(parseJsonField(row.output)),
+        error: row.error,
+        startedAt: toOptionalIsoString(row.started_at),
+        updatedAt: toIsoString(row.updated_at),
+        completedAt: toOptionalIsoString(row.completed_at),
+    };
+}
+function normalizeListLimit(limit) {
+    if (limit == null)
+        return 20;
+    if (!Number.isFinite(limit)) {
+        throw new GencowValidationError(`Argument "limit": expected a finite number, got ${limit}`);
+    }
+    return Math.max(1, Math.min(100, Math.floor(limit)));
+}
+function normalizeStatus(status) {
+    if (status == null)
+        return undefined;
+    if (!WORKFLOW_STATUSES.has(status)) {
+        throw new GencowValidationError(`Argument "status": expected one of pending, running, completed, failed`);
+    }
+    return status;
+}
+function normalizeDerivedStatus(status) {
+    if (status == null)
+        return undefined;
+    if (WORKFLOW_DERIVED_PENDING_STATUSES.has(status)) {
+        return status;
+    }
+    return normalizeStatus(status);
+}
+function toWorkflowStatusFilter(status) {
+    if (status == null)
+        return undefined;
+    if (WORKFLOW_DERIVED_PENDING_STATUSES.has(status)) {
+        return "pending";
+    }
+    return status;
+}
+async function ensureWorkflowRealtimeToken(db, workflowId, currentToken) {
+    if (currentToken && currentToken.trim() !== "")
+        return currentToken;
+    const nextToken = createWorkflowRealtimeToken();
+    const updateResult = await db.execute(sql `
+        UPDATE _gencow_workflows
+        SET realtime_token = ${nextToken}
+        WHERE id = ${workflowId}
+          AND (realtime_token IS NULL OR realtime_token = '')
+        RETURNING realtime_token
+    `);
+    const updatedToken = rowsFromResult(updateResult)[0]?.realtime_token ?? null;
+    if (updatedToken && updatedToken.trim() !== "")
+        return updatedToken;
+    const rereadResult = await db.execute(sql `
+        SELECT realtime_token
+        FROM _gencow_workflows
+        WHERE id = ${workflowId}
+        LIMIT 1
+    `);
+    const rereadToken = rowsFromResult(rereadResult)[0]?.realtime_token ?? null;
+    return rereadToken && rereadToken.trim() !== "" ? rereadToken : null;
+}
+async function loadWorkflowSignalTarget(db, workflowId) {
+    const result = await db.execute(sql `
+        SELECT
+            id,
+            name,
+            status,
+            current_step,
+            user_id
+        FROM _gencow_workflows
+        WHERE id = ${workflowId}
+        LIMIT 1
+    `);
+    return rowsFromResult(result)[0] ?? null;
+}
+export async function loadWorkflowSnapshot(db, workflowId, options) {
+    const workflowResult = await db.execute(sql `
+        SELECT
+            id,
+            name,
+            args,
+            status,
+            current_step,
+            result,
+            error,
+            retry_count,
+            max_retries,
+            max_duration_ms,
+            started_at,
+            updated_at,
+            completed_at,
+            realtime_token,
+            user_id
+        FROM _gencow_workflows
+        WHERE id = ${workflowId}
+        LIMIT 1
+    `);
+    const row = rowsFromResult(workflowResult)[0] ?? null;
+    if (!row)
+        return null;
+    const viewerUserId = options?.viewerUserId ?? null;
+    if (options?.requireViewerMatch && row.user_id && row.user_id !== viewerUserId) {
+        return null;
+    }
+    const realtimeToken = await ensureWorkflowRealtimeToken(db, workflowId, row.realtime_token);
+    if (!realtimeToken)
+        return null;
+    const stepsResult = await db.execute(sql `
+        SELECT
+            step_name,
+            status,
+            output,
+            error,
+            started_at,
+            updated_at,
+            completed_at
+        FROM _gencow_workflow_steps
+        WHERE workflow_id = ${workflowId}
+        ORDER BY COALESCE(started_at, updated_at) ASC, step_name ASC
+    `);
+    return {
+        ...mapWorkflowSummary(row),
+        args: deserializeWorkflowValue(parseJsonField(row.args)),
+        result: deserializeWorkflowValue(parseJsonField(row.result)),
+        steps: rowsFromResult(stepsResult).map(mapWorkflowStep),
+        realtimeKey: getWorkflowRealtimeKey(row.id, realtimeToken),
+    };
+}
+export function registerWorkflowsApi() {
+    if (globalThis.__gencow_workflowsApiRegistered)
+        return;
+    globalThis.__gencow_workflowsApiRegistered = true;
+    query("workflows.get", {
+        args: { id: v.string() },
+        public: true,
+        handler: async (ctx, args) => {
+            return loadWorkflowSnapshot(ctx.unsafeDb, args.id, {
+                viewerUserId: ctx.auth.getUserIdentity()?.id ?? null,
+                requireViewerMatch: true,
+            });
+        },
+    });
+    mutation("workflows.signal", {
+        args: {
+            id: v.string(),
+            event: v.string(),
+            payload: v.optional(v.any()),
+        },
+        public: true,
+        handler: async (ctx, args) => {
+            const normalizedEvent = args.event.trim();
+            if (!normalizedEvent) {
+                throw new GencowValidationError(`Argument "event": expected a non-empty string`);
+            }
+            const workflow = await loadWorkflowSignalTarget(ctx.unsafeDb, args.id);
+            const viewerUserId = ctx.auth.getUserIdentity()?.id ?? null;
+            if (!workflow || (workflow.user_id && workflow.user_id !== viewerUserId)) {
+                return {
+                    ok: false,
+                    workflowId: args.id,
+                    event: normalizedEvent,
+                    scheduledJobId: null,
+                };
+            }
+            if (workflow.status === "completed" || workflow.status === "failed") {
+                return {
+                    ok: false,
+                    workflowId: workflow.id,
+                    event: normalizedEvent,
+                    scheduledJobId: null,
+                };
+            }
+            const persistedPayload = serializeWorkflowValue(args.payload);
+            await ctx.unsafeDb.execute(sql `
+                INSERT INTO _gencow_workflow_events (
+                    id,
+                    workflow_id,
+                    event_name,
+                    payload
+                )
+                VALUES (
+                    ${crypto.randomUUID()},
+                    ${workflow.id},
+                    ${normalizedEvent},
+                    ${JSON.stringify(persistedPayload)}::jsonb
+                )
+            `);
+            let scheduledJobId = null;
+            if (workflow.status === "pending" && workflow.current_step?.startsWith("wait:")) {
+                try {
+                    scheduledJobId = ctx.scheduler.runAfter(0, getWorkflowResumeActionName(workflow.name), { workflowId: workflow.id });
+                }
+                catch {
+                    scheduledJobId = null;
+                }
+            }
+            return {
+                ok: true,
+                workflowId: workflow.id,
+                event: normalizedEvent,
+                scheduledJobId,
+            };
+        },
+    });
+    query("workflows.list", {
+        args: {
+            limit: v.optional(v.number()),
+            status: v.optional(v.string()),
+        },
+        handler: async (ctx, args) => {
+            const userId = ctx.auth.requireAuth().id;
+            const limit = normalizeListLimit(args.limit);
+            const requestedStatus = normalizeDerivedStatus(args.status);
+            const status = toWorkflowStatusFilter(requestedStatus);
+            const result = status == null
+                ? await ctx.unsafeDb.execute(sql `
+                    SELECT
+                        id,
+                        name,
+                        args,
+                        status,
+                        current_step,
+                        result,
+                        error,
+                        retry_count,
+                        max_retries,
+                        max_duration_ms,
+                        started_at,
+                        updated_at,
+                        completed_at,
+                        user_id
+                    FROM _gencow_workflows
+                    WHERE user_id = ${userId}
+                    ORDER BY started_at DESC
+                    LIMIT ${limit}
+                `)
+                : await ctx.unsafeDb.execute(sql `
+                    SELECT
+                        id,
+                        name,
+                        args,
+                        status,
+                        current_step,
+                        result,
+                        error,
+                        retry_count,
+                        max_retries,
+                        max_duration_ms,
+                        started_at,
+                        updated_at,
+                        completed_at,
+                        user_id
+                    FROM _gencow_workflows
+                    WHERE user_id = ${userId}
+                      AND status = ${status}
+                    ORDER BY started_at DESC
+                    LIMIT ${limit}
+                `);
+            return rowsFromResult(result)
+                .map(mapWorkflowSummary)
+                .filter((row) => requestedStatus == null || row.derivedStatus === requestedStatus);
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gencow/core",
-    "version": "0.1.23",
+    "version": "0.1.24",
     "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
     "type": "module",
     "main": "dist/index.js",

package/src/__tests__/dist-exports.test.ts

@@ -91,6 +91,12 @@ describe("dist/index.js 필수 export", () => {
         expect(typeof distModule.mutation).toBe("function");
     });
 
+    it("workflow export가 존재하고 함수이다", async () => {
+        if (!distModule) distModule = await import(DIST_INDEX);
+        expect(distModule.workflow).toBeDefined();
+        expect(typeof distModule.workflow).toBe("function");
+    });
+
     it("v export가 존재하고 객체이다", async () => {
         if (!distModule) distModule = await import(DIST_INDEX);
         expect(distModule.v).toBeDefined();