@anteros/core 0.0.41 → 0.0.44

package/tests/fixtures/agent-tenant/agents/weather.agent.ts

@@ -0,0 +1,21 @@
+import { define, v } from "../../../../index";
+
+/**
+ * Loader fixture — `{tenant.dir}/agents/**\/*.agent.ts`.
+ * No call is ever made against the provider here: only the loader is exercised.
+ */
+export default define.Agent({
+    id: "weather",
+    name: "Weather Agent",
+    description: "Answers weather questions with a tool call",
+    instructions: "You are a concise weather assistant.",
+    provider: { model: "test-model", protocol: "openai", apiKey: "fixture-key" },
+    tools: {
+        forecast: define.Tool({
+            id: "forecast",
+            description: "Current weather for a city",
+            inputSchema: v.object({ city: v.string().required() }),
+            execute: async ({ city }) => ({ city, celsius: 21 }),
+        }),
+    },
+});

package/tests/fixtures/agents-api/agents/assistant.agent.ts

@@ -0,0 +1,46 @@
+import { define, v, agents } from "../../../../index";
+
+/**
+ * HTTP-API fixture — exposed through `POST /api/:tenant_id/agents/:agent/:action`.
+ *
+ * The provider endpoint comes from the environment so the test can point it at
+ * its own fake provider (the port is chosen by the OS).
+ */
+export default define.Agent({
+    id: "assistant",
+    name: "Assistant",
+    description: "Fixture agent for the HTTP API",
+    instructions: "You are a fixture agent.",
+    provider: {
+        model: "test-model",
+        protocol: "openai",
+        apiKey: "test-key",
+        baseUrl: Bun.env.AGENT_API_TEST_URL ?? "http://127.0.0.1:1",
+        options: { retries: 0 },
+    },
+    maxSteps: 3,
+    memory: new agents.memory.InMemory(),
+    tools: {
+        echo: define.Tool({
+            id: "echo",
+            description: "Echoes the given text",
+            inputSchema: v.object({ text: v.string().required() }),
+            execute: async ({ text }) => ({ echoed: text }),
+        }),
+    },
+    api: {
+        access: {
+            // public metadata — no token needed
+            info: true,
+            generate: (ctx) => !!ctx.token.value,
+            stream: (ctx) => !!ctx.token.value,
+            object: (ctx) => !!ctx.token.value,
+            history: (ctx) => !!ctx.token.value,
+            threads: (ctx) => !!ctx.token.value,
+            clear: (ctx) => !!ctx.token.value,
+        },
+        object: {
+            schema: v.object({ city: v.string().required(), celsius: v.number().required() }),
+        },
+    },
+});

package/tests/fixtures/agents-api/agents/plain.agent.ts

@@ -0,0 +1,23 @@
+import { define } from "../../../../index";
+
+/**
+ * Public agent — `generate` is allowed without a token. Declares no memory and
+ * no `api.object`, to exercise `AGENT_NO_MEMORY` / `AGENT_NO_OBJECT_SCHEMA`.
+ */
+export default define.Agent({
+    id: "plain",
+    description: "A plain agent with no memory and no object schema.",
+    instructions: "You are a plain agent.",
+    provider: {
+        model: "test-model",
+        protocol: "openai",
+        apiKey: "test-key",
+        baseUrl: Bun.env.AGENT_API_TEST_URL ?? "http://127.0.0.1:1",
+        options: { retries: 0 },
+    },
+    api: {
+        // public on purpose: `object` also needs a rule so the *missing schema*
+        // error can be exercised (otherwise the action is denied first)
+        access: { generate: true, object: true },
+    },
+});

package/tests/fixtures/agents-api/agents/private.agent.ts

