@kubun/plugin-workflow 0.13.0 → 0.14.0

package/lib/adaptive.d.ts

@@ -0,0 +1,9 @@
+import type { AdaptivePolicy, WorkflowOutcome } from '@kubun/plugin-workflow-api';
+export declare function validateAdaptivePolicy(policy: AdaptivePolicy): void;
+export declare function computeNextDelay(policy: AdaptivePolicy, outcome: WorkflowOutcome, streak: {
+    lastOutcome: WorkflowOutcome | null;
+    count: number;
+}): {
+    delayMs: number;
+    count: number;
+};

package/lib/adaptive.js

@@ -0,0 +1,44 @@
+// Adaptive schedule policy: the pure core that maps a recurring sync's last
+// outcome to the delay before its next run. No DB, no engine state — the store
+// persists the streak, the engine calls this to advance it. The policy types
+// are the cross-plugin contract; this module keeps only the pure math.
+const DEFAULT_BACKOFF = {
+    idle: 'fixed',
+    error: 'exponential',
+    offline: 'exponential'
+};
+function assertPositive(value, label) {
+    if (!(value > 0)) throw new Error(`adaptive policy: ${label} must be > 0, got ${value}`);
+}
+function validateBranch(branch, label) {
+    assertPositive(branch.base, `${label}.base`);
+    assertPositive(branch.max, `${label}.max`);
+    if (branch.base > branch.max) {
+        throw new Error(`adaptive policy: ${label}.base (${branch.base}) exceeds max (${branch.max})`);
+    }
+}
+export function validateAdaptivePolicy(policy) {
+    assertPositive(policy.changed, 'changed');
+    validateBranch(policy.idle, 'idle');
+    validateBranch(policy.error, 'error');
+    validateBranch(policy.offline, 'offline');
+}
+export function computeNextDelay(policy, outcome, streak) {
+    if (outcome === 'changed') {
+        return {
+            delayMs: policy.changed,
+            count: 0
+        };
+    }
+    // A different outcome class (a productive run's stored count of 0 included)
+    // starts a fresh streak at 1; same class grows it.
+    const count = streak.lastOutcome === outcome ? streak.count + 1 : 1;
+    const branch = policy[outcome];
+    const kind = branch.backoff ?? DEFAULT_BACKOFF[outcome];
+    const raw = kind === 'fixed' ? branch.base : branch.base * 2 ** (count - 1);
+    // Clamp is the runtime backstop even if validation was bypassed.
+    return {
+        delayMs: Math.min(branch.max, raw),
+        count
+    };
+}

package/lib/definition.d.ts

@@ -1,25 +1,3 @@
-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;
-};
+import type { WorkflowDefinition } from '@kubun/plugin-workflow-api';
+import type { HandlersRecord } from '@sozai/flow';
 export declare function defineWorkflow<State extends Record<string, unknown>, Handlers extends HandlersRecord<State> = HandlersRecord<State>>(def: WorkflowDefinition<State, Handlers>): WorkflowDefinition<State, Handlers>;

package/lib/engine.d.ts

@@ -1,8 +1,7 @@
 import type { Logger } from '@kubun/logger';
+import type { RetryPolicy, WorkflowAPI } from '@kubun/plugin-workflow-api';
 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 = {

package/lib/engine.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from '@sozai/event';
 import { createFlow } from '@sozai/flow';
+import { computeNextDelay, validateAdaptivePolicy } from './adaptive.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;
@@ -43,6 +44,35 @@ function toStatus(row) {
         updatedAt: row.updated_at
     };
 }
