@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.11

package/docs/testing.md

@@ -11,22 +11,22 @@ Lean on unit tests for the day-to-day feedback loop — they run fast and exerci
 
 Unit-test entrypoints exposed by the SDK:
 
-- `resolver.body({ input, user, env })` — invoke a resolver
-- `workflowJob.body(input, { env })` — invoke a workflow job body directly
-- `workflowJob.trigger(input)` — chain a workflow job through the workflow runtime
+- `resolver.body({ input, caller, invoker, env })` — invoke a resolver
+- `workflowJob.body(input, { env, invoker })` — invoke a workflow job body directly
+- `workflowJob.start(input)` — chain a workflow job through the workflow runtime
 - `runWorkflowLocally(workflow, args)` — run a workflow chain locally with real job bodies
-- `executor.operation.body(args)` — invoke a function-kind executor
+- `executor.operation.body({ ...args, invoker })` — invoke a function-kind executor
 
-Helpers under `@tailor-platform/sdk/test`:
+For anonymous direct calls:
 
-- `unauthenticatedTailorUser` — default `user` value for resolver contexts
+- Pass `null` for anonymous `caller` / `invoker` context in direct unit tests.
 
 Platform API mocks under `@tailor-platform/sdk/vitest` (for use with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below):
 
 - `mockTailordb` — TailorDB query stubs and call recording
 - `mockWorkflow` — `tailor.workflow` job / wait / resolve mocks
 - `runWorkflowLocally` — local full-chain workflow runner
-- `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv` — corresponding platform API mocks
+- `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger` — corresponding platform API mocks
 
 For tighter alignment with the production runtime — Node.js module blocking, Web-only globals, and platform API mocks — pair the resolver helpers with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below.
 
