@anteros/core 0.0.41 → 0.0.42

package/tests/vars-api.test.ts

@@ -34,7 +34,7 @@ afterAll(async () => {
 });
 
 const post = (action: string, body: any) =>
-    fetch(`${url}/vars/${TENANT}/${action}`, {
+    fetch(`${url}/api/${TENANT}/vars/${action}`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),

package/tests/vars-replication.test.ts

@@ -85,8 +85,9 @@ describe("vars replication", () => {
         expect(dest?.value).toBe("SCOPED-1");
     });
 
-    it("does NOT replicate namespaces that did not opt in", async () => {
-        // `private.var.ts` has no `replication` — it must never reach the destination.
+    it("does NOT replicate namespaces that opt out (`enabled: false`)", async () => {
+        // `private.var.ts` declares `replication: { enabled: false }` — it must
+        // never reach the destination.
         await rest.vars.set("private", "secret", "top-secret");
         await replicateTenant(TEST_TENANT);
 

package/tests/workflow-engine.test.ts

@@ -0,0 +1,340 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from "bun:test";
+import os from "node:os";
+import { formatConfig } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { syncWorkflows, ensureWorkflowIndexes, getWorkflow } from "../lib/workflow";
+import { useRest } from "../database/rest";
+import type { WorkflowRun } from "../types/workflow";
+
+const TENANT = "wf-engine";
+const DIR = "packages/core/tests/fixtures/workflow-engine";
+
+let rest: InstanceType<typeof useRest>;
+/** Shared, in-process state written by the fixture steps */
+const state: { log: string[]; attempts: Record<string, number> } = ((globalThis as any).__wfEngine ??= {
+    log: [],
+    attempts: {},
+});
+
+async function runsOf(workflowId: string): Promise<WorkflowRun[]> {
+    const col = rest.db.collection("_workflows_");
+    return (await col.find({ workflowId }).sort({ createdAt: -1 }).toArray()) as unknown as WorkflowRun[];
+}
+
+/** The run currently being executed (its `_id` is only known from the database) */
+async function currentRun(workflowId: string): Promise<any> {
+    for (let i = 0; i < 80; i++) {
+        const [run] = await runsOf(workflowId);
+        if (run && run.status === "running") return run;
+        await Bun.sleep(25);
+    }
+    throw new Error(`no running '${workflowId}' run found`);
+}
+
+/** Insert a run document directly, to set up a state the engine must recover from */
+async function insertRun(doc: Partial<WorkflowRun> & { _id: string; workflowId: string }): Promise<void> {
+    await rest.db.collection("_workflows_").insertOne({
+        tenant_id: TENANT,
+        status: "failed",
+        progress: 0,
+        data: {},
+        currentStep: 0,
+        totalExecuted: 0,
+        totalSkipped: 0,
+        steps: [],
+        compensations: [],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...doc,
+    } as any);
+}
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id: TENANT, dir: DIR, database: { uri: "mongodb://localhost:27017/_WF_ENGINE" } }],
+    });
+    await syncTenants();
+    await syncWorkflows();
+    await ensureWorkflowIndexes();
+    rest = new useRest({ tenant_id: TENANT, internal: true });
+});
+
+beforeEach(() => {
+    state.log.length = 0;
+    for (const key of Object.keys(state.attempts)) delete state.attempts[key];
+});
+
+afterAll(async () => {
+    try { await rest.db.collection("_workflows_").drop(); } catch (_) {}
+    try { await rest.db.collection("_locks_").drop(); } catch (_) {}
+    delete (globalThis as any).__wfEngine;
+});
+
+describe("workflow locks", () => {
+    it("runs a step once when two nodes resume the same run", async () => {
+        await insertRun({
+            _id: "lock-1",
+            workflowId: "simple",
+            status: "paused",
+            steps: [{ stepId: "one", status: "pending", startedAt: new Date() } as any],
+        });
+
+        const [a, b] = await Promise.allSettled([
+            rest.workflow.resume("lock-1"),
+            rest.workflow.resume("lock-1"),
+        ]);
+        const outcomes = [a, b].map((r) => r.status);
+        const errors = [a, b].map((r: any) => r.reason?.code).filter(Boolean) as string[];
+
+        // One node wins; the other is either locked out or finds the run finished
+        expect(outcomes).toContain("fulfilled");
+        for (const code of errors) expect(["RUN_LOCKED", "RUN_TERMINAL"]).toContain(code);
+
+        // …and above all: the step was NOT executed twice
+        expect(state.log.filter((l) => l === "simple:one").length).toBe(1);
+    });
+
+    it("releases the lock when the run finishes (a later resume is not locked)", async () => {
+        const run = await rest.workflow.run("simple", { echo: "release" });
+        const locks = await rest.db.collection("_locks_").countDocuments({ name: `workflow:${run._id}` });
+        expect(locks).toBe(0);
+    });
+
+    it("refuses a resume while another node holds the run", async () => {
+        await insertRun({
+            _id: "lock-2",
+            workflowId: "simple",
+            status: "paused",
+            steps: [{ stepId: "one", status: "pending", startedAt: new Date() } as any],
+        });
+        // Simulate another node holding the lock (not expired)
+        await rest.db.collection("_locks_").insertOne({
+            _id: `${TENANT}:workflow:lock-2` as any,
+            tid: TENANT,
+            name: "workflow:lock-2",
+            acquiredAt: Date.now(),
+            expiresAt: Date.now() + 60_000,
+        } as any);
+
+        await expect(rest.workflow.resume("lock-2")).rejects.toThrow(/another node/);
+        await rest.db.collection("_locks_").deleteOne({ name: "workflow:lock-2" });
+    });
+});
+
+describe("workflow pause & cancel", () => {
+    it("pauses an in-flight run at the next step boundary", async () => {
+        const pending = rest.workflow.run("slow", { ms: 600 });
+        const running = await currentRun("slow");
+
+        expect(await rest.workflow.pause(running._id)).toBe(true);
+        const run: any = await pending;
+
+        expect(run.status).toBe("paused");
+        expect(state.log).toEqual(["slow:fast", "slow:slow:start", "slow:slow:end"]);
+        expect(run.steps[2].status).toBe("pending"); // the last step never ran
+    }, 20_000);
+
+    it("resumes a paused run from the step it stopped at", async () => {
+        const [paused] = await runsOf("slow");
+        state.log.length = 0;
+
+        const run = await rest.workflow.resume(paused!._id, { ms: 10 });
+        expect(run.status).toBe("completed");
+        expect(state.log).toEqual(["slow:last"]);
+    }, 20_000);
+
+    it("cancels an in-flight run permanently", async () => {
+        const pending = rest.workflow.run("slow", { ms: 600 });
+        const running = await currentRun("slow");
+
+        expect(await rest.workflow.cancel(running._id)).toBe(true);
+        const run: any = await pending;
+
+        expect(run.status).toBe("cancelled");
+        expect(state.log).not.toContain("slow:last");
+        await expect(rest.workflow.resume(run._id)).rejects.toThrow(/cancelled|not applicable/);
+    }, 20_000);
+
+    it("does not cancel a run that already completed", async () => {
+        const done = await rest.workflow.run("simple", { echo: "terminal" });
+        expect(await rest.workflow.cancel(done._id)).toBe(false);
+
+        const stored: any = await rest.workflow.getRun(done._id);
+        expect(stored.status).toBe("completed");
+    });
+});
+
+describe("workflow step retries & timeout", () => {
+    it("retries a transient failure instead of rolling the saga back", async () => {
+        const run = await rest.workflow.run("flaky", { failUntil: 2 });
+        expect(run.status).toBe("completed");
+        expect(state.log).toEqual(["flaky:attempt:1", "flaky:attempt:2", "flaky:attempt:3"]);
+        expect(run.steps[0]!.output).toEqual({ attempts: 3 });
+    });
+
+    it("gives up after `retries` and fails the run", async () => {
+        await expect(rest.workflow.run("flaky", { failUntil: 5 })).rejects.toThrow(/transient failure/);
+        const [run] = await runsOf("flaky");
+        expect(run!.status).toBe("failed");
+        expect(state.attempts.unstable).toBe(3); // 1 attempt + 2 retries
+    });
+
+    it("aborts a step that exceeds its timeout", async () => {
+        await expect(rest.workflow.run("hang", { ms: 1000 })).rejects.toThrow(/timed out/);
+        const [run] = await runsOf("hang");
+        expect(run!.status).toBe("failed");
+        expect(run!.error?.code).toBe("WORKFLOW_STEP_TIMEOUT");
+    }, 15_000);
+});
+
+describe("workflow compensations", () => {
+    it("compensates the completed steps and marks the run `compensated`", async () => {
+        await expect(rest.workflow.run("failing", {})).rejects.toThrow(/boom-b/);
+        const [run] = await runsOf("failing");
+
+        expect(run!.status).toBe("compensated");
+        expect(run!.steps[2]!.status).toBe("pending"); // never reached
+        expect(state.log).toEqual([
+            "failing:a:rest=client",
+            "simple:one", // the sub-workflow run from the step
+            "failing:a:sub-workflow-done",
+            "failing:b",
+            "failing:undo-a:1",
+        ]);
+    }, 15_000);
+
+    it("refuses to resume a compensated run (never replays the steps)", async () => {
+        const [run] = await runsOf("failing");
+        state.log.length = 0;
+
+        await expect(rest.workflow.resume(run!._id)).rejects.toThrow(/compensated/);
+        expect(state.log).toEqual([]);
+    });
+
+    it("never replays a compensation through resumeAll", async () => {
+        const [before] = await runsOf("failing");
+        state.log.length = 0;
+
+        await rest.workflow.resumeAll();
+
+        // The compensated run is left alone and its compensation is not replayed
+        const [after] = await runsOf("failing");
+        expect(after!.status).toBe("compensated");
+        expect(state.log.filter((l) => l.startsWith("failing:undo-a"))).toEqual([]);
+        expect(before!._id).toBe(after!._id);
+    }, 15_000);
+
+    it("finishes an interrupted rollback without replaying what already succeeded", async () => {
+        await insertRun({
+            _id: "rollback-1",
+            workflowId: "failing",
+            status: "failed",
+            steps: [
+                { stepId: "a", status: "completed", output: { a: 1 }, startedAt: new Date() } as any,
+                { stepId: "b", status: "failed", error: { message: "boom-b" }, startedAt: new Date() } as any,
+                { stepId: "c", status: "pending", startedAt: new Date() } as any,
+            ],
+            // `undo-a` failed the first time: the rollback must be finished
+            compensations: [{ stepId: "undo-a", status: "failed", error: { message: "network" }, startedAt: new Date() } as any],
+        });
+
+        const run: any = await rest.workflow.resume("rollback-1");
+        expect(run.status).toBe("compensated");
+        expect(run.steps[1].status).toBe("failed"); // never continued forward
+        expect(state.log.length).toBe(1);
+        expect(state.log[0]).toStartWith("failing:undo-a");
+        expect(run.compensations.length).toBe(2); // the failed one + the successful retry
+    });
+
+    it("replays nothing when the rollback already succeeded", async () => {
+        await insertRun({
+            _id: "rollback-2",
+            workflowId: "failing",
+            status: "failed",
+            steps: [
+                { stepId: "a", status: "completed", output: { a: 1 }, startedAt: new Date() } as any,
+                { stepId: "b", status: "failed", error: { message: "boom-b" }, startedAt: new Date() } as any,
+            ],
+            compensations: [{ stepId: "undo-a", status: "completed", startedAt: new Date() } as any],
+        });
+        state.log.length = 0;
+
+        const run: any = await rest.workflow.resume("rollback-2");
+        expect(run.status).toBe("compensated");
+        expect(state.log).toEqual([]); // the successful compensation was not replayed
+    });
+});
+
+describe("workflow run ownership", () => {
+    it("stops when another node takes the run over", async () => {
+        const pending = rest.workflow.run("slow", { ms: 500 });
+        const running = await currentRun("slow");
+
+        // Simulate a takeover: another process owns the run lock now
+        await rest.db.collection("_locks_").updateOne(
+            { _id: `${TENANT}:workflow:${running._id}` as any },
+            { $set: { pid: process.pid + 1, hostname: os.hostname(), expiresAt: Date.now() + 60_000 } },
+        );
+
+        const run: any = await pending;
+        expect(run.steps[2].status).toBe("pending"); // the last step never ran
+        expect(state.log).not.toContain("slow:last");
+
+        await rest.db.collection("_locks_").deleteOne({ _id: `${TENANT}:workflow:${running._id}` as any });
+    }, 20_000);
+
+    it("records the executing pid on the run", async () => {
+        const run = await rest.workflow.run("simple", { echo: "who" });
+        expect(run.pid).toBe(process.pid);
+        expect(run.hostname).toBe(os.hostname());
+    });
+});
+
+describe("workflow resume guards", () => {
+    it("refuses to resume a run started by another version", async () => {
+        await insertRun({
+            _id: "version-1",
+            workflowId: "versioned",
+            workflowVersion: 1,
+            status: "paused",
+            steps: [{ stepId: "v", status: "pending", startedAt: new Date() } as any],
+        });
+        // The workflow has been deployed in version 2 since the run started
+        getWorkflow("versioned", TENANT)!.version = 2;
+
+        await expect(rest.workflow.resume("version-1")).rejects.toThrow(/version/);
+
+        // …unless the operator forces it
+        state.log.length = 0;
+        const run: any = await rest.workflow.resume("version-1", undefined, { force: true });
+        expect(run.status).toBe("completed");
+        expect(state.log).toEqual(["versioned:v"]);
+
+        getWorkflow("versioned", TENANT)!.version = 1;
+    });
+});
+
+describe("workflow resumeAll", () => {
+    it("resumes every paused run, batch by batch", async () => {
+        for (let i = 0; i < 5; i++) {
+            await insertRun({
+                _id: `bulk-${i}`,
+                workflowId: "simple",
+                status: "paused",
+                steps: [{ stepId: "one", status: "pending", startedAt: new Date() } as any],
+            });
+        }
+
+        const { resumed } = await rest.workflow.resumeAll(undefined, { batchSize: 2 });
+        expect(resumed).toBeGreaterThanOrEqual(5);
+
+        const left = await rest.db.collection("_workflows_")
+            .countDocuments({ _id: /^bulk-/, status: { $in: ["paused", "failed"] } });
+        expect(left).toBe(0);
+
+        const done = await rest.db.collection("_workflows_")
+            .countDocuments({ _id: /^bulk-/, status: "completed" });
+        expect(done).toBe(5);
+    }, 20_000);
+});