@@ -0,0 +1,15 @@
+import { define } from "../../../../index";
+
+/** Declares no `api` at all — every action must be denied (secure by default). */
+export default define.Agent({
+    id: "private",
+    description: "Not exposed over HTTP.",
+    instructions: "You are a private agent.",
+    provider: {
+        model: "test-model",
+        protocol: "openai",
+        apiKey: "test-key",
+        baseUrl: Bun.env.AGENT_API_TEST_URL ?? "http://127.0.0.1:1",
+        options: { retries: 0 },
+    },
+});

package/tests/fixtures/agents-api/collections/notes.model.ts

@@ -0,0 +1,26 @@
+import { define } from "../../../../index";
+
+/**
+ * A collection whose hook uses `agents` — proving the LLM registry is injected
+ * into the hook context exactly like `rest` and `io`.
+ *
+ * The observation is published on `globalThis` (the test reads it back): a hook
+ * must not stuff arbitrary keys into `meta.data`, the collection schema rejects
+ * them (`allowUnknown: false`).
+ */
+export default define.Collection({
+    slug: "notes",
+    fields: [{ name: "title", type: "string" }],
+    hooks: {
+        beforeOperation: define.Hook(async ({ agents, api, rest, meta }) => {
+            if (meta.action !== "insertOne") return;
+            (globalThis as any).__agentsHookProbe = {
+                ids: agents.ids().sort(),
+                bound: agents.get("assistant")?.getRest() === rest,
+                // The in-process facade, bound to the same `rest`
+                slug: api.collection("notes").getSlug(),
+                notes: await api.collection("notes").countDocuments(),
+            };
+        }),
+    },
+});

package/tests/fixtures/agents-api/routes/probe.route.ts

@@ -0,0 +1,21 @@
+import { define } from "../../../../index";
+
+/** A route reading the LLM registry **and the in-process facade** from its context. */
+export default define.Route({
+    method: "GET",
+    path: "/probe",
+    handler: async ({ agents, api, rest }) => Response.json({
+        agents: agents.ids().sort(),
+        hasAssistant: !!agents.get("assistant"),
+        // `api` groups the same calls as `rest` — bound and namespaced
+        slug: api.collection("notes").getSlug(),
+        notes: await api.collection("notes").countDocuments(),
+        sameAsRest: (await api.collection("notes").find()) .length === (await rest.find("notes")).length,
+        agentBound: api.agent("assistant")?.getRest() === rest,
+        unknownAgent: api.agent("ghost"),
+        vars: typeof api.vars.get,
+        serviceRun: typeof api.service("probe").run,
+        serviceCall: await api.service("probe").run("echo", { from: "route" }),
+        fileUrl: api.files.url("invoices", "f1.pdf", { width: 800 }),
+    }),
+});

package/tests/fixtures/agents-api/services/probe.service.ts

@@ -0,0 +1,19 @@
+import { define } from "../../../../index";
+
+/** A service action reading the LLM registry and the facade from its context. */
+export default define.Service({
+    name: "probe",
+    enabled: true,
+    actions: {
+        check: async ({ agents, api, rest }) => ({
+            agents: agents.ids().sort(),
+            hasAssistant: !!agents.get("assistant"),
+            bound: agents.get("assistant")?.getRest() === rest,
+            tenant: rest.tenant_id,
+            // `api.service(name).run` is the grouped `rest.runService`
+            nested: await api.service("probe").run("echo", { from: "api" }),
+            varType: typeof api.vars.get,
+        }),
+        echo: async ({ data }) => data,
+    },
+});

package/tests/fixtures/attachment/data.csv

@@ -0,0 +1,2 @@
+ref,total
+A-1,99

package/tests/fixtures/fake-provider.ts