@@ -63,25 +63,30 @@ export default defineConfig({
 
 ### Acquiring mocks with `using`
 
-Each mock controller (`mockTailordb`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
+Each mock controller (`mockTailordb`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
 
 ```typescript
 import { mockTailordb } from "@tailor-platform/sdk/vitest";
 
 test("...", () => {
   using db = mockTailordb();
-  db.enqueueResult({ age: 30 });
+  db.onQuery(/SELECT age/).returnsRows([{ age: 30 }]);
   // …
 }); // reset automatically here
 ```
 
-The mock functions are also exposed directly (e.g. `db.queryObject`, `wf.triggerJobFunction`) so you can assert on them with `expect(...).toHaveBeenCalledWith(...)`.
+Runtime operations are exposed as typed Vitest mocks wherever the platform API has a stable operation shape. For example, use `file.download.mockResolvedValue(...)`, `iconv.decode.mockReturnValue(...)`, or `wf.job(myJob).mockResolvedValue(...)`, then assert with native Vitest matchers. Service-specific helpers cover stateful fixtures and query matching.
+
+Every controller provides two lifecycle methods when manual reuse is useful:
+
+- `clear()` removes call history but preserves configured behavior.
+- `reset()` removes call history and configured behavior, restoring the controller's default behavior.
 
 > **Requirements:** `using` requires TypeScript ≥ 5.2 and a runtime that provides `Symbol.dispose` (Node ≥ 20.4 — the SDK already targets Node ≥ 22, and Vitest's transformer downlevels the syntax for you).
 >
 > **Acquire what you use:** a namespace is only mocked while you hold it with `using`, so code under test that calls a platform API (e.g. `tailor.workflow`, `tailordb.Client`) must run inside a test that has acquired the matching `mockX()`. The error classes and `tailor.context` are always present.
 >
-> **Seeded secrets survive:** secrets seeded from `tailor.config.ts` stay available across tests; a per-test `mockSecretmanager().setSecrets(...)` override applies only within that test.
+> **Seeded secrets survive:** secrets seeded from `tailor.config.ts` stay available across tests; per-test fixtures passed to `mockSecretmanager({ secrets: ... })` apply only within that test.
 
 ### TailorDB Mock
 
@@ -92,14 +97,19 @@ import { mockTailordb } from "@tailor-platform/sdk/vitest";
 
 test("resolver queries the database", async () => {
   using db = mockTailordb();
-  // Order-based: stage rows for each upcoming query in one call
-  db.enqueueResults(
+  // Use an explicit queue when transaction order is part of the test.
+  db.enqueueRows(
     [], // BEGIN (empty result)
     [{ age: 30 }], // SELECT (one row)
     [], // COMMIT
   );
 
-  const result = await resolver.body({ input: { email: "test@example.com" } });
+  const result = await resolver.body({
+    input: { email: "test@example.com" },
+    caller: null,
+    invoker: null,
+    env: {},
+  });
 
   expect(result).toEqual({ oldAge: 30, newAge: 31 });
   expect(db.executedQueries).toHaveLength(3);
@@ -107,75 +117,85 @@ test("resolver queries the database", async () => {
 });
 ```
 
-Three response modes:
-
-- **`enqueueResult(...rows)`** — Order-based, single query. Arguments are the row objects returned by the next `queryObject` call (`enqueueResult()` for empty, `enqueueResult({ id: "1" })` for one row, `enqueueResult({ a: 1 }, { a: 2 })` for multiple rows). Consumed in FIFO order.
-- **`enqueueResults(...rowsArrays)`** — Order-based, multiple queries. Each argument is a rows array for one upcoming query. Equivalent to calling `enqueueResult` for each entry but easier to read for transactional sequences.
-- **`setQueryResolver((query, params) => rows)`** — Content-based fallback. Called when the queue is empty.
+Match queries by SQL text, a regular expression, SQL plus parameters, or a predicate. The most recently registered matcher wins:
 
 ```typescript
 test("content-based mock", async () => {
   using db = mockTailordb();
-  db.setQueryResolver((query) => {
-    if (query.includes("SELECT")) return [{ id: "1", name: "test" }];
-    return [];
+  db.onQuery({ sql: /FROM users/i, params: ["1"] }).returnsRows([{ id: "1", name: "test" }]);
+  db.onQuery(/FROM audit_logs/i)
+    .returnsRowsOnce([{ id: "first" }])
+    .returnsRows([{ id: "later" }]);
+
+  const result = await resolver.body({
+    input: { userId: "1" },
+    caller: null,
+    invoker: null,
+    env: {},
   });
 
-  const result = await resolver.body({ input: { userId: "1" } });
-
   expect(db.executedQueries[0].query).toContain("SELECT");
 });
 ```
 
+Within one `mockTailordb()` instance, use either `onQuery()` matchers or a direct `queryObject.mockImplementation()` override. A direct override replaces matcher-based behavior, so do not combine the two styles.
+
+`returnsRowsOnce` and `rejectsOnce` configure one-time responses before the persistent `returnsRows` or `rejects` response. `enqueueRows(...rowArrays)` remains available for transaction sequences whose exact call order is under test. The existing `enqueueResult`, `enqueueResults`, and `setQueryResolver` helpers remain supported for compatibility.
+
+Pass `{ onUnhandled: "error" }` to make an unmatched query fail instead of returning an empty result.
+
 ### Workflow Mock
 
-Workflow job `.trigger()` calls use the platform workflow runtime. Acquire `mockWorkflow()` when you want to provide trigger responses with `setJobHandler` / `enqueueResult` or assert on `triggeredJobs`. If no response is configured, the mock throws so missing job mocks fail loudly:
+Workflow job `.start()` calls use the platform workflow runtime. Acquire `mockWorkflow()` when you want to provide start responses with `setJobHandler` / `enqueueResult` or assert on `startedJobs`. If no response is configured, the mock throws so missing job mocks fail loudly. Use `job(definition)` or `workflow(definition)` to get a stable, fully typed Vitest mock for one definition:
 
 ```typescript
 import { mockWorkflow } from "@tailor-platform/sdk/vitest";
+import { processPayment, validateOrder } from "./jobs";
 
-test("workflow triggers jobs", async () => {
+test("workflow starts jobs", async () => {
   using wf = mockWorkflow();
-  wf.setJobHandler((jobName, args) => {
-    if (jobName === "validate-order") return { valid: true };
-    if (jobName === "process-payment") return { txnId: "txn-1" };
-    return null;
-  });
+  const validate = wf.job(validateOrder);
+  const payment = wf.job(processPayment);
+  validate.mockResolvedValue({ valid: true });
+  payment.mockResolvedValue({ txnId: "txn-1" });
 
   const result = await main({ input: { orderId: "o-1" } });
 
-  expect(wf.triggeredJobs).toEqual([
-    { jobName: "validate-order", args: { orderId: "o-1" } },
-    { jobName: "process-payment", args: { orderId: "o-1" } },
-  ]);
+  expect(validate).toHaveBeenCalledWith({ orderId: "o-1" });
+  expect(payment).toHaveBeenCalledWith({ orderId: "o-1" });
 });
 ```
 
-`mockWorkflow()` also supports order-based responses:
+Unconfigured definition mocks continue to run their real implementations. The lower-level `execJobFunction`, `startWorkflow`, `resumeWorkflowExecution`, `wait`, and `resolve` mocks and the existing `setJobHandler`, `enqueueResult`, `enqueueResults`, and call-record helpers remain available.
+
+Use `waitPoint(definition)` for typed wait-point control:
 
 ```typescript
 using wf = mockWorkflow();
+const approvalMock = wf.waitPoint(approvalWaitPoint);
 
-// Single response for the next triggerJobFunction call
-wf.enqueueResult({ valid: true });
+approvalMock.wait.mockResolvedValue({ approved: true });
+await approvalWaitPoint.wait({ message: "Please approve" });
 
-// Multiple responses for subsequent calls (FIFO)
-wf.enqueueResults({ valid: true }, { txnId: "txn-1" });
+expect(approvalMock.wait).toHaveBeenCalledWith({ message: "Please approve" });
 ```
 
+Use `wf.setEnv(...)` when locally-run workflow job bodies need configuration values. Per-run `runWorkflowLocally(..., { env })` options take precedence over the mock's env.
+
 ### SecretManager Mock
 
 ```typescript
 import { mockSecretmanager } from "@tailor-platform/sdk/vitest";
 
 test("reads secrets from vault", async () => {
-  using sm = mockSecretmanager();
-  sm.setSecrets({
-    "my-vault": { API_KEY: "sk-123", DB_PASS: "secret" },
+  using sm = mockSecretmanager({
+    secrets: { "my-vault": { API_KEY: "sk-123" } },
   });
+  sm.setSecret("my-vault", "API_KEY", "override");
+  sm.mergeSecrets("my-vault", { DB_PASS: "secret" });
 
   const key = await tailor.secretmanager.getSecret("my-vault", "API_KEY");
-  expect(key).toBe("sk-123");
+  expect(key).toBe("override");
   expect(sm.calls).toEqual([{ method: "getSecret", vault: "my-vault", name: "API_KEY" }]);
 });
 ```
@@ -186,65 +206,65 @@ test("reads secrets from vault", async () => {
 import { mockAuthconnection } from "@tailor-platform/sdk/vitest";
 
 test("returns configured token", async () => {
-  using ac = mockAuthconnection();
-  ac.setTokens({
-    google: { access_token: "ya29.xxx", expires_in: 3600 },
+  using ac = mockAuthconnection({
+    tokens: { google: { access_token: "ya29.xxx" } },
+    onUnhandled: "error",
   });
+  ac.setToken("google", { access_token: "replacement" });
 
   const token = await tailor.authconnection.getConnectionToken("google");
-  expect(token.access_token).toBe("ya29.xxx");
+  expect(token.access_token).toBe("replacement");
 });
 ```
 
-When no token is configured for a connection, it returns `{ access_token: "mock-token" }`.
+By default, an unconfigured connection returns `{ access_token: "mock-token" }`. Pass `onUnhandled: "error"` to fail instead.
 
 ### IDP Mock
 
 ```typescript
 import { mockIdp } from "@tailor-platform/sdk/vitest";
 
-test("resolver-based", async () => {
-  using idp = mockIdp();
-  idp.setResolver((method, args) => {
-    if (method === "user") return { id: "u-1", name: "alice", disabled: false };
-    return null; // falls back to defaults
+test("namespace-specific mock", async () => {
+  using idp = mockIdp({ onUnhandled: "error" });
+  const customerIdp = idp.namespace("my-ns");
+  customerIdp.user.mockResolvedValue({
+    id: "u-1",
+    name: "alice",
+    disabled: false,
+    mfaEnrolled: false,
+    mfaFactorIds: [],
   });
 
   const client = new tailor.idp.Client({ namespace: "my-ns" });
   const user = await client.user("u-1");
   expect(user.name).toBe("alice");
-});
-
-test("queue-based", async () => {
-  using idp = mockIdp();
-  idp.enqueueResult({ id: "u-1", name: "alice", disabled: false });
-
-  const client = new tailor.idp.Client({ namespace: "my-ns" });
-  const user = await client.user("u-1");
-  expect(user.name).toBe("alice");
-  expect(idp.calls).toMatchObject([{ method: "user", namespace: "my-ns" }]);
+  expect(customerIdp.user).toHaveBeenCalledWith("u-1");
 });
 ```
 
+Each namespace exposes typed mocks for `users`, `user`, `userByName`, `createUser`, `updateUser`, `deleteUser`, `sendPasswordResetEmail`, and `unenrollMfa`. The existing resolver, queue, and aggregate `calls` APIs remain supported.
+
 ### File Mock
 
 ```typescript
 import { mockFile } from "@tailor-platform/sdk/vitest";
 
 test("mock file download", async () => {
-  using file = mockFile();
-  file.enqueueResult({
+  using file = mockFile({ onUnhandled: "error" });
+  file.download.mockResolvedValue({
     data: new Uint8Array([1, 2, 3]),
     metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc", lastUploadedAt: "" },
   });
 
   const result = await tailordb.file.download("ns", "Doc", "attachment", "r-1");
   expect(result.data).toEqual(new Uint8Array([1, 2, 3]));
-  expect(file.calls).toMatchObject([{ method: "download", recordId: "r-1" }]);
+  expect(file.download).toHaveBeenCalledWith("ns", "Doc", "attachment", "r-1");
 });
 ```
 
-For `downloadStream`, enqueue a `FileDownloadStreamResponse` object with a `ReadableStream` body and metadata:
+All File operations are typed Vitest mocks: `upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, and `uploadStream`. Use native methods such as `mockResolvedValueOnce` and `mockRejectedValueOnce` to model success and failure. The existing resolver, queue, and aggregate `calls` APIs remain supported.
+
+For `downloadStream`, configure a `FileDownloadStreamResponse` object with a `ReadableStream` body and metadata:
 
 ```typescript
 test("mock file download stream", async () => {
@@ -255,7 +275,7 @@ test("mock file download stream", async () => {
       controller.close();
     },
   });
-  file.enqueueResult({
+  file.downloadStream.mockResolvedValue({
     body,
     metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc", lastUploadedAt: "" },
   });
@@ -265,28 +285,6 @@ test("mock file download stream", async () => {
 });
 ```
 
-For the deprecated `openDownloadStream`, enqueue an iterable of `StreamValue` items — `metadata`, one or more `chunk` items, and a terminal `complete`. Raw `Uint8Array` / `ArrayBuffer` chunks are rejected so tests stay aligned with the platform's structured stream contract.
-
-```typescript
-test("mock file download stream (deprecated openDownloadStream)", async () => {
-  using file = mockFile();
-  file.enqueueResult([
-    {
-      type: "metadata",
-      metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc" },
-    },
-    { type: "chunk", data: new Uint8Array([1, 2]), position: 0 },
-    { type: "chunk", data: new Uint8Array([3]), position: 2 },
-    { type: "complete" },
-  ]);
-
-  const stream = await tailordb.file.openDownloadStream("ns", "Doc", "attachment", "r-1");
-  const items = [];
-  for await (const item of stream) items.push(item);
-  expect(items).toHaveLength(4);
-});
-```
-
 ### Iconv Mock
 
 ```typescript
@@ -294,10 +292,7 @@ import { mockIconv } from "@tailor-platform/sdk/vitest";
 
 test("mock encoding conversion", () => {
   using iconv = mockIconv();
-  iconv.setResolver((method, args) => {
-    if (method === "decode") return "decoded-text";
-    return null; // falls back to default empty string
-  });
+  iconv.decode.mockReturnValue("decoded-text");
 
   const result = tailor.iconv.decode(new Uint8Array([0x48, 0x69]), "UTF-8");
   expect(result).toBe("decoded-text");
@@ -305,6 +300,48 @@ test("mock encoding conversion", () => {
 });
 ```
 
+`convert`, `convertBuffer`, `decode`, `encode`, and `encodings` are all typed Vitest mocks. Pass `{ onUnhandled: "error" }` to fail calls without a configured implementation. The existing resolver and aggregate `calls` APIs remain supported.
+
+### AI Gateway Mock
+
+```typescript
+import { mockAigateway } from "@tailor-platform/sdk/vitest";
+
+test("resolves an AI Gateway URL", async () => {
+  using aigateway = mockAigateway({
+    urls: { "my-aigateway": "https://my-aigateway.example.com" },
+  });
+  aigateway.setUrl("my-aigateway", "https://replacement.example.com");
+
+  const { url } = await tailor.aigateway.get("my-aigateway");
+  expect(url).toBe("https://replacement.example.com");
+  expect(aigateway.calls).toEqual([{ name: "my-aigateway" }]);
+});
+```
+
+Calling `get` for a name that has not been registered throws. `setUrls` remains available when replacing the complete URL fixture.
+
+### Logger Mock
+
+Each method is a `vi.fn`, so assert on it directly. `calls` returns the emitted `debug`/`info`/`warn`/`error` entries in order.
+
+```typescript
+import { mockLogger } from "@tailor-platform/sdk/vitest";
+
+test("logs the processed order", () => {
+  using logger = mockLogger();
+
+  tailor.logger.info("order processed", { orderId: "o-1" });
+
+  expect(logger.info).toHaveBeenCalledWith("order processed", { orderId: "o-1" });
+  expect(logger.calls).toEqual([
+    { severity: "info", message: "order processed", attributes: { orderId: "o-1" } },
+  ]);
+});
+```
+
+Without an explicit `mockLogger()`, `tailor.logger.*` calls are no-ops in the `tailor-runtime` environment (they neither throw nor record).
+
 ### Loading Secrets from Config
 
 Pass a config path to load `defineSecretManager()` values into the mock:
@@ -316,7 +353,7 @@ export default defineConfig({
 });
 ```
 
-This makes `tailor.secretmanager.getSecret("vault", "key")` return the values defined in your config. You can still override with `using sm = mockSecretmanager(); sm.setSecrets(...)` in individual tests: a per-test override applies only within that test, and the config-loaded secrets remain available to every other test.
+This makes `tailor.secretmanager.getSecret("vault", "key")` return the values defined in your config. You can still override with `mockSecretmanager({ secrets: ... })` in individual tests: a per-test overlay applies only within that test, and the config-loaded secrets remain available to every other test.
 
 ### Per-Project Configuration
 
@@ -358,7 +395,7 @@ export default defineConfig({
 
 ## Unit Tests
 
-Unit tests call `.body()` (or `.trigger()`) directly on a resolver, workflow job, or executor and stub any platform-provided globals they touch.
+Unit tests call `.body()` (or `.start()`) directly on a resolver, workflow job, or executor and stub any platform-provided globals they touch.
 
 ### Testing Resolvers
 
@@ -367,7 +404,6 @@ Unit tests call `.body()` (or `.trigger()`) directly on a resolver, workflow job
 For pure logic with no external dependencies, invoke `.body()` directly:
 
 ```typescript
-import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
 import { describe, expect, test } from "vitest";
 import resolver from "../src/resolver/add";
 
@@ -375,7 +411,8 @@ describe("add resolver", () => {
   test("adds two numbers", async () => {
     const result = await resolver.body({
       input: { left: 1, right: 2 },
-      user: unauthenticatedTailorUser,
+      caller: null,
+      invoker: null,
       env: {},
     });
     expect(result).toBe(3);
@@ -391,15 +428,16 @@ Stub the global `tailordb.Client` and queue raw query results in order. Best for
 
 > If you are running with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta), acquire `using db = mockTailordb()` to install and drive the mock `tailordb.Client` instead of `vi.stubGlobal()`.
 
+> The example below uses `aroundAll` / `aroundEach`, which require Vitest ≥ 4.1.
+
 ```typescript
-import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
-import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from "vitest";
+import { aroundAll, aroundEach, describe, expect, test, vi } from "vitest";
 import resolver from "../src/resolver/incrementUserAge";
 
 describe("incrementUserAge resolver", () => {
   const mockQueryObject = vi.fn();
 
-  beforeAll(() => {
+  aroundAll(async (runSuite) => {
     vi.stubGlobal("tailordb", {
       Client: vi.fn(
         class {
@@ -409,9 +447,13 @@ describe("incrementUserAge resolver", () => {
         },
       ),
     });
+    await runSuite();
+    vi.unstubAllGlobals();
+  });
+  aroundEach(async (runTest) => {
+    await runTest();
+    mockQueryObject.mockReset();
   });
-  afterAll(() => vi.unstubAllGlobals());
-  afterEach(() => mockQueryObject.mockReset());
 
   test("increments age inside a transaction", async () => {
     // BEGIN → SELECT → UPDATE → COMMIT
@@ -422,7 +464,8 @@ describe("incrementUserAge resolver", () => {
 
     const result = await resolver.body({
       input: { email: "test@example.com" },
-      user: unauthenticatedTailorUser,
+      caller: null,
+      invoker: null,
       env: {},
     });
 
@@ -493,7 +536,6 @@ describe("decrementUserAge", () => {
 Pass `mock.db` to functions that take a Kysely instance. When a resolver or executor calls `getDB()` internally there is no such seam, so spy the generated `getDB` and point it at the mock:
 
 ```typescript
-import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
 import { createKyselyMock } from "@tailor-platform/sdk/vitest";
 import { describe, expect, test, vi } from "vitest";
 import { getDB, type Namespace } from "../generated/db";
@@ -525,7 +567,8 @@ describe("upsertUsers resolver", () => {
           { name: "Existing", email: "exists@example.com", age: 41 },
         ],
       },
-      user: unauthenticatedTailorUser,
+      caller: null,
+      invoker: null,
       env: { appName: "Resolver Template", version: 1 },
     });
 
@@ -541,39 +584,70 @@ Reach for [`mockTailordb`](#mocking-the-tailordb-client) instead when you want t
 
 #### Resolvers that resume a workflow
 
-Resolvers that call `waitPoint.resolve(...)` delegate to `tailor.workflow.resolve` at runtime. With the `tailor-runtime` environment active, use `mockWorkflow().setResolveHandler` to drive the user-supplied callback and inspect `resolveCalls`:
+Resolvers that call `waitPoint.resolve(...)` delegate to `tailor.workflow.resolve` at runtime. With the `tailor-runtime` environment active, use `mockWorkflow().waitPoint(definition)` to invoke the callback with the payload that originally suspended the job:
 
 ```typescript
-import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
 import { mockWorkflow } from "@tailor-platform/sdk/vitest";
 import { describe, expect, test } from "vitest";
+import { approval } from "../workflow/approval";
 import resolver from "./resolveApproval";
 
 describe("resolveApproval resolver", () => {
   test("resolves approval with approved=true", async () => {
     using wf = mockWorkflow();
-    wf.setResolveHandler((_executionId, _key, callback) => {
-      const result = callback({ message: "Please approve order order-1", orderId: "order-1" });
-      expect(result).toEqual({ approved: true });
+    const approvalMock = wf.waitPoint(approval);
+    approvalMock.setResolvePayload({
+      message: "Please approve order order-1",
+      orderId: "order-1",
     });
 
     const result = await resolver.body({
       input: { executionId: "exec-1", approved: true },
-      user: unauthenticatedTailorUser,
+      caller: null,
+      invoker: null,
       env: {},
     });
 
     expect(result).toEqual({ resolved: true });
-    expect(wf.resolveCalls).toEqual([{ executionId: "exec-1", key: "approval" }]);
+    expect(approvalMock.resolve).toHaveBeenCalledWith("exec-1", expect.any(Function));
   });
 });
 ```
 
-`setResolveHandler` receives `(executionId, key, callback)` and decides whether to invoke the callback — that's how you assert the value returned to the suspended job.
+`setResolvePayload` is typed from the wait-point definition. The lower-level `setResolveHandler` and `resolveCalls` APIs remain available when a test must control several wait points together.
+
+#### Resolvers that resume failed workflows
+
+Resolvers or executors that call `workflow.resumeWorkflowExecution(executionId)` delegate to `tailor.workflow.resumeWorkflowExecution` at runtime. With the `tailor-runtime` environment active, use `mockWorkflow().setResumeHandler` to control the returned execution ID and inspect `resumeWorkflowExecution.mock.calls`:
+
+```typescript
+import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
+import { mockWorkflow } from "@tailor-platform/sdk/vitest";
+import { describe, expect, test } from "vitest";
+import resolver from "./retryFailedWorkflow";
+
+describe("retryFailedWorkflow resolver", () => {
+  test("resumes a failed workflow execution", async () => {
+    using wf = mockWorkflow();
+    wf.setResumeHandler("exec-resumed-123");
+
+    const result = await resolver.body({
+      input: { executionId: "exec-failed-456" },
+      user: unauthenticatedTailorUser,
+      env: {},
+    });
+
+    expect(result).toEqual({ resumedExecutionId: "exec-resumed-123" });
+    expect(wf.resumeWorkflowExecution.mock.calls).toEqual([["exec-failed-456"]]);
+  });
+});
+```
+
+`setResumeHandler` accepts a static string (same execution ID for every call) or a function `(executionId) => string` that computes one per call. By default the mock echoes the input `executionId`.
 
 ### Testing Executors
 
-Function-kind executors expose their handler as `executor.operation.body(args)`. The shape of `args` is determined by the trigger — for example, `recordCreatedTrigger({ type: user })` produces `{ newRecord }` typed against the type's output. GraphQL, webhook, and workflow operation kinds are declarative and don't expose a user-authored body to test.
+Function-kind executors expose their handler as `executor.operation.body(args)`. The shape of `args` is determined by the trigger — for example, `recordCreatedTrigger({ type: user })` produces `{ newRecord }` typed against the type's output, plus runtime fields such as `env`, `actor`, and `invoker`. GraphQL, webhook, and workflow operation kinds are declarative and don't expose a user-authored body to test.
 
 The `executor` template extracts shared DB access into a helper (`shared.ts`) and tests the helper directly against a mocked `tailordb.Client` (same TailorDB-mocking pattern as the resolver section). Executor handlers themselves stay thin and can be tested by spying on the helper:
 
@@ -590,6 +664,14 @@ describe("onUserCreated executor", () => {
       throw new Error("expected function operation");
     }
     await onUserCreated.operation.body({
+      workspaceId: "workspace-1",
+      appNamespace: "app",
+      env: {},
+      actor: null,
+      invoker: null,
+      event: "created",
+      rawEvent: "tailordb.type_record.created",
+      typeName: "User",
       newRecord: {
         id: "user-1",
         name: "Alice",
@@ -614,11 +696,11 @@ To exercise the full chain (executor → helper → TailorDB), drop the spy and
 
 ### Testing Workflow Jobs
 
-Workflow jobs expose the same `.body()` entrypoint as resolvers, plus `.trigger()` for calling them from another job or a test.
+Workflow jobs expose the same `.body()` entrypoint as resolvers, plus `.start()` for calling them from another job or a test.
 
 #### Simple job
 
-Call `.body()` with the input and a stub `{ env: {} }`:
+Call `.body()` with the input and a stub `{ env: {}, invoker: null }`:
 
 ```typescript
 import { describe, expect, test } from "vitest";
@@ -626,46 +708,54 @@ import { validateOrder } from "./order-fulfillment";
 
 describe("validateOrder", () => {
   test("accepts a valid order", () => {
-    const result = validateOrder.body({ orderId: "order-1", amount: 100 }, { env: {} });
+    const result = validateOrder.body(
+      { orderId: "order-1", amount: 100 },
+      { env: {}, invoker: null },
+    );
     expect(result).toEqual({ valid: true, orderId: "order-1" });
   });
 
   test("rejects a non-positive amount", () => {
-    expect(() => validateOrder.body({ orderId: "order-1", amount: 0 }, { env: {} })).toThrow(
-      "Order amount must be positive",
-    );
+    expect(() =>
+      validateOrder.body({ orderId: "order-1", amount: 0 }, { env: {}, invoker: null }),
+    ).toThrow("Order amount must be positive");
   });
 });
 ```
 
-#### Jobs that trigger other jobs
+#### Jobs that start other jobs
 
-Spy on each dependent job's `.trigger()` to replace it with a deterministic result:
+Use `mockWorkflow().job(definition)` to replace dependent jobs with deterministic results:
 
 ```typescript
-import { describe, expect, test, vi } from "vitest";
+import { mockWorkflow } from "@tailor-platform/sdk/vitest";
+import { describe, expect, test } from "vitest";
 import { fulfillOrder, processPayment, sendConfirmation, validateOrder } from "./order-fulfillment";
 
 describe("fulfillOrder", () => {
   test("chains validate → pay → confirm", async () => {
-    using _validateSpy = vi.spyOn(validateOrder, "trigger").mockReturnValue({
+    using wf = mockWorkflow();
+    const validate = wf.job(validateOrder).mockResolvedValue({
       valid: true,
       orderId: "order-1",
     });
-    using _paymentSpy = vi.spyOn(processPayment, "trigger").mockReturnValue({
+    wf.job(processPayment).mockResolvedValue({
       transactionId: "txn-order-1",
       amount: 100,
       status: "completed",
     });
-    using _confirmSpy = vi.spyOn(sendConfirmation, "trigger").mockReturnValue({
+    wf.job(sendConfirmation).mockResolvedValue({
       orderId: "order-1",
       transactionId: "txn-order-1",
       confirmed: true,
     });
 
-    const result = await fulfillOrder.body({ orderId: "order-1", amount: 100 }, { env: {} });
+    const result = await fulfillOrder.body(
+      { orderId: "order-1", amount: 100 },
+      { env: {}, invoker: null },
+    );
 
-    expect(validateOrder.trigger).toHaveBeenCalledWith({ orderId: "order-1", amount: 100 });
+    expect(validate).toHaveBeenCalledWith({ orderId: "order-1", amount: 100 });
     expect(result).toMatchObject({ confirmed: true, paymentStatus: "completed" });
   });
 });
@@ -675,43 +765,50 @@ describe("fulfillOrder", () => {
 
 #### Jobs that wait on approval
 
-`.wait()` calls delegate to `tailor.workflow.wait`. With the `tailor-runtime` environment active, use `mockWorkflow().setWaitHandler` to drive each branch and inspect `waitCalls`:
+`.wait()` calls delegate to `tailor.workflow.wait`. With the `tailor-runtime` environment active, use `mockWorkflow().waitPoint(definition)` to drive each branch with a typed mock:
 
 ```typescript
 import { mockWorkflow } from "@tailor-platform/sdk/vitest";
 import { describe, expect, test } from "vitest";
-import { processWithApproval } from "./approval";
+import { approval, processWithApproval } from "./approval";
 
 describe("processWithApproval", () => {
   test("returns approved status when .wait() resolves positively", async () => {
     using wf = mockWorkflow();
-    wf.setWaitHandler({ approved: true });
+    const approvalMock = wf.waitPoint(approval);
+    approvalMock.wait.mockResolvedValue({ approved: true });
 
-    const result = await processWithApproval.body({ orderId: "order-1" }, { env: {} });
+    const result = await processWithApproval.body(
+      { orderId: "order-1" },
+      { env: {}, invoker: null },
+    );
 
     expect(result).toEqual({ orderId: "order-1", status: "approved" });
-    expect(wf.waitCalls[0]).toEqual({
-      key: "approval",
-      payload: { message: "Please approve order order-1", orderId: "order-1" },
+    expect(approvalMock.wait).toHaveBeenCalledWith({
+      message: "Please approve order order-1",
+      orderId: "order-1",
     });
   });
 
   test("returns rejected status when .wait() resolves negatively", async () => {
     using wf = mockWorkflow();
-    wf.setWaitHandler({ approved: false });
+    wf.waitPoint(approval).wait.mockResolvedValue({ approved: false });
 
-    const result = await processWithApproval.body({ orderId: "order-2" }, { env: {} });
+    const result = await processWithApproval.body(
+      { orderId: "order-2" },
+      { env: {}, invoker: null },
+    );
 
     expect(result.status).toBe("rejected");
   });
 });
 ```
 
-`setWaitHandler` accepts a static value (returned from every `.wait()` call) or a function `(key, payload) => unknown` to compute one per call. `waitCalls` captures the `key` and `payload` passed in.
+The lower-level `setWaitHandler` and `waitCalls` APIs remain available when one handler must cover several wait points.
 
 #### Running a full workflow locally
 
-To exercise the full chain with real job bodies, call `runWorkflowLocally(workflow, args)`. Dependent jobs run their real `.body()` functions, and trigger args/results cross the same JSON boundary as the platform, so a non-serializable payload fails the test exactly as it would in production:
+To exercise the full chain with real job bodies, call `runWorkflowLocally(workflow, args)`. Dependent jobs run their real `.body()` functions, and start args/results cross the same JSON boundary as the platform, so a non-serializable payload fails the test exactly as it would in production:
 
 ```typescript
 import { runWorkflowLocally } from "@tailor-platform/sdk/vitest";
@@ -727,9 +824,13 @@ describe("order-fulfillment workflow", () => {
 });
 ```
 
+Acquire `mockWorkflow()` only when you need to override a dependent definition with `wf.job(...)` / `wf.workflow(...)` (the rest still run their real bodies), control the env via `wf.setEnv(...)`, or assert on calls.
+
 Pass `{ env }` as the third argument when job bodies need configuration values during the local run.
 
-Like the platform runtime, the local runner re-runs the orchestrator body once per `.trigger()` call (N triggers means N+1 passes), so any side effects outside the trigger results fire on every pass. Keep the body deterministic and move repeatable side effects into the triggered jobs.
+If you already acquired `mockWorkflow()`, you can also call `wf.setEnv(...)` to reuse the same env across local workflow runs.
+
+Like the platform runtime, the local runner re-runs the orchestrator body once per `.start()` call (N starts means N+1 passes), so any side effects outside the start results fire on every pass. Keep the body deterministic and move repeatable side effects into the started jobs.
 
 This helper is still a local runner. Use E2E tests when you need to verify deployed workflow scheduling, suspension, or replay behavior.
 
@@ -837,7 +938,7 @@ describe("user-profile-sync workflow", () => {
   test("executes end to end", { timeout: 180_000 }, async () => {
     const { executionId, wait } = await startWorkflow({
       workflow: userProfileSync,
-      authInvoker: "admin",
+      invoker: "admin",
       arg: {
         name: "workflow-test",
         email: `wf-${randomUUID()}@example.com`,