package/tests/workflow-retention.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants, getTenant } from "../database/tenant";
+import { syncWorkflows, ensureWorkflowIndexes, resolveWorkflowsRetention } from "../lib/workflow";
+
+const SERVER_RETENTION = "30d";
+
+const INHERIT = "wfr-inherit";
+const OVERRIDE = "wfr-override";
+const OFF = "wfr-off";
+
+const DBS = {
+    [INHERIT]: "mongodb://localhost:27017/_WF_RET_INHERIT",
+    [OVERRIDE]: "mongodb://localhost:27017/_WF_RET_OVERRIDE",
+    [OFF]: "mongodb://localhost:27017/_WF_RET_OFF",
+} as const;
+
+const TTL_INDEX = "_workflow_runs_ttl_";
+
+/** TTL index of a tenant's `_workflows_` collection, or undefined */
+async function ttlIndex(tenantId: string): Promise<any> {
+    const db = getTenant(tenantId)!.database!.db!;
+    return (await db.collection("_workflows_").listIndexes().toArray())
+        .find((i: any) => i.name === TTL_INDEX);
+}
+
+beforeAll(async () => {
+    formatConfig({
+        server: {
+            port: 4000,
+            // Server-wide default — inherited unless the tenant declares its own
+            workflows: { retention: SERVER_RETENTION },
+        },
+        tenants: [
+            { id: INHERIT, dir: "packages/core/tests/fixtures/workflow-engine", database: { uri: DBS[INHERIT] } },
+            {
+                id: OVERRIDE,
+                dir: "packages/core/tests/fixtures/workflow-engine",
+                database: { uri: DBS[OVERRIDE] },
+                workflows: { retention: "1h" },
+            },
+            {
+                id: OFF,
+                dir: "packages/core/tests/fixtures/workflow-engine",
+                database: { uri: DBS[OFF] },
+                workflows: { retention: false },
+            },
+        ],
+    });
+
+    await syncTenants();
+    await syncWorkflows();
+    await ensureWorkflowIndexes();
+});
+
+afterAll(async () => {
+    for (const id of Object.keys(DBS)) {
+        try { await getTenant(id)?.database?.db?.collection("_workflows_").drop(); } catch (_) {}
+    }
+    delete (cfg.server as any).workflows;
+});
+
+describe("workflow run retention", () => {
+    it("resolves the tenant first, the server default as fallback", () => {
+        expect(resolveWorkflowsRetention({ id: INHERIT, dir: "x", database: { uri: "" } } as any)).toBe(SERVER_RETENTION);
+        expect(resolveWorkflowsRetention({ id: OVERRIDE, dir: "x", database: { uri: "" }, workflows: { retention: "1h" } } as any)).toBe("1h");
+        // `false` is a value, not an absence — it must override the server default
+        expect(resolveWorkflowsRetention({ id: OFF, dir: "x", database: { uri: "" }, workflows: { retention: false } } as any)).toBe(false);
+    });
+
+    it("applies the server default to a tenant without its own config", async () => {
+        const ttl = await ttlIndex(INHERIT);
+        expect(ttl).toBeDefined();
+        expect(ttl.key).toEqual({ completedAt: 1 });
+        expect(ttl.expireAfterSeconds).toBe(30 * 86400);
+    });
+
+    it("lets the tenant override the server default", async () => {
+        const ttl = await ttlIndex(OVERRIDE);
+        expect(ttl).toBeDefined();
+        expect(ttl.expireAfterSeconds).toBe(3600);
+    });
+
+    it("lets a tenant opt out with `false`", async () => {
+        expect(await ttlIndex(OFF)).toBeUndefined();
+    });
+
+    it("only prunes finished runs (`completedAt` is never set on an in-flight one)", async () => {
+        const db = getTenant(INHERIT)!.database!.db!;
+        const col: any = db.collection("_workflows_");
+        await col.insertMany([
+            { _id: "ret-running", workflowId: "simple", status: "running", createdAt: new Date(), updatedAt: new Date() },
+            { _id: "ret-paused", workflowId: "simple", status: "paused", createdAt: new Date(), updatedAt: new Date() },
+            { _id: "ret-done", workflowId: "simple", status: "completed", completedAt: new Date(), createdAt: new Date(), updatedAt: new Date() },
+        ]);
+
+        const missing = await col.countDocuments({ _id: { $in: ["ret-running", "ret-paused"] }, completedAt: { $exists: false } });
+        const finished = await col.countDocuments({ completedAt: { $exists: true } });
+
+        expect(missing).toBe(2);   // never pruned by a TTL on `completedAt`
+        expect(finished).toBe(1);  // only the finished run can expire
+    });
+});

