@kubun/plugin-workflow 0.17.0 → 0.17.1

package/lib/control-plane.js

@@ -44,8 +44,17 @@ export function createWorkflowControlPlaneHelpers(getP2P) {
         discoverWorkflows: async (groupID, options)=>(await getP2P()).discoverWorkflows(groupID, options),
         listWorkflows: async (groupID, targetDID)=>(await getP2P()).listWorkflows(groupID, targetDID),
         workflowStatus: async (groupID, targetDID, instanceID)=>(await getP2P()).workflowStatus(groupID, targetDID, instanceID),
-        enqueueWorkflow: async (groupID, targetDID, name, params, opts)=>unwrap(await (await getP2P()).enqueueWorkflow(groupID, targetDID, name, params, opts)),
-        cancelWorkflow: async (groupID, targetDID, instanceID)=>unwrap(await (await getP2P()).cancelWorkflow(groupID, targetDID, instanceID)),
-        retryWorkflow: async (groupID, targetDID, instanceID)=>unwrap(await (await getP2P()).retryWorkflow(groupID, targetDID, instanceID))
+        enqueueWorkflow: async (groupID, targetDID, name, params, opts)=>{
+            const p2p = await getP2P();
+            return unwrap(await p2p.enqueueWorkflow(groupID, targetDID, name, params, opts));
+        },
+        cancelWorkflow: async (groupID, targetDID, instanceID)=>{
+            const p2p = await getP2P();
+            return unwrap(await p2p.cancelWorkflow(groupID, targetDID, instanceID));
+        },
+        retryWorkflow: async (groupID, targetDID, instanceID)=>{
+            const p2p = await getP2P();
+            return unwrap(await p2p.retryWorkflow(groupID, targetDID, instanceID));
+        }
     };
 }

package/lib/engine.d.ts

@@ -2,6 +2,7 @@ import type { Logger } from '@kubun/logger';
 import type { RetryPolicy, RetryRefusalReason, WorkflowAPI } from '@kubun/plugin-workflow-api';
 import type { WorkflowStoreAPI } from '@kubun/store-workflow';
 import type { GetRandomID } from '@sozai/runtime';
+import { type ResolvedFinishedInstanceCleanup } from './instance-cleanup.js';
 export declare function backoff(attempts: number, policy?: RetryPolicy): number;
 export declare function parseEvery(spec: string): number;
 export declare class WorkflowRetryError extends Error {
@@ -15,15 +16,18 @@ export type WorkflowEngineDeps = {
     getStore: () => Promise<WorkflowStoreAPI>;
     logger: Logger;
     now?: () => number;
-    getRandomID?: GetRandomID;
+    getRandomID: GetRandomID;
     tickMs?: number;
     disposeTimeoutMs?: number;
     ready?: () => Promise<void>;
+    finishedInstanceCleanup?: ResolvedFinishedInstanceCleanup | null;
+    cleanupBatchSize?: number;
 };
 export type WorkflowEngine = {
     api: WorkflowAPI;
     recover(): Promise<Array<string>>;
     tick(): Promise<void>;
+    cleanupFinished(): Promise<number>;
     dispose(): Promise<void>;
 };
 export declare function createWorkflowEngine(deps: WorkflowEngineDeps): WorkflowEngine;

package/lib/engine.js

@@ -1,6 +1,8 @@
+import { getWorkflowStore } from '@kubun/store-workflow';
 import { EventEmitter } from '@sozai/event';
 import { createFlow } from '@sozai/flow';
 import { computeNextDelay, validateAdaptivePolicy } from './adaptive.js';
+import { FINISHED_INSTANCE_CLEANUP_BATCH_SIZE } from './instance-cleanup.js';
 // One runner may hold an instance's lease for this long before another boot may
 // reclaim it as stranded.
 const LEASE_MS = 30_000;
@@ -62,7 +64,8 @@ function toStatus(row) {
     };
 }
 // The active (pending/running) instance for (name, singletonKey) if one exists,