@@ -0,0 +1,128 @@
+/**
+ * Fake model providers for the agent tests — one local HTTP endpoint per
+ * protocol, recording what the runtime sent.
+ *
+ * Shared by `agent.test.ts` (runtime) and `agents-api.test.ts` (HTTP surface),
+ * so a change in the wire format is fixed in one place.
+ */
+
+export type Recorded = { path: string; body: any; headers: Record<string, string> };
+
+export type Fake = {
+    requests: Recorded[];
+    url: string;
+    hits: () => number;
+    stop: () => void;
+};
+
+/** A local endpoint that records the requests and answers from `handler`. */
+export function fakeProvider(handler: (body: any, req: Request, hits: number) => Response | Promise<Response>): Fake {
+    const requests: Recorded[] = [];
+    let hits = 0;
+    const server = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: async (req) => {
+            const body = await req.json().catch(() => null);
+            requests.push({
+                path: new URL(req.url).pathname,
+                body,
+                headers: Object.fromEntries(req.headers.entries()),
+            });
+            hits += 1;
+            return handler(body, req, hits);
+        },
+    });
+    return {
+        requests,
+        url: `http://127.0.0.1:${server.port}`,
+        hits: () => hits,
+        stop: () => server.stop(true),
+    };
+}
+
+/** Typed element access (`noUncheckedIndexedAccess` is on). */
+export function at<T>(list: T[], index = 0): T {
+    const item = list[index];
+    if (item === undefined) throw new Error(`No element #${index} (length ${list.length})`);
+    return item;
+}
+
+export function request(provider: Fake, index = 0): Recorded {
+    const recorded = provider.requests[index];
+    if (!recorded) throw new Error(`No request #${index} was recorded (got ${provider.requests.length})`);
+    return recorded;
+}
+
+export const USAGE = { prompt_tokens: 11, completion_tokens: 4, total_tokens: 15 };
+export const A_USAGE = { input_tokens: 13, output_tokens: 6 };
+
+/** An SSE response from a list of already-serialized events. */
+export function sse(events: string[]): Response {
+    return new Response(events.map((event) => `data: ${event}\n\n`).join(""), {
+        headers: { "Content-Type": "text/event-stream" },
+    });
+}
+
+// ─── OpenAI-compatible ───────────────────────────────────────────────────
+
+export function openaiText(text: string, finishReason = "stop"): Response {
+    return Response.json({
+        choices: [{ message: { role: "assistant", content: text }, finish_reason: finishReason }],
+        usage: USAGE,
+    });
+}
+
+export function openaiTool(name: string, args: any, id = "call_1"): Response {
+    return Response.json({
+        choices: [{
+            message: {
+                role: "assistant",
+                content: null,
+                tool_calls: [{ id, type: "function", function: { name, arguments: JSON.stringify(args) } }],
+            },
+            finish_reason: "tool_calls",
+        }],
+        usage: USAGE,
+    });
+}
+
+export function openaiStream(pieces: string[]): Response {
+    const events = pieces.map((text) => JSON.stringify({ choices: [{ delta: { content: text } }] }));
+    events.push(JSON.stringify({ choices: [], usage: USAGE }));
+    events.push(JSON.stringify({ choices: [{ delta: {}, finish_reason: "stop" }] }));
+    events.push("[DONE]");
+    return sse(events);
+}
+
+// ─── Anthropic ───────────────────────────────────────────────────────────
+
+export function anthropicText(text: string, stopReason = "end_turn"): Response {
+    return Response.json({
+        content: [{ type: "text", text }],
+        stop_reason: stopReason,
+        usage: A_USAGE,
+    });
+}
+
+export function anthropicTool(name: string, input: any, id = "toolu_1"): Response {
+    return Response.json({
+        content: [{ type: "tool_use", id, name, input }],
+        stop_reason: "tool_use",
+        usage: A_USAGE,
+    });
+}
+
+export function anthropicStream(pieces: string[]): Response {
+    const events: string[] = [
+        JSON.stringify({ type: "message_start", message: { usage: { input_tokens: 9, output_tokens: 0 } } }),
+        JSON.stringify({ type: "content_block_start", index: 0, content_block: { type: "text", text: "" } }),
+    ];
+    for (const text of pieces) {
+        events.push(JSON.stringify({ type: "content_block_delta", index: 0, delta: { type: "text_delta", text } }));
+    }
+    events.push(JSON.stringify({ type: "content_block_stop", index: 0 }));
+    events.push(JSON.stringify({ type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 5 } }));
+    events.push(JSON.stringify({ type: "message_stop" }));
+    return sse(events);
+}

