@adula/kit 0.2.0-alpha.4 → 1.0.0

package/build/src/workflows/define_workflow.js

@@ -0,0 +1,83 @@
+import { createMachine, getNextSnapshot } from 'xstate';
+const IDENTIFIER = /^[a-z][a-z0-9_]*$/;
+function targets(step) {
+    switch (step.type) {
+        case 'condition':
+            return [step.then, step.else];
+        case 'approval':
+            return [step.approve, step.reject];
+        case 'end':
+            return [];
+        default:
+            return [step.next];
+    }
+}
+/**
+ * Declares a versioned workflow. Steps compile to an XState machine; the engine
+ * performs each step's effect and asks the machine for the next step. Runs keep
+ * the version they started with, so publishing a new version never changes a
+ * running workflow (migrate explicitly with WorkflowEngine.migrateRuns).
+ */
+export function defineWorkflow(input) {
+    if (!IDENTIFIER.test(input.name))
+        throw new Error(`Invalid workflow name: ${input.name}`);
+    if (!Number.isInteger(input.version) || input.version < 1)
+        throw new Error('Workflow version must be a positive integer');
+    if (!(input.start in input.steps))
+        throw new Error(`Unknown start step: ${input.start}`);
+    const keys = Object.keys(input.steps);
+    for (const key of keys) {
+        if (!IDENTIFIER.test(key))
+            throw new Error(`Invalid step name: ${key}`);
+        for (const target of targets(input.steps[key]))
+            if (!(target in input.steps))
+                throw new Error(`Step ${key} points to unknown step ${target}`);
+        const step = input.steps[key];
+        if (step.type === 'delay' && (!Number.isInteger(step.ms) || step.ms < 0))
+            throw new Error(`Step ${key} needs a non-negative integer delay`);
+    }
+    if (!keys.some((key) => input.steps[key].type === 'end'))
+        throw new Error('A workflow needs at least one end step');
+    const machine = createMachine({
+        id: `${input.name}@${input.version}`,
+        initial: input.start,
+        states: Object.fromEntries(keys.map((key) => {
+            const step = input.steps[key];
+            switch (step.type) {
+                case 'condition':
+                    return [
+                        key,
+                        {
+                            on: {
+                                EVALUATE: [
+                                    {
+                                        target: step.then,
+                                        guard: ({ event }) => event.type === 'EVALUATE' && step.when(event.record),
+                                    },
+                                    { target: step.else },
+                                ],
+                            },
+                        },
+                    ];
+                case 'approval':
+                    return [key, { on: { APPROVE: step.approve, REJECT: step.reject } }];
+                case 'end':
+                    return [key, { type: 'final' }];
+                default:
+                    return [key, { on: { DONE: step.next } }];
+            }
+        })),
+    });
+    return { ...input, machine };
+}
+/** The step reached from `current` by `event`, or an error if the step does not accept it. */
+export function nextStep(definition, current, event) {
+    if (!(current in definition.steps))
+        throw new Error(`Step ${current} is not part of ${definition.name}@${definition.version}`);
+    const snapshot = definition.machine.resolveState({ value: current, context: {} });
+    const next = getNextSnapshot(definition.machine, snapshot, event);
+    const value = String(next.value);
+    if (value === current)
+        throw new Error(`Step ${current} does not accept ${event.type}`);
+    return value;
+}

package/build/src/workflows/engine.d.ts

