@anteros/core 0.0.40 → 0.0.42

package/tests/vars.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient, ObjectId } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncVars } from "../database/vars";
+import { define } from "../lib/define";
+
+const TEST_TENANT = "vars";
+const DB = "mongodb://localhost:27017/_VARS_TEST";
+
+let rest: InstanceType<typeof useRest>;
+let client: MongoClient;
+const raw = () => client.db().collection("_vars_");
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "packages/core/tests/fixtures/vars-tenant",
+            database: { uri: DB },
+        }],
+    });
+
+    client = new MongoClient(DB, { serverSelectionTimeoutMS: 3000 });
+    await client.connect();
+    const tenant: any = cfg.tenants?.[0];
+    tenant.database.client = client;
+    tenant.database.db = client.db();
+
+    await syncVars();
+
+    rest = new useRest({ tenant_id: TEST_TENANT });
+});
+
+afterAll(async () => {
+    try { await client.db().dropDatabase(); } catch (_) {}
+    try { await client.close(); } catch (_) {}
+});
+
+describe("define.Vars", () => {
+    it("marks the definition", () => {
+        const v = define.Vars({ namespace: "x", vars: { a: 1 } });
+        expect(v._isVars_).toBe(true);
+    });
+});
+
+describe("vars loading & seeding", () => {
+    it("loads the definitions from vars/*.var.ts", () => {
+        const namespaces = (cfg.vars ?? []).map((v) => v.namespace).sort();
+        expect(namespaces).toEqual(["config", "private"]);
+        expect((cfg.vars ?? []).every((v) => v._tenant_ === TEST_TENANT)).toBe(true);
+    });
+
+    it("seeds default values at the global scope", async () => {
+        expect(await rest.vars.get<string>("config", "licence")).toBe("RDX00");
+        expect(await rest.vars.get<number>("config", "maxUsers")).toBe(100);
+    });
+
+    it("never overwrites an existing value when re-seeding", async () => {
+        await rest.vars.set("config", "licence", "CHANGED");
+        await syncVars();
+        expect(await rest.vars.get<string>("config", "licence")).toBe("CHANGED");
+    });
+
+    it("always creates the scope + TTL indexes", async () => {
+        const names = (await raw().listIndexes().toArray()).map((i) => i.name);
+        expect(names).toContain("scope_1_ns_1");
+        expect(names).toContain("expiresAt_1");
+    });
+});
+
+describe("rest.vars — CRUD", () => {
+    it("set / get / has / del", async () => {
+        await rest.vars.set("app", "theme", "dark");
+        expect(await rest.vars.get<string>("app", "theme")).toBe("dark");
+        expect(await rest.vars.has("app", "theme")).toBe(true);
+
+        expect(await rest.vars.del("app", "theme")).toBe(true);
+        expect(await rest.vars.get<string>("app", "theme")).toBeUndefined();
+        expect(await rest.vars.has("app", "theme")).toBe(false);
+        expect(await rest.vars.del("app", "theme")).toBe(false);
+    });
+
+    it("stores rich values (objects, arrays, booleans)", async () => {
+        const value = { max: 10, tags: ["a", "b"], on: true };
+        await rest.vars.set("app", "limits", value);
+        expect(await rest.vars.get<any>("app", "limits")).toEqual(value);
+    });
+
+    it("setMany / all / clear", async () => {
+        await rest.vars.setMany("bulk", { a: 1, b: 2, c: 3 });
+        expect(await rest.vars.all("bulk")).toEqual({ a: 1, b: 2, c: 3 });
+        expect(await rest.vars.clear("bulk")).toBe(3);
+        expect(await rest.vars.all("bulk")).toEqual({});
+    });
+
+    it("incr is atomic (and creates a missing key)", async () => {
+        await rest.vars.set("counters", "hits", 5);
+        expect(await rest.vars.incr("counters", "hits")).toBe(6);
+        expect(await rest.vars.incr("counters", "hits", 10)).toBe(16);
+        expect(await rest.vars.incr("counters", "fresh", 3)).toBe(3);
+    });
+
+    it("isolates namespaces", async () => {
+        await rest.vars.set("ns1", "k", "a");
+        await rest.vars.set("ns2", "k", "b");
+        expect(await rest.vars.get<string>("ns1", "k")).toBe("a");
+        expect(await rest.vars.get<string>("ns2", "k")).toBe("b");
+    });
+});
+
+describe("rest.vars — scope (per company)", () => {
+    it("keeps a distinct value per scope", async () => {
+        const acme = new ObjectId().toHexString();
+        const globex = new ObjectId().toHexString();
+
+        await rest.vars.scope(acme).set("config", "licence", "ACME-001");
+        await rest.vars.scope(globex).set("config", "licence", "GLBX-002");
+
+        expect(await rest.vars.scope(acme).get<string>("config", "licence")).toBe("ACME-001");
+        expect(await rest.vars.scope(globex).get<string>("config", "licence")).toBe("GLBX-002");
+        // global value untouched
+        expect(await rest.vars.get<string>("config", "licence")).not.toBe("ACME-001");
+    });
+
+    it("accepts an explicit scope option", async () => {
+        const id = new ObjectId().toHexString();
+        await rest.vars.set("config", "licence", "SCOPED", { scope: id });
+        expect(await rest.vars.get<string>("config", "licence", { scope: id })).toBe("SCOPED");
+    });
+});
+
+describe("rest.vars — meta", () => {
+    it("stores and returns validated meta", async () => {
+        const id = new ObjectId().toHexString();
+        const acme = rest.vars.scope(id);
+
+        await acme.set("config", "licence", "ACME-003", { meta: { note: "Contrat 2026" } });
+        const entry = await acme.entry("config", "licence");
+
+        expect(entry?.value).toBe("ACME-003");
+        expect(entry?.meta).toEqual({ note: "Contrat 2026" });
+        expect(String(entry?.scope)).toBe(id);
+    });
+
+    it("rejects unknown meta keys", async () => {
+        await expect(
+            rest.vars.set("config", "licence", "X", { meta: { nope: 1 } }),
+        ).rejects.toThrow(/nope/);
+    });
+
+    it("filters entries on meta with `where`", async () => {
+        const id = new ObjectId().toHexString();
+        const acme = rest.vars.scope(id);
+
+        await acme.setMany("flags", { a: true, b: false }, { meta: { note: "grp" } });
+        const found = await acme.entries("flags", { where: { note: "grp" } });
+
+        expect(found.length).toBe(2);
+        expect(await acme.entries("flags", { where: { note: "other" } })).toEqual([]);
+    });
+});
+
+describe("rest.vars — validation", () => {
+    it("rejects a value that does not match its spec", async () => {
+        await expect(rest.vars.set("config", "maxUsers", "not-a-number")).rejects.toThrow(/maxUsers/);
+    });
+});
+
+describe("rest.vars — TTL", () => {
+    it("stores an expiry set per call", async () => {
+        await rest.vars.set("ttl", "k", "v", { ttl: "1h" });
+        const entry = await rest.vars.entry("ttl", "k");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+        expect(entry!.expiresAt!.getTime()).toBeGreaterThan(Date.now());
+    });
+
+    it("applies the variable's default TTL", async () => {
+        await rest.vars.set("config", "session", "s1"); // `session` declares ttl: '1h'
+        const entry = await rest.vars.entry("config", "session");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it("`set` without ttl clears an existing one", async () => {
+        await rest.vars.set("ttl", "clear", "v", { ttl: "1h" });
+        await rest.vars.set("ttl", "clear", "v2"); // no ttl → authoritative reset
+        const entry = await rest.vars.entry("ttl", "clear");
+        expect(entry?.expiresAt).toBeNull();
+    });
+
+    it("`expire` sets / renews the TTL", async () => {
+        await rest.vars.set("ttl", "renew", "v");
+        expect(await rest.vars.expire("ttl", "renew", "30m")).toBe(true);
+        const entry = await rest.vars.entry("ttl", "renew");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it("hides an expired entry from reads", async () => {
+        await raw().insertOne({
+            _id: "config:gone",
+            ns: "config", key: "gone", scope: null,
+            value: "x", meta: {},
+            expiresAt: new Date(Date.now() - 1000),
+            createdAt: new Date(), updatedAt: new Date(),
+        } as any);
+
+        expect(await rest.vars.get<string>("config", "gone")).toBeUndefined();
+        expect(await rest.vars.has("config", "gone")).toBe(false);
+        expect(await rest.vars.entry("config", "gone")).toBeUndefined();
+    });
+
+    it("rejects an invalid ttl", async () => {
+        await expect(rest.vars.set("ttl", "bad", "v", { ttl: "abc" })).rejects.toThrow(/ttl/);
+    });
+});

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
+    });
+});