-// else the most recent terminal by updated_at, else null. Instances are promoted
+// else the most recent terminal by updated_at (a tie goes to the highest
+// instance_id, as the finished-instance cleanup keeps), else null. Instances are promoted
 // with singleton_key = subject, so the subject keys the lookup.
 async function currentInstanceRow(s, name, singletonKey) {
     const rows = await s.list({
@@ -70,7 +73,7 @@ async function currentInstanceRow(s, name, singletonKey) {
     });
     const forSubject = rows.filter((r)=>r.singleton_key === singletonKey);
     const active = forSubject.find((r)=>r.status === 'pending' || r.status === 'running');
-    return active ?? forSubject.reduce((best, r)=>best == null || r.updated_at > best.updated_at ? r : best, null);
+    return active ?? forSubject.reduce((best, r)=>best == null || r.updated_at > best.updated_at || r.updated_at === best.updated_at && r.instance_id > best.instance_id ? r : best, null);
 }
 // Project an adaptive schedule row as a PeriodicSync. `currentStatus` is the
 // schedule subject's current instance (see `currentInstanceRow`), null if never
@@ -97,7 +100,7 @@ export function createWorkflowEngine(deps) {
     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()))();
+    const bootID = deps.getRandomID();
     // Instances currently being driven in THIS process, so `cancel` can signal the
     // running flow via its AbortController.
     const running = new Map();
@@ -280,6 +283,58 @@ export function createWorkflowEngine(deps) {
             running.delete(instanceID);
         }
     }