@@ -0,0 +1,119 @@
+import type { Knex } from 'knex';
+import type { Actor } from '../auth/ability.js';
+import type { ResourceService } from '../admin/resource_service.js';
+import type { ResourceRegistry } from '../resource/registry.js';
+import type { JsonValue } from '../resource/types.js';
+import type { DomainEvent, Listener } from '../events/outbox.js';
+import type { HttpPoster } from '../integrations/webhooks.js';
+import type { Assignments } from '../collaboration/assignments.js';
+import { type WorkflowDefinition } from './define_workflow.js';
+export type WorkflowRunStatus = 'pending_definition' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+export type WorkflowRun = {
+    id: string;
+    resource: string;
+    resourceLabel: string;
+    recordId: number;
+    definition: string;
+    label: string;
+    version: number;
+    status: WorkflowRunStatus;
+    step: string | null;
+    stepLabel: string | null;
+    outcome: string | null;
+    attempts: number;
+    lastError: string | null;
+    wakeAt: string | null;
+    createdAt: string;
+    completedAt: string | null;
+    history: {
+        step: string | null;
+        event: string;
+        actorName: string | null;
+        detail: {
+            [key: string]: JsonValue;
+        };
+        at: string;
+    }[];
+    /** Open approval assigned to the viewer for this run, if any. */
+    myApproval: {
+        assignmentId: number;
+        title: string;
+    } | null;
+};
+export type WorkflowOptions = {
+    post?: HttpPoster;
+    /** Test hook simulating a crash after a step's effect and before its commit. */
+    beforeCommit?: (run: {
+        id: string;
+        step: string;
+    }) => void | Promise<void>;
+    now?: () => Date;
+};
+/**
+ * Durable workflow engine over workflow_runs. Every step runs inside the run's
+ * row lock (FOR UPDATE); its database effects and the transition commit together,
+ * so a crash repeats at most the step's external calls (HTTP carries a stable
+ * Idempotency-Key). Failed steps retry with growing delays up to maxAttempts.
+ */
+export declare class WorkflowEngine {
+    #private;
+    private db;
+    private registry;
+    private resources;
+    private actors;
+    private assignments;
+    private options;
+    constructor(db: Knex, registry: ResourceRegistry, resources: ResourceService, actors: {
+        load(id: number): Promise<Actor>;
+    }, assignments: Assignments, definitions: readonly WorkflowDefinition[], options?: WorkflowOptions);
+    register(definition: WorkflowDefinition): this;
+    /** The newest version of each workflow attached to a resource. */
+    private latestFor;
+    private definition;
+    /** Listeners: submitted documents start their workflow; cancelled ones stop it. */
+    listeners(): Listener[];
+    /** Claims the submission envelope written in the submit transaction. */
+    start(trx: Knex.Transaction, event: DomainEvent): Promise<void>;
+    /** Worker step: advances due runs, each under its own row lock. */
+    tick(limit?: number): Promise<number>;
+    /**
+     * Runs steps until the run waits, ends, fails or is scheduled later. The caller
+     * holds the row lock. Each step executes in a savepoint so a failing step leaves
+     * no partial effects behind.
+     */
+    private advance;
+    private execute;
+    /**
+     * Records an approver's decision. Only an open approval assigned to the actor
+     * counts, and the run is locked so concurrent decisions cannot both apply.
+     */
+    decide(runId: string, actor: Actor, decision: 'approve' | 'reject', comment?: unknown): Promise<WorkflowRun>;
+    /** Administrators put a failed run back to its failed step. */
+    retry(runId: string, actorId: number): Promise<void>;
+    /**
+     * Explicit version migration for runs that have not finished: `mapStep` returns
+     * the equivalent step name in the new version.
+     */
+    migrateRuns(name: string, from: number, to: number, mapStep: (step: string) => string): Promise<number>;
+    runsFor(name: string, id: number, actor: Actor): Promise<WorkflowRun[]>;
+    run(runId: string, actor: Actor): Promise<WorkflowRun>;
+    /** Runs waiting for the actor's decision, newest first, on records they can still read. */
+    inbox(actor: Actor): Promise<WorkflowRun[]>;
+    failed(limit?: number): Promise<WorkflowRun[]>;
+    private present;
+    private fail;
+    private cancelRuns;
+    private context;
+    /** Workflow writes are system writes attributed to the submitter, with history. */
+    private updateRecord;
+    private cancelDocument;
+    private recipients;
+    private canView;
+    private log;
+    private now;
+}
+/**
+ * Listeners resolved per call, so hosts can build the engine lazily (for example
+ * per request) while the listener list is fixed at boot from the registry.
+ */
+export declare function workflowListeners(registry: ResourceRegistry, engine: () => WorkflowEngine): Listener[];