package/tests/fixtures/repl-only/app.ts

@@ -18,6 +18,9 @@ await bootApp({
         database: { uri: Bun.env.RO_SRC ?? "mongodb://localhost:27017/_RO_SRC" },
         replication: {
             enabled: true,
+            // Boot capabilities are under test here, not the replication engine:
+            // the scan mode keeps the assertions deterministic
+            mode: "scan",
             runOnBoot: true,
             schedule: { interval: "1h" },
             destinations: [{ id: "backup", uri: Bun.env.RO_DST ?? "mongodb://localhost:27017/_RO_DST" }],

package/tests/fixtures/replication-meta/agents/chat.agent.ts

@@ -0,0 +1,16 @@
+import { define, agents } from "../../../../index";
+
+/**
+ * The collection this tenant names for its agent memory. The loader publishes it
+ * (`cfg.agentMemories`), so the replication engine copies it like a declared
+ * collection — `replication.exclude: ['memory']` is the opt-out.
+ */
+export const AGENT_THREADS = "agent_threads";
+
+export default define.Agent({
+    id: "chat",
+    description: "Fixture agent whose memory lives in a tenant-named collection.",
+    instructions: "Fixture agent — no model call is ever made in these tests.",
+    provider: { model: "test-model", protocol: "openai", apiKey: "fixture" },
+    memory: new agents.memory.Mongo({ collection: AGENT_THREADS }),
+});

package/tests/fixtures/replication-meta/collections/counters.model.ts

@@ -0,0 +1,13 @@
+// Test fixture — a collection whose replication key is a **number** (not a date).
+// The delete guard must still match on the destination.
+export default {
+    _isCollection_: true,
+    _isTimeSerie_: false,
+    type: "document",
+    slug: "counters",
+    fields: [
+        { name: "seq", type: "number" },
+        { name: "title", type: "string" },
+    ],
+    replication: { enabled: true, key: "seq" },
+};

package/tests/fixtures/replication-meta/collections/orders.model.ts

@@ -0,0 +1,9 @@
+// Test fixture — a declared collection that opted into replication.
+export default {
+    _isCollection_: true,
+    _isTimeSerie_: false,
+    type: "document",
+    slug: "orders",
+    fields: [{ name: "title", type: "string" }],
+    replication: { enabled: true },
+};

package/tests/fixtures/replication-meta/workflows/run.workflow.ts

@@ -0,0 +1,8 @@
+// Test fixture — a workflow whose runs must follow the data to the destination.
+export default {
+    _isWorkflow_: true,
+    id: "run",
+    name: "Run",
+    version: 1,
+    steps: [{ id: "one", exec: async () => ({ ok: true }) }],
+};

package/tests/fixtures/skills-tenant/agents/docs.agent.ts

@@ -0,0 +1,23 @@
+import { define } from "../../../../index";
+
+/**
+ * Fixture — an agent whose system prompt carries skills, declared every way a
+ * source can be: a glob of a folder, one file, a regex over the tenant, and the
+ * `SKILL.md` directory layout.
+ *
+ * The last two patterns overlap on purpose (`./docs/*.md` and the `docs` regex):
+ * a file matched twice is one skill.
+ */
+export default define.Agent({
+    id: "docs",
+    description: "Answers from the tenant's own documentation.",
+    instructions: "Answer from the documentation you were given.",
+    provider: { model: "claude-test", protocol: "anthropic", apiKey: "fixture-key" },
+    skills: [
+        "./docs/*.md",
+        "./guide/ml.md",
+        /^docs\/.*\.md$/,
+        /^runbooks\/.*$/,
+        "./guides/**/SKILL.md",
+    ],
+});

package/tests/fixtures/skills-tenant/agents/incomplete.agent.ts

@@ -0,0 +1,14 @@
+import { define } from "../../../../index";
+
+/**
+ * Fixture — an agent whose skill is malformed (`broken/no-name.md` has no `name`).
+ *
+ * A broken skill refuses **this agent** at load, and must not hide the others.
+ */
+export default define.Agent({
+    id: "incomplete",
+    description: "Carries a skill that does not follow the format.",
+    instructions: "Nothing to see here.",
+    provider: { model: "claude-test", protocol: "anthropic", apiKey: "fixture-key" },
+    skills: ["./broken/no-name.md"],
+});

package/tests/fixtures/skills-tenant/broken/bad-name.md

@@ -0,0 +1,6 @@
+---
+name: Bad Name
+description: The name is not kebab-case.
+---
+
+Body.

package/tests/fixtures/skills-tenant/broken/dup-a.md

@@ -0,0 +1,6 @@
+---
+name: same-name
+description: Two files of one agent cannot share a name — this is the first.
+---
+
+Body.

package/tests/fixtures/skills-tenant/broken/dup-b.md

@@ -0,0 +1,6 @@
+---
+name: same-name
+description: Two files of one agent cannot share a name — this is the second.
+---
+
+Body.

package/tests/fixtures/skills-tenant/broken/empty-body.md

@@ -0,0 +1,4 @@
+---
+name: empty-body
+description: Frontmatter only — nothing for the model to read.
+---

package/tests/fixtures/skills-tenant/broken/long-compat.md

@@ -0,0 +1,7 @@
+---
+name: long-compat
+description: A skill whose compatibility line is too long.
+compatibility: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+---
+
+Body.

package/tests/fixtures/skills-tenant/broken/long-description.md

@@ -0,0 +1,6 @@
+---
+name: long-description
+description: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+---
+
+Body.

package/tests/fixtures/skills-tenant/broken/mismatch/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: other-name
+description: The parent directory is 'mismatch' — a SKILL.md must be named after it.
+---
+
+Body.

package/tests/fixtures/skills-tenant/broken/no-description.md

@@ -0,0 +1,5 @@
+---
+name: no-description
+---
+
+A skill without a description — the model would never know when to read it.

package/tests/fixtures/skills-tenant/broken/no-name.md

@@ -0,0 +1,5 @@
+---
+description: A skill without a name — the frontmatter is incomplete.
+---
+
+Body.

package/tests/fixtures/skills-tenant/broken/plain.md

@@ -0,0 +1,4 @@
+# No frontmatter at all
+
+A plain markdown file is refused: without a name and a description it cannot be
+injected (the model would not know what it is).

package/tests/fixtures/skills-tenant/broken/unknown-key.md

@@ -0,0 +1,9 @@
+---
+name: unknown-keys
+description: Extra frontmatter keys are kept out of the prompt, not refused.
+version: 3
+author: platform
+metadata: { owner: platform }
+---
+
+Body.

package/tests/fixtures/skills-tenant/docs/pdf-forms.md

@@ -0,0 +1,18 @@
+---
+name: pdf-forms
+description: Fill, flatten and merge PDF forms. Use it for any AcroForm work.
+license: MIT
+compatibility: Needs the `pdftk` binary on the host.
+metadata:
+  owner: platform
+  reviewed: 2026-09-24
+allowed-tools: read_pdf write_pdf
+---
+
+# Filling a form
+
+1. Dump the fields: `pdftk form.pdf dump_data_fields`.
+2. Build the FDF, then fill it: `pdftk form.pdf fill_form data.fdf output out.pdf`.
+3. Flatten: `pdftk out.pdf output flat.pdf flatten`.
+
+Never flatten before the signature step — it makes the form read-only.

package/tests/fixtures/skills-tenant/guide/ml.md

@@ -0,0 +1,9 @@
+---
+name: ml-conventions
+description: The tenant's ML conventions — feature naming, training splits, review gates.
+---
+
+# Conventions
+
+- Features are `snake_case`, prefixed by their source (`crm_`, `billing_`).
+- A model only ships with a held-out split and a written evaluation.

package/tests/fixtures/skills-tenant/guides/pdf/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: pdf
+description: Everything about the tenant's PDF pipeline, from templating to archiving.
+---
+
+# PDF pipeline
+
+The `name` matches the parent directory, which is what the `SKILL.md` layout
+requires.

package/tests/fixtures/skills-tenant/runbooks/incident.md

@@ -0,0 +1,9 @@
+---
+name: incident-response
+description: What to do when production breaks — paging, comms, post-mortem.
+---
+
+# Incident response
+
+1. Acknowledge the page within five minutes.
+2. Open a channel, name an incident commander, keep a timeline.

package/tests/fixtures/skills-tenant/runbooks/notes.txt

@@ -0,0 +1,2 @@
+This file is not markdown — a regex that walks the tenant picks it up, and the
+loader must skip it (logged) instead of taking the agent down.

package/tests/fixtures/vars-tenant/vars/private.var.ts

@@ -1,6 +1,9 @@
-// Test fixture — a namespace WITHOUT `api.access` (must be denied over HTTP).
+// Test fixture — a namespace WITHOUT `api.access` (must be denied over HTTP),
+// and which explicitly opts OUT of replication.
 export default {
     _isVars_: true,
     namespace: "private",
     vars: { secret: "shh" },
+    // Framework collections are replicated by default: opting out is explicit
+    replication: { enabled: false },
 };

package/tests/fixtures/workflow-engine/workflows/failing.workflow.ts

@@ -0,0 +1,34 @@
+// Test fixture — `b` always fails, `a` must be compensated (once, never twice).
+// Also proves the step ctx `rest` is a real tenant client.
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "failing",
+    name: "Failing",
+    version: 1,
+    steps: [
+        {
+            id: "a",
+            exec: async ({ rest }: any) => {
+                state.log.push(`failing:a:rest=${typeof rest?.find === "function" ? "client" : "engine"}`);
+                // A sub-workflow, through the client handed to the step
+                await rest.workflow.run("simple", { echo: "sub" });
+                state.log.push("failing:a:sub-workflow-done");
+                return { a: 1 };
+            },
+        },
+        { id: "b", exec: async () => { state.log.push("failing:b"); throw new Error("boom-b"); } },
+        { id: "c", exec: async () => { state.log.push("failing:c"); return { c: 1 }; } },
+    ],
+    compensations: [
+        {
+            id: "undo-a",
+            depend: ["a"],
+            exec: async () => {
+                state.attempts["undo-a"] = (state.attempts["undo-a"] ?? 0) + 1;
+                state.log.push(`failing:undo-a:${state.attempts["undo-a"]}`);
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/flaky.workflow.ts

@@ -0,0 +1,23 @@
+// Test fixture — a step that fails until `data.failUntil` attempts are reached,
+// with retries. Used to prove a transient failure does not roll the saga back.
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "flaky",
+    name: "Flaky",
+    version: 1,
+    steps: [
+        {
+            id: "unstable",
+            retries: 2,
+            backoffMs: 1,
+            exec: async ({ data }: any) => {
+                const n = (state.attempts.unstable = (state.attempts.unstable ?? 0) + 1);
+                state.log.push(`flaky:attempt:${n}`);
+                if (n <= (data?.failUntil ?? 0)) throw new Error(`transient failure ${n}`);
+                return { attempts: n };
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/hang.workflow.ts

@@ -0,0 +1,17 @@
+// Test fixture — a step that outlives its `timeout` (150ms vs 1s by default).
+export default {
+    _isWorkflow_: true,
+    id: "hang",
+    name: "Hang",
+    version: 1,
+    steps: [
+        {
+            id: "hang",
+            timeout: "150ms",
+            exec: async ({ data }: any) => {
+                await new Promise((resolve) => setTimeout(resolve, data?.ms ?? 1000));
+                return { done: true };
+            },
+        },
+    ],
+};