+// The active (pending/running) instance for (name, singletonKey) if one exists,
+// else the most recent terminal by updated_at, 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({
+        name
+    });
+    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);
+}
+// Project an adaptive schedule row as a PeriodicSync. `currentStatus` is the
+// schedule subject's current instance (see `currentInstanceRow`), null if never
+// run.
+async function buildPeriodicSync(s, sched) {
+    const subject = sched.id.slice(sched.workflow_name.length + 1);
+    const chosen = await currentInstanceRow(s, sched.workflow_name, subject);
+    return {
+        scheduleID: sched.id,
+        subject,
+        workflowName: sched.workflow_name,
+        enabled: sched.enabled,
+        nextRun: sched.next_run,
+        lastOutcome: sched.last_outcome,
+        consecutiveCount: sched.consecutive_count,
+        policy: sched.policy,
+        currentStatus: chosen != null ? toStatus(chosen) : null
+    };
+}
 export function createWorkflowEngine(deps) {
     const now = deps.now ?? Date.now;
     const logger = deps.logger;
@@ -65,7 +95,7 @@ export function createWorkflowEngine(deps) {
         inflight.add(promise);
         void promise.finally(()=>inflight.delete(promise));
     }
-    function fireTerminal(def, instanceID, status, error) {
+    function fireTerminal(def, instanceID, status, error, outcome) {
         events.fire(status, {
             instanceID,
             name: def.name
@@ -76,7 +106,8 @@ export function createWorkflowEngine(deps) {
                     instanceID,
                     name: def.name,
                     status,
-                    error
+                    error,
+                    outcome
                 });
             } catch (cause) {
                 logger.warn('workflow onTerminal threw', {
@@ -87,6 +118,24 @@ export function createWorkflowEngine(deps) {
             }
         }
     }
+    // Advance the adaptive schedule that owns this instance, if any. Keyed by the
+    // instance's singleton_key: an interval-promoted or one-shot run has none and
+    // is a no-op. Called only after a fenced terminal write succeeded.
+    async function advanceAdaptive(row, outcome, at) {
+        if (row.singleton_key == null) return;
+        const s = await store();
+        const sched = await s.getSchedule(`${row.name}:${row.singleton_key}`);
+        if (sched == null || sched.kind !== 'adaptive') return;
+        const { delayMs, count } = computeNextDelay(sched.policy, outcome, {
+            lastOutcome: sched.last_outcome,
+            count: sched.consecutive_count
+        });
+        await s.advanceScheduleAdaptive(sched.id, {
+            nextRun: at + delayMs,
+            lastOutcome: outcome,
+            consecutiveCount: count
+        }, at);
+    }
     // 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) {
@@ -153,7 +202,10 @@ export function createWorkflowEngine(deps) {
                         state: flow.getState()
                     }, now(), bootID);
                     if (!wrote) return;
-                    fireTerminal(def, instanceID, 'completed');
+                    // A run reports its outcome via the flow `end` value; absent = idle.
+                    const outcome = value.outcome ?? 'idle';
+                    fireTerminal(def, instanceID, 'completed', undefined, outcome);
+                    await advanceAdaptive(row, outcome, now());
                     return;
                 }
                 if (value.status === 'aborted') {
@@ -191,7 +243,8 @@ export function createWorkflowEngine(deps) {
                     status: 'failed'
                 }, now(), bootID);
                 if (!wrote) return;
-                fireTerminal(def, instanceID, 'failed', error);
+                fireTerminal(def, instanceID, 'failed', error, 'error');
+                await advanceAdaptive(row, 'error', now());
                 return;
             }
         } catch (cause) {
@@ -255,8 +308,21 @@ export function createWorkflowEngine(deps) {
         const due = await s.listDueSchedules(at);
         for (const sched of due){
             try {
+                if (sched.kind === 'adaptive') {
+                    // subjectKey may itself contain ':', so slice by the known prefix
+                    // rather than splitting.
+                    const subjectKey = sched.id.slice(sched.workflow_name.length + 1);
+                    // next_run is NOT advanced here: it stays stable until the instance
+                    // terminates, so the fire-time idempotency key blocks re-enqueue and
+                    // the singleton key interlocks any manual sync of the same subject.
+                    await api.enqueue(sched.workflow_name, sched.params, {
+                        idempotencyKey: `schedule:${sched.id}:${sched.next_run}`,
+                        singletonKey: subjectKey
+                    });
+                    continue;
+                }
                 if (sched.every == null) {
-                    // Only interval schedules exist today; a cron-only row can't be armed.
+                    // A cron-only interval row can't be armed (cron is deferred).
                     logger.warn('workflow schedule "{id}" has no interval, skipping', {
                         id: sched.id
                     });
@@ -369,6 +435,57 @@ export function createWorkflowEngine(deps) {
             };
             return handle;
         },
+        async scheduleAdaptive (name, params, opts) {
+            validateAdaptivePolicy(opts.policy);
+            const s = await store();
+            // Deterministic id so a re-arm across restarts targets the same row.
+            const id = `${name}:${opts.subjectKey}`;
+            const at = now();
+            const existing = await s.getSchedule(id);
+            if (existing == null) {
+                await s.insertSchedule({
+                    id,
+                    workflowName: name,
+                    params,
+                    cron: null,
+                    every: null,
+                    kind: 'adaptive',
+                    policy: opts.policy,
+                    nextRun: at + opts.policy.changed,
+                    enabled: true
+                }, at);
+            } else {
+                // Reactivation: re-arm eagerly, preserving the stored streak.
+                await s.advanceScheduleAdaptive(id, {
+                    nextRun: at + opts.policy.changed,
+                    lastOutcome: existing.last_outcome,
+                    consecutiveCount: existing.consecutive_count
+                }, at);
+                await s.setScheduleEnabled(id, true, at);
+            }
+            const handle = {
+                id,
+                async disable () {
+                    await (await store()).setScheduleEnabled(id, false, now());
+                },
+                async enable () {
+                    // Re-arm eagerly (now + changed), mirroring reactivation above.
+                    const s2 = await store();
+                    const reAt = now();
+                    const cur = await s2.getSchedule(id);
+                    await s2.advanceScheduleAdaptive(id, {
+                        nextRun: reAt + opts.policy.changed,
+                        lastOutcome: cur?.last_outcome ?? null,
+                        consecutiveCount: cur?.consecutive_count ?? 0
+                    }, reAt);
+                    await s2.setScheduleEnabled(id, true, reAt);
+                },
+                async cancel () {
+                    await (await store()).setScheduleEnabled(id, false, now());
+                }
+            };
+            return handle;
+        },
         async enqueue (name, params, opts) {
             const def = registry.get(name);
             if (def == null) {
@@ -453,6 +570,39 @@ export function createWorkflowEngine(deps) {
             const rows = await s.list(filter);
             return rows.map(toStatus);
         },
+        async getCurrentInstance (name, singletonKey) {
+            const s = await store();
+            const row = await currentInstanceRow(s, name, singletonKey);
+            return row != null ? toStatus(row) : null;
+        },
+        async getPeriodicSync (scheduleID) {
+            const s = await store();
+            const sched = await s.getSchedule(scheduleID);
+            if (sched == null || sched.kind !== 'adaptive') return null;
+            return buildPeriodicSync(s, sched);
+        },
+        async listPeriodicSyncs (workflowName) {
+            const s = await store();
+            const scheds = (await s.listSchedules()).filter((x)=>x.kind === 'adaptive' && (workflowName == null || x.workflow_name === workflowName));
+            return Promise.all(scheds.map((x)=>buildPeriodicSync(s, x)));
+        },
+        async setPeriodicSyncEnabled (scheduleID, enabled) {
+            const s = await store();
+            const sched = await s.getSchedule(scheduleID);
+            if (sched == null || sched.kind !== 'adaptive') return null;
+            await s.setScheduleEnabled(scheduleID, enabled, now());
+            return buildPeriodicSync(s, await s.getSchedule(scheduleID) ?? sched);
+        },
+        async setPeriodicSyncPolicy (scheduleID, policy) {
+            // Validate before touching the store: a bad policy throws loudly and
+            // nothing is written.
+            validateAdaptivePolicy(policy);
+            const s = await store();
+            const sched = await s.getSchedule(scheduleID);
+            if (sched == null || sched.kind !== 'adaptive') return null;
+            await s.setSchedulePolicy(scheduleID, policy, now());
+            return buildPeriodicSync(s, await s.getSchedule(scheduleID) ?? sched);
+        },
         events
     };
     return {

package/lib/index.d.ts

@@ -1,10 +1,9 @@
 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 { computeNextDelay, validateAdaptivePolicy } from './adaptive.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

@@ -25,6 +25,7 @@ export function createWorkflowPlugin(_options = {}) {
         };
     };
 }
+export { computeNextDelay, validateAdaptivePolicy } from './adaptive.js';
 export { defineWorkflow } from './definition.js';
 export { createWorkflowEngine, parseEvery } from './engine.js';
 export { createWorkflowContextFactory, createWorkflowSchemaExtension, subscribeToWorkflowEvents } from './schema.js';

package/lib/schema.d.ts

@@ -1,6 +1,6 @@
 import type { ContextFactory, SchemaExtension } from '@kubun/engine';
+import type { AdaptivePolicy, InstanceStatus, ListFilter, PeriodicSync, WorkflowAPI, WorkflowEvents } from '@kubun/plugin-workflow-api';
 import type { EventsSource } from '@sozai/event';
-import type { InstanceStatus, ListFilter, WorkflowAPI, WorkflowEvents } from './types.js';
 export type WorkflowEventResult = {
     type: keyof WorkflowEvents;
     instanceID: string;
@@ -31,6 +31,10 @@ export type WorkflowContext = {
     get(instanceID: string): Promise<InstanceStatus | null>;
     list(filter: ListFilter): Promise<Array<InstanceStatus>>;
     subscribeToWorkflowEvents(instanceID?: string | null): AsyncIterableIterator<WorkflowEventResult>;
+    getPeriodicSync(scheduleID: string): Promise<PeriodicSync | null>;
+    listPeriodicSyncs(workflowName?: string): Promise<Array<PeriodicSync>>;
+    setPeriodicSyncEnabled(scheduleID: string, enabled: boolean): Promise<PeriodicSync | null>;
+    setPeriodicSyncPolicy(scheduleID: string, policy: AdaptivePolicy): Promise<PeriodicSync | null>;
 };
 declare module '@kubun/graphql' {
     interface PluginContextMap {

package/lib/schema.js

@@ -1,3 +1,7 @@
+import { PluginNodeID } from '@kubun/id';
+// The plugin identity and Node type name in every PeriodicSync global id.
+const PLUGIN_NAME = 'workflow';
+const PERIODIC_SYNC_TYPE = 'PeriodicSync';
 // 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 = [
@@ -95,11 +99,21 @@ function requireWorkflow(ctx) {
     }
     return ctx.workflow;
 }
+// A PeriodicSync's GraphQL `id` is a global PluginNodeID; the schedule id is its
+// localID. `node(id)` decodes centrally, but the typed fields receive the global
+// id and must decode it here.
+function decodeScheduleID(id) {
+    return PluginNodeID.fromString(id).localID;
+}
 export function createWorkflowContextFactory(api) {
     return ()=>({
             get: (instanceID)=>api.get(instanceID),
             list: (filter)=>api.list(filter),
-            subscribeToWorkflowEvents: (instanceID)=>subscribeToWorkflowEvents(api.events, instanceID)
+            subscribeToWorkflowEvents: (instanceID)=>subscribeToWorkflowEvents(api.events, instanceID),
+            getPeriodicSync: (scheduleID)=>api.getPeriodicSync(scheduleID),
+            listPeriodicSyncs: (workflowName)=>api.listPeriodicSyncs(workflowName),
+            setPeriodicSyncEnabled: (scheduleID, enabled)=>api.setPeriodicSyncEnabled(scheduleID, enabled),
+            setPeriodicSyncPolicy: (scheduleID, policy)=>api.setPeriodicSyncPolicy(scheduleID, policy)
         });
 }
 // ms-epoch timestamps are exposed as `Float` (JS number), matching how the
@@ -124,9 +138,28 @@ type WorkflowEvent {
   name: String!
 }
 
+type PeriodicSync implements Node {
+  id: ID!
+  subject: String!
+  workflowName: String!
+  enabled: Boolean!
+  nextRun: Float!
+  lastOutcome: String
+  consecutiveCount: Int!
+  policy: JSON!
+  currentStatus: WorkflowInstanceStatus
+}
+
 extend type Query {
   workflowInstance(instanceID: ID!): WorkflowInstanceStatus
   workflowInstances(name: String, queue: String, status: String): [WorkflowInstanceStatus!]!
+  periodicSync(id: ID!): PeriodicSync
+  periodicSyncs(workflowName: String): [PeriodicSync!]!
+}
+
+extend type Mutation {
+  setPeriodicSyncEnabled(id: ID!, enabled: Boolean!): PeriodicSync!
+  setPeriodicSyncPolicy(id: ID!, policy: JSON!): PeriodicSync!
 }
 
 extend type Subscription {
@@ -143,7 +176,23 @@ export function createWorkflowSchemaExtension() {
                         name: args.name,
                         queue: args.queue,
                         status: args.status
-                    })
+                    }),
+                periodicSync: (_source, args, context)=>requireWorkflow(context).getPeriodicSync(decodeScheduleID(args.id)),
+                periodicSyncs: (_source, args, context)=>requireWorkflow(context).listPeriodicSyncs(args.workflowName)
+            },
+            mutationFields: {
+                setPeriodicSyncEnabled: (_source, args, context)=>requireWorkflow(context).setPeriodicSyncEnabled(decodeScheduleID(args.id), args.enabled),
+                setPeriodicSyncPolicy: (_source, args, context)=>requireWorkflow(context).setPeriodicSyncPolicy(decodeScheduleID(args.id), args.policy)
+            },
+            typeFields: {
+                PeriodicSync: {
+                    id: (source)=>PluginNodeID.create(PLUGIN_NAME, PERIODIC_SYNC_TYPE, source.scheduleID).toString()
+                }
+            },
+            nodeResolvers: {
+                PeriodicSync: {
+                    resolve: (localID, ctx)=>requireWorkflow(ctx).getPeriodicSync(localID)
+                }
             },
             subscriptionFields: {
                 workflowEvents: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/plugin-workflow",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,20 +15,22 @@
     "LICENSE.md"
   ],
   "dependencies": {
+    "@kubun/db": "^0.14.0",
+    "@kubun/engine": "^0.14.0",
+    "@kubun/graphql": "^0.14.0",
+    "@kubun/id": "^0.14.0",
+    "@kubun/logger": "^0.14.0",
+    "@kubun/plugin-workflow-api": "^0.14.0",
+    "@kubun/store-workflow": "^0.14.0",
     "@sozai/event": "^0.1.3",
-    "@sozai/flow": "^0.3.0",
+    "@sozai/flow": "^0.3.1",
     "@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"
+    "@sozai/schema": "^0.1.1"
   },
   "devDependencies": {
-    "@testcontainers/postgresql": "^12.1.0",
-    "@kubun/db-postgres": "^0.13.0",
-    "@kubun/db-better-sqlite": "^0.13.0"
+    "@kubun/db-better-sqlite": "^0.14.0",
+    "@kubun/db-postgres": "^0.14.0",
+    "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {
     "access": "public"

package/lib/types.d.ts

@@ -1,73 +0,0 @@
-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

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