+    // --- Finished-instance retention cleanup ---
+    const cleanup = deps.finishedInstanceCleanup ?? null;
+    const cleanupBatchSize = deps.cleanupBatchSize ?? FINISHED_INSTANCE_CLEANUP_BATCH_SIZE;
+    // Due immediately: the first scheduler pass after `ready` runs it.
+    let nextCleanupAt = Number.NEGATIVE_INFINITY;
+    let cleanupRun = null;
+    // One batch per statement until a short batch, or until dispose(). Errors are
+    // logged, never thrown: the next interval retries.
+    async function collectFinished(retentionMs) {
+        let total = 0;
+        try {
+            const s = await store();
+            const before = now() - retentionMs;
+            while(!disposed){
+                const removed = await s.purgeFinished({
+                    before,
+                    limit: cleanupBatchSize
+                });
+                total += removed;
+                if (removed < cleanupBatchSize) break;
+            }
+            if (total > 0) {
+                logger.debug('workflow cleanup removed {count} finished instances', {
+                    count: total
+                });
+            }
+        } catch (cause) {
+            logger.warn('workflow finished-instance cleanup failed', {
+                error: cause
+            });
+        }
+        return total;
+    }
+    function cleanupFinished() {
+        if (cleanup == null || disposed) return Promise.resolve(0);
+        if (cleanupRun == null) {
+            const run = collectFinished(cleanup.retentionMs).finally(()=>{
+                cleanupRun = null;
+            });
+            cleanupRun = run;
+            // Tracked so dispose() drains a run in progress before the store closes.
+            track(run.then(()=>{}));
+        }
+        return cleanupRun;
+    }
+    // Called from each scheduler pass; starts a run once the interval is due. The
+    // pass does not wait for it, so a long cleanup never delays claims.
+    function maybeCleanup(at) {
+        if (cleanup == null || cleanupRun != null || at < nextCleanupAt) return;
+        nextCleanupAt = at + cleanup.intervalMs;
+        void cleanupFinished();
+    }
     // Per-lane concurrency. Defaults to 1; `defineQueue` raises a lane's cap.
     const concurrency = new Map();
     function laneConcurrency(lane) {
@@ -379,6 +434,7 @@ export function createWorkflowEngine(deps) {
             // in-flight when dispose() fired from claiming fresh work after shutdown began.
             if (disposed) return;
             const at = now();
+            maybeCleanup(at);
             // Promote due schedules first so their instances are claimable this pass.
             await promoteSchedules(s, at);
             if (disposed) return;
@@ -470,7 +526,7 @@ export function createWorkflowEngine(deps) {
         async schedule (name, params, when) {
             const s = await store();
             const everyMs = parseEvery(when.every);
-            const id = crypto.randomUUID();
+            const id = deps.getRandomID();
             const at = now();
             // First fire one interval out: a restart storm must not refire everything
             // that was ever scheduled.
@@ -486,7 +542,8 @@ export function createWorkflowEngine(deps) {
             const handle = {
                 id,
                 async disable () {
-                    await (await store()).setScheduleEnabled(id, false, now());
+                    const s2 = await store();
+                    await s2.setScheduleEnabled(id, false, now());
                 },
                 async enable () {
                     // Re-arm one interval out from re-enable so a long-disabled schedule
@@ -498,7 +555,8 @@ export function createWorkflowEngine(deps) {
                 },
                 async cancel () {
                     // No store delete today: permanent disable is the cancel semantics.
-                    await (await store()).setScheduleEnabled(id, false, now());
+                    const s2 = await store();
+                    await s2.setScheduleEnabled(id, false, now());
                 }
             };
             return handle;
@@ -525,7 +583,8 @@ export function createWorkflowEngine(deps) {
             const handle = {
                 id,
                 async disable () {
-                    await (await store()).setScheduleEnabled(id, false, now());
+                    const s2 = await store();
+                    await s2.setScheduleEnabled(id, false, now());
                 },
                 async enable () {
                     // Re-arm eagerly (now + changed), mirroring reactivation above.
@@ -540,7 +599,8 @@ export function createWorkflowEngine(deps) {
                     await s2.setScheduleEnabled(id, true, reAt);
                 },
                 async cancel () {
-                    await (await store()).setScheduleEnabled(id, false, now());
+                    const s2 = await store();
+                    await s2.setScheduleEnabled(id, false, now());
                 }
             };
             return handle;
@@ -551,7 +611,7 @@ export function createWorkflowEngine(deps) {
                 throw new Error(`Workflow "${name}" is not registered`);
             }
             const s = await store();
-            const instanceID = crypto.randomUUID();
+            const instanceID = deps.getRandomID();
             const createdAt = now();
             const initialAction = params !== undefined ? {
                 name: def.initialAction.name,
@@ -585,6 +645,53 @@ export function createWorkflowEngine(deps) {
                 instanceID
             };
         },
+        async enqueueTx (stores, name, params, opts) {
+            const def = registry.get(name);
+            if (def == null) {
+                throw new Error(`Workflow "${name}" is not registered`);
+            }
+            // Resolve the store from the CALLER's request-scoped provider, not the
+            // top-level `store()` — when `stores` is a tx-scoped StoreProvider
+            // (e.g. from `db.withTransaction`), this binds the returned store to
+            // that already-open transaction.
+            const s = await getWorkflowStore(stores);
+            const instanceID = deps.getRandomID();
+            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
+            };
+            // insertInstanceTx runs directly on the tx-bound store — no nested
+            // transaction — inheriting atomicity from the caller's own transaction.
+            const result = await s.insertInstanceTx(input);
+            // Idempotent or singleton hit: return the existing instance, drive nothing.
+            if (!result.created) {
+                return {
+                    instanceID: result.row.instance_id
+                };
+            }
+            // Defer the wake until AFTER the caller's transaction commits: `stores`
+            // IS that transaction here, so an inline scheduleTick() (as `enqueue`
+            // does above) could wake the scheduler to claim a row whose insert has
+            // not committed yet. onCommit fires post-commit, or never if the
+            // transaction rolls back.
+            stores.onCommit(()=>scheduleTick());
+            return {
+                instanceID
+            };
+        },
         async cancel (instanceID) {
             const controller = running.get(instanceID);
             if (controller != null) {
@@ -720,6 +827,7 @@ export function createWorkflowEngine(deps) {
             track(p);
             return p;
         },
+        cleanupFinished,
         async dispose () {
             disposed = true;
             if (interval != null) {

package/lib/index.d.ts

@@ -1,10 +1,30 @@
 import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
-export type WorkflowPluginOptions = Record<string, never>;
-export declare function createWorkflowPlugin(_options?: WorkflowPluginOptions): (params: PluginFactoryParams) => KubunPlugin;
+import { type FinishedInstanceCleanupOptions } from './instance-cleanup.js';
+export type WorkflowPluginOptions = {
+    /**
+     * Retention cleanup of finished workflow instances. Every run of a workflow,
+     * scheduled ones included, leaves an instance row; once it has been finished
+     * (completed, failed or cancelled) for `retentionMs`, the cleanup deletes it.
+     * Defaults: runs every 6 hours, keeps 30 days. Omit it for the defaults,
+     * pass an object to change either value, or `false` to keep every instance.
+     *
+     * It never deletes a pending or running instance, nor the newest instance of
+     * a periodic sync's subject, which is what its status and
+     * `getCurrentInstance` report. A deleted instance is unknown to `get`, cannot be retried,
+     * and no longer holds its idempotency key: an enqueue reusing that key
+     * creates a new instance.
+     *
+     * Each value must be a positive finite number, or the plugin throws when it
+     * is created.
+     */
+    finishedInstanceCleanup?: FinishedInstanceCleanupOptions;
+};
+export declare function createWorkflowPlugin(options?: WorkflowPluginOptions): (params: PluginFactoryParams) => KubunPlugin;
 export { computeNextDelay, validateAdaptivePolicy } from './adaptive.js';
 export { createWorkflowControlPlaneHelpers, WorkflowCommandRefusedError, type WorkflowControlPlaneHelpers, } from './control-plane.js';
 export { defineWorkflow, isRemotelyCommandable, isRemotelyObservable } from './definition.js';
 export type { WorkflowEngine, WorkflowEngineDeps } from './engine.js';
 export { createWorkflowEngine, parseEvery, WorkflowRetryError } from './engine.js';
+export { DEFAULT_FINISHED_INSTANCE_CLEANUP_INTERVAL_MS, DEFAULT_FINISHED_INSTANCE_RETENTION_MS, FINISHED_INSTANCE_CLEANUP_BATCH_SIZE, type FinishedInstanceCleanupOptions, type ResolvedFinishedInstanceCleanup, resolveFinishedInstanceCleanup, } from './instance-cleanup.js';
 export type { WorkflowContext, WorkflowEventResult } from './schema.js';
 export { createWorkflowContextFactory, createWorkflowSchemaExtension, subscribeToWorkflowEvents, } from './schema.js';

package/lib/index.js

@@ -1,8 +1,11 @@
 import { getWorkflowStore, workflowStoreDefinition } from '@kubun/store-workflow';
 import { createWorkflowControlPlaneHelpers } from './control-plane.js';
 import { createWorkflowEngine } from './engine.js';
+import { resolveFinishedInstanceCleanup } from './instance-cleanup.js';
 import { createWorkflowContextFactory, createWorkflowSchemaExtension } from './schema.js';
-export function createWorkflowPlugin(_options = {}) {
+export function createWorkflowPlugin(options = {}) {
+    // Validated here, so a bad value fails when the plugin is created.
+    const cleanupSettings = resolveFinishedInstanceCleanup(options.finishedInstanceCleanup);
     return (params)=>{
         params.db.register(workflowStoreDefinition);
         const logger = params.getLogger('workflow');
@@ -14,7 +17,8 @@ export function createWorkflowPlugin(_options = {}) {
             // the interval claim no work until `ready()` resolves, and an identity
             // mismatch leaves the engine inert rather than driving jobs on a database it
             // was rejected from.
-            ready: ()=>params.engine.ready()
+            ready: ()=>params.engine.ready(),
+            finishedInstanceCleanup: cleanupSettings
         });
         // Re-drive stranded instances once on boot, but only after the host engine
         // verifies its database identity — a re-driven instance mints under the engine's
@@ -44,4 +48,5 @@ export { computeNextDelay, validateAdaptivePolicy } from './adaptive.js';
 export { createWorkflowControlPlaneHelpers, WorkflowCommandRefusedError } from './control-plane.js';
 export { defineWorkflow, isRemotelyCommandable, isRemotelyObservable } from './definition.js';
 export { createWorkflowEngine, parseEvery, WorkflowRetryError } from './engine.js';
+export { DEFAULT_FINISHED_INSTANCE_CLEANUP_INTERVAL_MS, DEFAULT_FINISHED_INSTANCE_RETENTION_MS, FINISHED_INSTANCE_CLEANUP_BATCH_SIZE, resolveFinishedInstanceCleanup } from './instance-cleanup.js';
 export { createWorkflowContextFactory, createWorkflowSchemaExtension, subscribeToWorkflowEvents } from './schema.js';

package/lib/instance-cleanup.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Retention cleanup of finished workflow instances (completed, failed or
+ * cancelled). `false` turns it off; an object (or the option left out) turns
+ * it on, each value defaulting when absent.
+ */
+export type FinishedInstanceCleanupOptions = false | {
+    /** How often the cleanup runs, in milliseconds. Default 6 hours. */
+    intervalMs?: number;
+    /** How long a finished instance is kept, in milliseconds. Default 30 days. */
+    retentionMs?: number;
+};
+export declare const DEFAULT_FINISHED_INSTANCE_CLEANUP_INTERVAL_MS: number;
+export declare const DEFAULT_FINISHED_INSTANCE_RETENTION_MS: number;
+/** The most rows one cleanup statement deletes. */
+export declare const FINISHED_INSTANCE_CLEANUP_BATCH_SIZE = 500;
+export type ResolvedFinishedInstanceCleanup = {
+    intervalMs: number;
+    retentionMs: number;
+};
+/**
+ * The cleanup settings `options` describe, or null when cleanup is off.
+ * Throws on a value that is not a positive whole number of milliseconds.
+ */
+export declare function resolveFinishedInstanceCleanup(options: FinishedInstanceCleanupOptions | undefined): ResolvedFinishedInstanceCleanup | null;

package/lib/instance-cleanup.js

@@ -0,0 +1,28 @@
+/**
+ * Retention cleanup of finished workflow instances (completed, failed or
+ * cancelled). `false` turns it off; an object (or the option left out) turns
+ * it on, each value defaulting when absent.
+ */ export const DEFAULT_FINISHED_INSTANCE_CLEANUP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+export const DEFAULT_FINISHED_INSTANCE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** The most rows one cleanup statement deletes. */ export const FINISHED_INSTANCE_CLEANUP_BATCH_SIZE = 500;
+function assertDuration(value, label) {
+    // Whole milliseconds only: the cutoff is compared with integer timestamp
+    // columns, which Postgres will not compare with a fractional parameter.
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`finishedInstanceCleanup.${label} must be a positive whole number of milliseconds`);
+    }
+    return value;
+}
+/**
+ * The cleanup settings `options` describe, or null when cleanup is off.
+ * Throws on a value that is not a positive whole number of milliseconds.
+ */ export function resolveFinishedInstanceCleanup(options) {
+    if (options === false) return null;
+    if (options != null && (typeof options !== 'object' || Array.isArray(options))) {
+        throw new Error('finishedInstanceCleanup must be false or an object');
+    }
+    return {
+        intervalMs: assertDuration(options?.intervalMs ?? DEFAULT_FINISHED_INSTANCE_CLEANUP_INTERVAL_MS, 'intervalMs'),
+        retentionMs: assertDuration(options?.retentionMs ?? DEFAULT_FINISHED_INSTANCE_RETENTION_MS, 'retentionMs')
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/plugin-workflow",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -16,13 +16,13 @@
   ],
   "dependencies": {
     "@kubun/db": "^0.17.0",
-    "@kubun/engine": "^0.17.0",
-    "@kubun/graphql": "^0.17.0",
+    "@kubun/engine": "^0.17.2",
+    "@kubun/graphql": "^0.17.2",
     "@kubun/id": "^0.17.0",
     "@kubun/logger": "^0.17.0",
     "@kubun/plugin-p2p-api": "^0.17.0",
-    "@kubun/plugin-workflow-api": "^0.17.0",
-    "@kubun/store-workflow": "^0.17.0",
+    "@kubun/plugin-workflow-api": "^0.17.1",
+    "@kubun/store-workflow": "^0.17.1",
     "@sozai/event": "^0.1.3",
     "@sozai/flow": "^0.3.1",
     "@sozai/runtime": "^0.1.0",
@@ -30,7 +30,7 @@
   },
   "devDependencies": {
     "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/db-postgres": "^0.17.0",
+    "@kubun/db-postgres": "^0.17.1",
     "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {