@kubun/plugin-workflow 0.13.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/definition.d.ts

@@ -0,0 +1,25 @@
+import type { FlowAction, HandlersRecord } from '@sozai/flow';
+import type { Validator } from '@sozai/schema';
+export type RetryPolicy = {
+    maxAttempts?: number;
+    backoff?: 'exponential' | 'fixed';
+    baseMs?: number;
+    maxMs?: number;
+};
+export type TerminalStatus = 'completed' | 'failed' | 'cancelled';
+export type TerminalInfo = {
+    instanceID: string;
+    name: string;
+    status: TerminalStatus;
+    error?: string;
+};
+export type WorkflowDefinition<State extends Record<string, unknown> = Record<string, unknown>, Handlers extends HandlersRecord<State> = HandlersRecord<State>> = {
+    name: string;
+    handlers: Handlers;
+    initialAction: FlowAction<State, Handlers>;
+    stateValidator?: Validator<State>;
+    queue?: string;
+    retry?: RetryPolicy;
+    onTerminal?: (info: TerminalInfo) => void;
+};
+export declare function defineWorkflow<State extends Record<string, unknown>, Handlers extends HandlersRecord<State> = HandlersRecord<State>>(def: WorkflowDefinition<State, Handlers>): WorkflowDefinition<State, Handlers>;

package/lib/definition.js

@@ -0,0 +1,8 @@
+// A typed identity helper: authors get inference on handlers/state while the
+// object is validated and returned unchanged for registration.
+export function defineWorkflow(def) {
+    if (def.name.length === 0) {
+        throw new Error('Workflow definition requires a non-empty name');
+    }
+    return def;
+}

package/lib/engine.d.ts

@@ -0,0 +1,21 @@
+import type { Logger } from '@kubun/logger';
+import type { WorkflowStoreAPI } from '@kubun/store-workflow';
+import type { GetRandomID } from '@sozai/runtime';
+import type { RetryPolicy } from './definition.js';
+import type { WorkflowAPI } from './types.js';
+export declare function backoff(attempts: number, policy?: RetryPolicy): number;
+export declare function parseEvery(spec: string): number;
+export type WorkflowEngineDeps = {
+    getStore: () => Promise<WorkflowStoreAPI>;
+    logger: Logger;
+    now?: () => number;
+    getRandomID?: GetRandomID;
+    tickMs?: number;
+};
+export type WorkflowEngine = {
+    api: WorkflowAPI;
+    recover(): Promise<Array<string>>;
+    tick(): Promise<void>;
+    dispose(): void;
+};
+export declare function createWorkflowEngine(deps: WorkflowEngineDeps): WorkflowEngine;

package/lib/engine.js

@@ -0,0 +1,478 @@
+import { EventEmitter } from '@sozai/event';
+import { createFlow } from '@sozai/flow';
+// One runner may hold an instance's lease for this long before another boot may
+// reclaim it as stranded.
+const LEASE_MS = 30_000;
+// Default scheduler cadence; injectable via deps so tests drive `tick()` directly.
+const DEFAULT_TICK_MS = 1_000;
+// Backoff for a failed attempt (1-based). `fixed` returns `baseMs`; `exponential`
+// doubles per attempt, capped at `maxMs`. Pure so it is unit-testable.
+export function backoff(attempts, policy) {
+    const base = policy?.baseMs ?? 1_000;
+    const raw = (policy?.backoff ?? 'exponential') === 'fixed' ? base : base * 2 ** (attempts - 1);
+    return policy?.maxMs != null ? Math.min(raw, policy.maxMs) : raw;
+}
+// Tiny local interval parser (no dependency, no cron). Accepts `<n>ms|s|m|h` and
+// a bare integer (= ms). Throws on anything else so a bad spec fails loudly at
+// `schedule()` time rather than silently never firing.
+const INTERVAL_UNITS = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000
+};
+export function parseEvery(spec) {
+    const match = /^(\d+)(ms|s|m|h)?$/.exec(spec.trim());
+    if (match == null) throw new Error(`Invalid interval "${spec}"`);
+    return Number(match[1]) * (match[2] != null ? INTERVAL_UNITS[match[2]] : 1);
+}
+const TERMINAL = new Set([
+    'completed',
+    'failed',
+    'cancelled'
+]);
+function toStatus(row) {
+    return {
+        instanceID: row.instance_id,
+        name: row.name,
+        queue: row.queue,
+        status: row.status,
+        attempts: row.attempts,
+        lastError: row.last_error,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    };
+}
+export function createWorkflowEngine(deps) {
+    const now = deps.now ?? Date.now;
+    const logger = deps.logger;
+    const events = new EventEmitter();
+    const registry = new Map();
+    // A per-process identity for lease ownership. A fresh engine over the same DB
+    // (a "reboot") gets a new one, which is what makes crash-reclaim observable.
+    const bootID = (deps.getRandomID ?? (()=>crypto.randomUUID()))();
+    // Instances currently being driven in THIS process, so `cancel` can signal the
+    // running flow via its AbortController.
+    const running = new Map();
+    // In-flight drives, tracked so nudges are not lost and errors are logged.
+    const inflight = new Set();
+    let storePromise;
+    function store() {
+        storePromise ??= deps.getStore();
+        return storePromise;
+    }
+    function track(promise) {
+        inflight.add(promise);
+        void promise.finally(()=>inflight.delete(promise));
+    }
+    function fireTerminal(def, instanceID, status, error) {
+        events.fire(status, {
+            instanceID,
+            name: def.name
+        });
+        if (def.onTerminal != null) {
+            try {
+                def.onTerminal({
+                    instanceID,
+                    name: def.name,
+                    status,
+                    error
+                });
+            } catch (cause) {
+                logger.warn('workflow onTerminal threw', {
+                    name: def.name,
+                    instanceID,
+                    error: cause
+                });
+            }
+        }
+    }
+    // Runs an already-claimed, already-leased row through the flow loop. The tick's
+    // `claimDue` does the claiming, so this path never re-claims.
+    async function run(row) {
+        const instanceID = row.instance_id;
+        // In-process guard: never drive the same instance twice concurrently (the
+        // live lease is the cross-process guard).
+        if (running.has(instanceID)) return;
+        const controller = new AbortController();
+        running.set(instanceID, controller);
+        try {
+            const s = await store();
+            const def = registry.get(row.name);
+            if (def == null) {
+                logger.warn('no workflow registered for claimed instance', {
+                    name: row.name,
+                    instanceID
+                });
+                return;
+            }
+            const generate = createFlow({
+                handlers: def.handlers,
+                stateValidator: def.stateValidator
+            });
+            const flow = generate({
+                state: row.state,
+                action: row.next_action ?? def.initialAction,
+                signal: controller.signal
+            });
+            events.fire('started', {
+                instanceID,
+                name: def.name
+            });
+            // Pull the generator by hand: flow returns terminal values (`end`/`error`/
+            // `aborted`) with `done:true`, which `for await…of` would swallow — so the
+            // loop must inspect every value, done or not.
+            while(true){
+                const { value } = await flow.next();
+                // Defensive: flow always yields a defined value, but the generator's
+                // return type admits `undefined`.
+                if (value == null) return;
+                if (value.status === 'state' || value.status === 'action') {
+                    // Renew before persisting: if the lease was reclaimed elsewhere, stop
+                    // without writing so a stranded runner cannot clobber the reclaimer's
+                    // state on a late wake-up.
+                    const held = await s.renew(instanceID, bootID, LEASE_MS, now());
+                    if (!held) return;
+                    const nextAction = value.status === 'action' ? value.action : null;
+                    await s.checkpoint(instanceID, {
+                        state: flow.getState(),
+                        nextAction,
+                        status: 'running'
+                    }, now());
+                    events.fire('checkpoint', {
+                        instanceID,
+                        name: def.name
+                    });
+                    continue;
+                }
+                if (value.status === 'end') {
+                    // Fence terminal writes on our bootID: a lease lost during a long
+                    // pause means a reclaimer owns the row now, so write nothing.
+                    const wrote = await s.finish(instanceID, {
+                        status: 'completed',
+                        state: flow.getState()
+                    }, now(), bootID);
+                    if (!wrote) return;
+                    fireTerminal(def, instanceID, 'completed');
+                    return;
+                }
+                if (value.status === 'aborted') {
+                    const wrote = await s.finish(instanceID, {
+                        status: 'cancelled',
+                        state: flow.getState()
+                    }, now(), bootID);
+                    if (!wrote) return;
+                    fireTerminal(def, instanceID, 'cancelled');
+                    return;
+                }
+                // status === 'error'. `getState()` here is the PRE-handler input state.
+                const error = String(value.error);
+                const attempts = row.attempts + 1;
+                const maxAttempts = def.retry?.maxAttempts ?? 1;
+                if (attempts < maxAttempts) {
+                    // Retry rides the queue: re-queue `pending` with a future run gate; the
+                    // scheduler re-claims it when due. Not terminal, so no terminal event.
+                    await s.fail(instanceID, {
+                        state: flow.getState(),
+                        nextAction: row.next_action,
+                        error,
+                        attempts,
+                        runAfter: now() + backoff(attempts, def.retry),
+                        status: 'pending'
+                    }, now(), bootID);
+                    return;
+                }
+                const wrote = await s.fail(instanceID, {
+                    state: flow.getState(),
+                    nextAction: row.next_action,
+                    error,
+                    attempts,
+                    runAfter: now(),
+                    status: 'failed'
+                }, now(), bootID);
+                if (!wrote) return;
+                fireTerminal(def, instanceID, 'failed', error);
+                return;
+            }
+        } catch (cause) {
+            logger.error('workflow run failed', {
+                instanceID,
+                error: cause
+            });
+        } finally{
+            running.delete(instanceID);
+        }
+    }
+    // Per-lane concurrency. Defaults to 1; `defineQueue` raises a lane's cap.
+    const concurrency = new Map();
+    function laneConcurrency(lane) {
+        return concurrency.get(lane) ?? 1;
+    }
+    const buckets = new Map();
+    const queueOpts = new Map();
+    // Refill to `at` then report whole tokens available. Unbucketed lanes are
+    // unthrottled. Mutates lastRefillMs so tokens accrue monotonically across ticks.
+    function availableTokens(lane, at) {
+        const b = buckets.get(lane);
+        if (b == null) return Number.POSITIVE_INFINITY;
+        const elapsed = Math.max(0, at - b.lastRefillMs);
+        b.tokens = Math.min(b.capacity, b.tokens + elapsed * b.ratePerMs);
+        b.lastRefillMs = at;
+        return Math.floor(b.tokens);
+    }
+    function consumeTokens(lane, n) {
+        const b = buckets.get(lane);
+        if (b != null) b.tokens -= n;
+    }
+    function defineQueue(name, opts) {
+        const existing = queueOpts.get(name);
+        if (existing != null) {
+            if (existing.concurrency !== opts.concurrency || existing.ratePerMinute !== opts.ratePerMinute) {
+                logger.warn('workflow queue "{name}" defined with different options, ignoring', {
+                    name
+                });
+            }
+            return;
+        }
+        queueOpts.set(name, opts);
+        concurrency.set(name, opts.concurrency);
+        if (opts.ratePerMinute != null) {
+            // Burst capacity = ratePerMinute; start full so a fresh lane can dispatch
+            // immediately up to the per-minute allowance.
+            buckets.set(name, {
+                tokens: opts.ratePerMinute,
+                capacity: opts.ratePerMinute,
+                ratePerMs: opts.ratePerMinute / 60_000,
+                lastRefillMs: now()
+            });
+        }
+    }
+    // Promote every due schedule into a queued instance. Enqueue is keyed by
+    // (schedule, fire time) so a re-entrant or crash-resumed tick coalesces on the
+    // idempotency key instead of double-firing; the advance then arms the next
+    // interval so the row leaves the due set.
+    async function promoteSchedules(s, at) {
+        const due = await s.listDueSchedules(at);
+        for (const sched of due){
+            try {
+                if (sched.every == null) {
+                    // Only interval schedules exist today; a cron-only row can't be armed.
+                    logger.warn('workflow schedule "{id}" has no interval, skipping', {
+                        id: sched.id
+                    });
+                    continue;
+                }
+                const everyMs = parseEvery(sched.every);
+                await api.enqueue(sched.workflow_name, sched.params, {
+                    idempotencyKey: `schedule:${sched.id}:${sched.next_run}`
+                });
+                await s.advanceSchedule(sched.id, at + everyMs, at);
+            } catch (cause) {
+                logger.error('workflow schedule promotion failed', {
+                    id: sched.id,
+                    error: cause
+                });
+            }
+        }
+    }
+    async function tick() {
+        try {
+            const s = await store();
+            const at = now();
+            // Promote due schedules first so their instances are claimable this pass.
+            await promoteSchedules(s, at);
+            const lanes = await s.listRunnableQueues(at);
+            for (const lane of lanes){
+                const cap = laneConcurrency(lane) - await s.countRunning(lane, at);
+                if (cap <= 0) continue;
+                // Clamp to available tokens; consume only for rows actually claimed
+                // (claimDue may return fewer than the grant).
+                const grant = Math.min(cap, availableTokens(lane, at));
+                if (grant <= 0) continue;
+                const rows = await s.claimDue(lane, grant, bootID, LEASE_MS, at);
+                consumeTokens(lane, rows.length);
+                for (const row of rows)track(run(row));
+            }
+        } catch (cause) {
+            logger.error('workflow tick failed', {
+                error: cause
+            });
+        }
+    }
+    // Coalesced early wake: an enqueue makes the scheduler run soon rather than
+    // waiting for the next interval. It only triggers a tick — it never drives a
+    // specific instance, so `claimDue`'s priority/run_after ordering is preserved.
+    let tickScheduled = false;
+    function scheduleTick() {
+        if (tickScheduled) return;
+        tickScheduled = true;
+        queueMicrotask(()=>{
+            tickScheduled = false;
+            track(tick());
+        });
+    }
+    const tickMs = deps.tickMs ?? DEFAULT_TICK_MS;
+    let interval = setInterval(()=>{
+        void tick();
+    }, tickMs);
+    // Allow the process to exit even while the scheduler interval is pending.
+    const intervalHandle = interval;
+    if (typeof intervalHandle?.unref === 'function') intervalHandle.unref();
+    const api = {
+        register (def) {
+            const erased = def;
+            const existing = registry.get(def.name);
+            if (existing != null) {
+                if (existing !== erased) {
+                    logger.warn('workflow "{name}" registered with different definition, ignoring', {
+                        name: def.name
+                    });
+                }
+                return;
+            }
+            registry.set(def.name, erased);
+        },
+        defineQueue,
+        async schedule (name, params, when) {
+            const s = await store();
+            const everyMs = parseEvery(when.every);
+            const id = crypto.randomUUID();
+            const at = now();
+            // First fire one interval out: a restart storm must not refire everything
+            // that was ever scheduled.
+            await s.insertSchedule({
+                id,
+                workflowName: name,
+                params,
+                cron: null,
+                every: when.every,
+                nextRun: at + everyMs,
+                enabled: true
+            }, at);
+            const handle = {
+                id,
+                async disable () {
+                    await (await store()).setScheduleEnabled(id, false, now());
+                },
+                async enable () {
+                    // Re-arm one interval out from re-enable so a long-disabled schedule
+                    // does not immediately fire every missed interval at once.
+                    const s2 = await store();
+                    const reAt = now();
+                    await s2.advanceSchedule(id, reAt + everyMs, reAt);
+                    await s2.setScheduleEnabled(id, true, reAt);
+                },
+                async cancel () {
+                    // No store delete today: permanent disable is the cancel semantics.
+                    await (await store()).setScheduleEnabled(id, false, now());
+                }
+            };
+            return handle;
+        },
+        async enqueue (name, params, opts) {
+            const def = registry.get(name);
+            if (def == null) {
+                throw new Error(`Workflow "${name}" is not registered`);
+            }
+            const s = await store();
+            const instanceID = crypto.randomUUID();
+            const createdAt = now();
+            const initialAction = params !== undefined ? {
+                name: def.initialAction.name,
+                params
+            } : def.initialAction;
+            const input = {
+                instanceID,
+                name,
+                queue: opts?.queue ?? def.queue ?? name,
+                idempotencyKey: opts?.idempotencyKey ?? null,
+                singletonKey: opts?.singletonKey ?? null,
+                priority: opts?.priority ?? 0,
+                state: {},
+                nextAction: initialAction,
+                runAfter: createdAt,
+                createdAt
+            };
+            let result;
+            try {
+                result = await s.insertInstance(input);
+            } catch (cause) {
+                // A concurrent insert may lose the singleton race and surface the
+                // partial-unique constraint as a thrown error. Treat it as "singleton
+                // already active": return the existing active instance rather than throw.
+                if (opts?.singletonKey != null) {
+                    const active = (await s.list({
+                        name
+                    })).find((r)=>r.singleton_key === opts.singletonKey && (r.status === 'pending' || r.status === 'running'));
+                    if (active != null) return {
+                        instanceID: active.instance_id
+                    };
+                }
+                throw cause;
+            }
+            // Idempotent or singleton hit: return the existing instance, drive nothing.
+            if (!result.created) {
+                return {
+                    instanceID: result.row.instance_id
+                };
+            }
+            // Wake the scheduler early; it claims by priority/run_after order.
+            scheduleTick();
+            return {
+                instanceID
+            };
+        },
+        async cancel (instanceID) {
+            const controller = running.get(instanceID);
+            if (controller != null) {
+                // The running drive observes `aborted` and finalises `cancelled`.
+                controller.abort();
+                return;
+            }
+            const s = await store();
+            const row = await s.get(instanceID);
+            if (row == null || TERMINAL.has(row.status)) return;
+            await s.finish(instanceID, {
+                status: 'cancelled',
+                state: row.state
+            }, now());
+            const def = registry.get(row.name);
+            if (def != null) fireTerminal(def, instanceID, 'cancelled');
+            else events.fire('cancelled', {
+                instanceID,
+                name: row.name
+            });
+        },
+        async get (instanceID) {
+            const s = await store();
+            const row = await s.get(instanceID);
+            return row != null ? toStatus(row) : null;
+        },
+        async list (filter) {
+            const s = await store();
+            const rows = await s.list(filter);
+            return rows.map(toStatus);
+        },
+        events
+    };
+    return {
+        api,
+        async recover () {
+            // Stranded rows are claimable by `claimDue`, so a single tick reclaims and
+            // resumes them. The returned ids are the pre-tick stranded set.
+            const s = await store();
+            const stranded = await s.listRecoverable(now());
+            await tick();
+            return stranded.map((r)=>r.instance_id);
+        },
+        tick,
+        dispose () {
+            if (interval != null) {
+                clearInterval(interval);
+                interval = null;
+            }
+            for (const controller of running.values())controller.abort();
+            running.clear();
+        }
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+export type WorkflowPluginOptions = Record<string, never>;
+export declare function createWorkflowPlugin(_options?: WorkflowPluginOptions): (params: PluginFactoryParams) => KubunPlugin;
+export type { RetryPolicy, TerminalInfo, TerminalStatus, WorkflowDefinition, } from './definition.js';
+export { defineWorkflow } from './definition.js';
+export type { WorkflowEngine, WorkflowEngineDeps } from './engine.js';
+export { createWorkflowEngine, parseEvery } from './engine.js';
+export type { WorkflowContext, WorkflowEventResult } from './schema.js';
+export { createWorkflowContextFactory, createWorkflowSchemaExtension, subscribeToWorkflowEvents, } from './schema.js';
+export type { EnqueueOptions, InstanceHandle, InstanceStatus, ListFilter, QueueOptions, ScheduleHandle, ScheduleSpec, WorkflowAPI, WorkflowEvents, } from './types.js';

package/lib/index.js

@@ -0,0 +1,30 @@
+import { getWorkflowStore, workflowStoreDefinition } from '@kubun/store-workflow';
+import { createWorkflowEngine } from './engine.js';
+import { createWorkflowContextFactory, createWorkflowSchemaExtension } from './schema.js';
+export function createWorkflowPlugin(_options = {}) {
+    return (params)=>{
+        params.db.register(workflowStoreDefinition);
+        const logger = params.getLogger('workflow');
+        const engine = createWorkflowEngine({
+            getStore: ()=>getWorkflowStore(params.db),
+            logger,
+            getRandomID: ()=>params.runtime.getRandomID()
+        });
+        // No scheduler in Phase 1: re-drive stranded instances once on boot.
+        void engine.recover().catch((error)=>{
+            logger.error('workflow recovery failed', {
+                error
+            });
+        });
+        return {
+            name: 'workflow',
+            api: engine.api,
+            schemaExtension: ()=>createWorkflowSchemaExtension(),
+            createContextFactory: ()=>createWorkflowContextFactory(engine.api),
+            dispose: ()=>engine.dispose()
+        };
+    };
+}
+export { defineWorkflow } from './definition.js';
+export { createWorkflowEngine, parseEvery } from './engine.js';
+export { createWorkflowContextFactory, createWorkflowSchemaExtension, subscribeToWorkflowEvents } from './schema.js';

package/lib/schema.d.ts

@@ -0,0 +1,41 @@
+import type { ContextFactory, SchemaExtension } from '@kubun/engine';
+import type { EventsSource } from '@sozai/event';
+import type { InstanceStatus, ListFilter, WorkflowAPI, WorkflowEvents } from './types.js';
+export type WorkflowEventResult = {
+    type: keyof WorkflowEvents;
+    instanceID: string;
+    name: string;
+};
+/**
+ * Subscribe to a workflow's lifecycle events, yielding GraphQL result shapes.
+ *
+ * Implemented as a manual async iterator rather than an `async function*` so a
+ * consumer's `return()` removes all listeners immediately. A `for await` wrapper
+ * would queue the `return()` behind a parked `next()` between events, leaking the
+ * listeners until the next event — for an idle subscription, potentially never.
+ *
+ * `fromEmitter` (the connector template) handles a single event name over an
+ * `EventEmitter`; `WorkflowEvents` has five keys and the API exposes only the
+ * listen-only `EventsSource`, so the fan-in is done by hand over `on`.
+ */
+export declare function subscribeToWorkflowEvents(events: EventsSource<WorkflowEvents>, instanceID?: string | null): AsyncIterableIterator<WorkflowEventResult>;
+/**
+ * Per-request context for the workflow query/subscription fields. Reads are
+ * process-level (not transaction-bound), so the factory closes over a single
+ * long-lived API rather than rebuilding one per request.
+ *
+ * Lands on the GraphQL resolver context under `ctx.workflow` via the
+ * `declare module '@kubun/graphql'` augmentation below.
+ */
+export type WorkflowContext = {
+    get(instanceID: string): Promise<InstanceStatus | null>;
+    list(filter: ListFilter): Promise<Array<InstanceStatus>>;
+    subscribeToWorkflowEvents(instanceID?: string | null): AsyncIterableIterator<WorkflowEventResult>;
+};
+declare module '@kubun/graphql' {
+    interface PluginContextMap {
+        workflow: WorkflowContext;
+    }
+}
+export declare function createWorkflowContextFactory(api: WorkflowAPI): ContextFactory;
+export declare function createWorkflowSchemaExtension(): SchemaExtension;

package/lib/schema.js

@@ -0,0 +1,156 @@
+// Every lifecycle key. The source must listen to all of them and tag each event
+// with its `type`, since one subscription surfaces the whole lifecycle.
+const EVENT_TYPES = [
+    'started',
+    'checkpoint',
+    'failed',
+    'completed',
+    'cancelled'
+];
+/**
+ * Subscribe to a workflow's lifecycle events, yielding GraphQL result shapes.
+ *
+ * Implemented as a manual async iterator rather than an `async function*` so a
+ * consumer's `return()` removes all listeners immediately. A `for await` wrapper
+ * would queue the `return()` behind a parked `next()` between events, leaking the
+ * listeners until the next event — for an idle subscription, potentially never.
+ *
+ * `fromEmitter` (the connector template) handles a single event name over an
+ * `EventEmitter`; `WorkflowEvents` has five keys and the API exposes only the
+ * listen-only `EventsSource`, so the fan-in is done by hand over `on`.
+ */ export function subscribeToWorkflowEvents(events, instanceID) {
+    const filter = instanceID != null ? (data)=>data.instanceID === instanceID : undefined;
+    let isDone = false;
+    const queue = [];
+    const pending = [];
+    const unsubscribes = EVENT_TYPES.map((type)=>events.on(type, (data)=>{
+            const result = {
+                type,
+                instanceID: data.instanceID,
+                name: data.name
+            };
+            const waiter = pending.shift();
+            if (waiter == null) {
+                queue.push(result);
+            } else {
+                waiter({
+                    value: result,
+                    done: false
+                });
+            }
+        }, {
+            filter
+        }));
+    const stop = ()=>{
+        if (isDone) return;
+        isDone = true;
+        for (const off of unsubscribes)off();
+        // Settle every parked reader so a return() before the first event does not
+        // leave a next() hanging.
+        while(pending.length > 0){
+            pending.shift()?.({
+                done: true,
+                value: undefined
+            });
+        }
+    };
+    return {
+        [Symbol.asyncIterator] () {
+            return this;
+        },
+        next () {
+            if (isDone) {
+                return Promise.resolve({
+                    done: true,
+                    value: undefined
+                });
+            }
+            const queued = queue.shift();
+            if (queued != null) {
+                return Promise.resolve({
+                    value: queued,
+                    done: false
+                });
+            }
+            return new Promise((resolve)=>{
+                pending.push(resolve);
+            });
+        },
+        return () {
+            stop();
+            return Promise.resolve({
+                done: true,
+                value: undefined
+            });
+        },
+        throw (reason) {
+            stop();
+            return Promise.reject(reason);
+        }
+    };
+}
+function requireWorkflow(ctx) {
+    if (ctx.workflow == null) {
+        throw new Error('workflow plugin is not wired into this context');
+    }
+    return ctx.workflow;
+}
+export function createWorkflowContextFactory(api) {
+    return ()=>({
+            get: (instanceID)=>api.get(instanceID),
+            list: (filter)=>api.list(filter),
+            subscribeToWorkflowEvents: (instanceID)=>subscribeToWorkflowEvents(api.events, instanceID)
+        });
+}
+// ms-epoch timestamps are exposed as `Float` (JS number), matching how the
+// connector exposes numeric time (`ConnectorSyncEvent.duration`). `Int` would
+// overflow GraphQL's 32-bit range for a millisecond epoch. `state`/`next_action`
+// have no field here — the projection cannot leak them.
+const SDL = `
+type WorkflowInstanceStatus {
+  instanceID: ID!
+  name: String!
+  queue: String!
+  status: String!
+  attempts: Int!
+  lastError: String
+  createdAt: Float!
+  updatedAt: Float!
+}
+
+type WorkflowEvent {
+  type: String!
+  instanceID: ID!
+  name: String!
+}
+
+extend type Query {
+  workflowInstance(instanceID: ID!): WorkflowInstanceStatus
+  workflowInstances(name: String, queue: String, status: String): [WorkflowInstanceStatus!]!
+}
+
+extend type Subscription {
+  workflowEvents(instanceID: ID): WorkflowEvent!
+}
+`;
+export function createWorkflowSchemaExtension() {
+    return {
+        sdl: SDL,
+        resolvers: {
+            queryFields: {
+                workflowInstance: (_source, args, context)=>requireWorkflow(context).get(args.instanceID),
+                workflowInstances: (_source, args, context)=>requireWorkflow(context).list({
+                        name: args.name,
+                        queue: args.queue,
+                        status: args.status
+                    })
+            },
+            subscriptionFields: {
+                workflowEvents: {
+                    resolve: (event)=>event,
+                    subscribe: (_source, args, context)=>requireWorkflow(context).subscribeToWorkflowEvents(args.instanceID)
+                }
+            }
+        }
+    };
+}

package/lib/types.d.ts

@@ -0,0 +1,73 @@
+import type { WorkflowStatus } from '@kubun/store-workflow';
+import type { EventsSource } from '@sozai/event';
+import type { HandlersRecord } from '@sozai/flow';
+import type { WorkflowDefinition } from './definition.js';
+export type WorkflowEvents = {
+    started: {
+        instanceID: string;
+        name: string;
+    };
+    checkpoint: {
+        instanceID: string;
+        name: string;
+    };
+    failed: {
+        instanceID: string;
+        name: string;
+    };
+    completed: {
+        instanceID: string;
+        name: string;
+    };
+    cancelled: {
+        instanceID: string;
+        name: string;
+    };
+};
+export type InstanceStatus = {
+    instanceID: string;
+    name: string;
+    queue: string;
+    status: WorkflowStatus;
+    attempts: number;
+    lastError: string | null;
+    createdAt: number;
+    updatedAt: number;
+};
+export type InstanceHandle = {
+    instanceID: string;
+};
+export type EnqueueOptions = {
+    queue?: string;
+    priority?: number;
+    idempotencyKey?: string;
+    singletonKey?: string;
+};
+export type ListFilter = {
+    name?: string;
+    queue?: string;
+    status?: WorkflowStatus;
+};
+export type QueueOptions = {
+    concurrency: number;
+    ratePerMinute?: number;
+};
+export type ScheduleSpec = {
+    every: string;
+};
+export type ScheduleHandle = {
+    id: string;
+    disable(): Promise<void>;
+    enable(): Promise<void>;
+    cancel(): Promise<void>;
+};
+export type WorkflowAPI = {
+    register<State extends Record<string, unknown>, Handlers extends HandlersRecord<State> = HandlersRecord<State>>(def: WorkflowDefinition<State, Handlers>): void;
+    defineQueue(name: string, opts: QueueOptions): void;
+    enqueue(name: string, params?: unknown, opts?: EnqueueOptions): Promise<InstanceHandle>;
+    schedule(name: string, params: unknown, when: ScheduleSpec): Promise<ScheduleHandle>;
+    cancel(instanceID: string): Promise<void>;
+    get(instanceID: string): Promise<InstanceStatus | null>;
+    list(filter?: ListFilter): Promise<Array<InstanceStatus>>;
+    events: EventsSource<WorkflowEvents>;
+};

package/lib/types.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kubun/plugin-workflow",
+  "version": "0.13.0",
+  "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "dependencies": {
+    "@sozai/event": "^0.1.3",
+    "@sozai/flow": "^0.3.0",
+    "@sozai/runtime": "^0.1.0",
+    "@sozai/schema": "^0.1.1",
+    "@kubun/engine": "^0.13.0",
+    "@kubun/logger": "^0.13.0",
+    "@kubun/store-workflow": "^0.13.0",
+    "@kubun/graphql": "^0.13.0",
+    "@kubun/db": "^0.13.0"
+  },
+  "devDependencies": {
+    "@testcontainers/postgresql": "^12.1.0",
+    "@kubun/db-postgres": "^0.13.0",
+    "@kubun/db-better-sqlite": "^0.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
+}