package/tests/workflow.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import os from "node:os";
+import { formatConfig } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { syncWorkflows, ensureWorkflowIndexes, getWorkflow, workflowStats } from "../lib/workflow";
+import { useRest } from "../database/rest";
+
+const TENANT = "wf-test";
+// Second tenant sharing the same code folder — same workflows, other database
+const TENANT_2 = "wf-test-2";
+const DIR = "packages/core/tests/fixtures/workflow-tenant";
+
+let rest: InstanceType<typeof useRest>;
+
+async function indexNames(tenantId: string): Promise<string[]> {
+    const tenantRest = new useRest({ tenant_id: tenantId, internal: true });
+    return (await tenantRest.db.collection("_workflows_").listIndexes().toArray()).map((i: any) => i.name);
+}
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [
+            { id: TENANT, dir: DIR, database: { uri: "mongodb://localhost:27017/_WF_TEST" } },
+            { id: TENANT_2, dir: DIR, database: { uri: "mongodb://localhost:27017/_WF_TEST_2" } },
+        ],
+    });
+    await syncTenants();
+    await syncWorkflows();
+    // The loader fires the index pass in the background — await it here so the
+    // assertions below are deterministic (the non-blocking behaviour is tested
+    // separately, via `syncWorkflows()` alone).
+    await ensureWorkflowIndexes();
+
+    rest = new useRest({ tenant_id: TENANT, internal: true });
+});
+
+afterAll(async () => {
+    for (const id of [TENANT, TENANT_2]) {
+        try { await new useRest({ tenant_id: id, internal: true }).db.collection("_workflows_").drop(); } catch (_) {}
+    }
+});
+
+describe("workflow loader", () => {
+    it("registers the enabled workflows of the tenant", () => {
+        const invoice = getWorkflow("invoice", TENANT);
+        expect(invoice).toBeDefined();
+        expect(invoice!._tenant_).toBe(TENANT);
+        expect(invoice!.version).toBe(3);
+    });
+
+    it("keeps exactly one definition for a duplicated id", () => {
+        const order = getWorkflow("order", TENANT);
+        // Which file wins depends on the filesystem order — what matters is that
+        // there is a single, valid definition (never two, never a crash)
+        expect(["Orders", "Orders (duplicate definition)"]).toContain(order!.name);
+    });
+
+    it("skips disabled workflows (`enabled: false`)", () => {
+        expect(getWorkflow("nightly", TENANT)).toBeUndefined();
+    });
+
+    it("ignores a workflow without an `id`", () => {
+        // A missing id used to be registered under the literal `undefined` key
+        expect(getWorkflow("undefined", TENANT)).toBeUndefined();
+    });
+
+    it("isolates a file that throws on import", () => {
+        expect(getWorkflow("broken", TENANT)).toBeUndefined();
+        // …and the other workflows are still there
+        expect(getWorkflow("order", TENANT)).toBeDefined();
+    });
+
+    it("loads the same folder independently for each tenant", () => {
+        expect(getWorkflow("order", TENANT)).toBeDefined();
+        expect(getWorkflow("order", TENANT_2)).toBeDefined();
+        expect(getWorkflow("order", TENANT_2)!._tenant_).toBe(TENANT_2);
+    });
+
+    it("reports what was loaded", () => {
+        const stats = workflowStats();
+        expect(stats.total).toBeGreaterThanOrEqual(2); // one per tenant
+        expect(stats.tenants).toContain(TENANT);
+        expect(stats.tenants).toContain(TENANT_2);
+    });
+});
+
+describe("workflow indexes", () => {
+    it("creates the indexes the engine queries on", async () => {
+        const names = await indexNames(TENANT);
+        expect(names).toContain("workflowId_1_createdAt_-1"); // listRuns()
+        expect(names).toContain("status_1");                  // resumeAll()
+    });
+
+    it("creates the indexes declared by the workflow context", async () => {
+        const names = await indexNames(TENANT);
+        expect(names).toContain("context.customerId_1");
+        expect(names).toContain("context.total_-1");
+        expect(names).toContain("context.companyId_1");
+        // a field without `index` is not indexed
+        expect(names).not.toContain("context.note_1");
+        expect(names).not.toContain("context.processedAt_1");
+    });
+
+    it("creates the explicit `indexes` — compound, unique, sparse, named", async () => {
+        const names = await indexNames(TENANT);
+        expect(names).toContain("context.companyId_1_status_1"); // compound
+        expect(names).toContain("uniq_batch");                  // explicit name
+
+        const uniq: any = (await rest.db.collection("_workflows_").listIndexes().toArray())
+            .find((i: any) => i.name === "uniq_batch");
+        expect(uniq.unique).toBe(true);
+        expect(uniq.sparse).toBe(true);
+    });
+
+    it("is idempotent — running it again creates nothing", async () => {
+        const before = (await indexNames(TENANT)).length;
+        await ensureWorkflowIndexes();
+        expect((await indexNames(TENANT)).length).toBe(before);
+    });
+
+    it("serves the engine's own query with an index scan", async () => {
+        const col: any = rest.db.collection("_workflows_");
+        // A run must exist for the collection to be queryable/explainable
+        await rest.workflow.run("invoice", { ref: "A-1" });
+        const plan = JSON.stringify(await col.find({ workflowId: "invoice" }).explain("queryPlanner"));
+        expect(plan).toContain("IXSCAN"); // COLLSCAN before the loader indexed `workflowId`
+    });
+});
+
+describe("workflow engine wiring", () => {
+    it("runs a workflow loaded from the filesystem", async () => {
+        const run = await rest.workflow.run("invoice", { ref: "A-1" }, { companyId: "c-1" });
+        expect(run.status).toBe("completed");
+        expect(run.workflowVersion).toBe(3);
+        expect(run.context).toEqual({ companyId: "c-1" });
+        expect(run.steps.length).toBe(2);
+        // The run says which process executed it (`reusePort` / forked workers)
+        expect(run.pid).toBe(process.pid);
+        expect(run.hostname).toBe(os.hostname());
+
+        const runs = await rest.workflow.listRuns("invoice");
+        expect(runs.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it("refuses to run a disabled workflow", async () => {
+        await expect(rest.workflow.run("nightly", {})).rejects.toThrow();
+    });
+});
+
+describe("workflow context validation", () => {
+    it("accepts a context that matches the declaration", async () => {
+        const run = await rest.workflow.run("invoice", { ref: "B-1" }, { companyId: "c-2" });
+        expect(run.context).toEqual({ companyId: "c-2" });
+    });
+
+    it("rejects a wrong type with a clear code", async () => {
+        await expect(
+            rest.workflow.run("invoice", {}, { companyId: 42 as any }),
+        ).rejects.toThrow(/must be a string/);
+    });
+
+    it("coerces an ISO string to a real Date (so `context.*` indexes stay typed)", async () => {
+        const run = await rest.workflow.run("invoice", {}, {
+            companyId: "c-3",
+            processedAt: "2026-03-04T05:06:07.000Z" as any,
+        });
+        expect(run.context.processedAt).toBeInstanceOf(Date);
+        expect((run.context.processedAt as Date).toISOString()).toBe("2026-03-04T05:06:07.000Z");
+
+        // …and it is stored as a Date in MongoDB too
+        const stored: any = await rest.workflow.getRun(run._id);
+        expect(stored.context.processedAt).toBeInstanceOf(Date);
+    });
+
+    it("rejects an invalid date", async () => {
+        await expect(
+            rest.workflow.run("invoice", {}, { processedAt: "not-a-date" as any }),
+        ).rejects.toThrow(/must be a date/);
+    });
+
+    it("keeps undeclared keys as-is", async () => {
+        const run = await rest.workflow.run("invoice", {}, { companyId: "c-4", extra: { any: "thing" } });
+        expect(run.context.extra).toEqual({ any: "thing" });
+    });
+});