Skip to content

Commit c1e7ca9

Browse files
Update SDK pages
1 parent e48e8cd commit c1e7ca9

3 files changed

Lines changed: 51 additions & 3 deletions

File tree

docs/sdk/cli/function.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ tailor-sdk function test-run [options] <file>
152152
**Run a resolver with input arguments**
153153

154154
```bash
155-
$ tailor-sdk function test-run resolvers/add.ts --arg '{"input":{"a":1,"b":2}}'
155+
$ tailor-sdk function test-run resolvers/add.ts --arg '{"a":1,"b":2}'
156156
```
157157

158158
**Run a specific workflow job by name**
@@ -164,7 +164,7 @@ $ tailor-sdk function test-run workflows/sample.ts --name validate-order
164164
**Run a pre-bundled .js file directly**
165165

166166
```bash
167-
$ tailor-sdk function test-run build/resolvers/add.js --arg '{"input":{"a":1,"b":2}}'
167+
$ tailor-sdk function test-run build/resolvers/add.js --arg '{"a":1,"b":2}'
168168
```
169169

170170
<!-- politty:command:function test-run:examples:end -->

docs/sdk/services/resolver.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Resolvers provide:
1313

1414
## Comparison with Tailor Platform Pipeline Resolver
1515

16-
The SDK's Resolver is a simplified version of Tailor Platform's [Pipeline Resolver](/guides/pipeline).
16+
The SDK's Resolver is a simplified version of Tailor Platform's [Pipeline Resolver](/guides/resolver).
1717

1818
| Pipeline Resolver | SDK Resolver |
1919
| ---------------------------------------- | --------------------------------- |

docs/sdk/services/workflow.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,54 @@ export const mainJob = createWorkflowJob({
115115

116116
**Important:** On the Tailor runtime, job triggers are executed synchronously. This means `Promise.all([jobA.trigger(), jobB.trigger()])` will not run jobs in parallel.
117117

118+
### Deterministic Execution Requirement
119+
120+
Workflow jobs use a **suspend/resume execution model**. When a job calls `.trigger()`, the runtime suspends the current job, executes the triggered job, and then **re-executes the calling job from the beginning** with cached results from previous triggers.
121+
122+
This means that **job code must be deterministic** — every re-execution must produce the same sequence of `.trigger()` calls with the same arguments in the same order.
123+
124+
Using `.trigger()` inside a loop works correctly, as long as the loop is deterministic:
125+
126+
```typescript
127+
// ✅ OK: deterministic loop — same calls in the same order on every execution
128+
const regions = ["us", "eu", "ap"];
129+
for (const region of regions) {
130+
const result = await fetchData.trigger({ region });
131+
results.push(result);
132+
}
133+
```
134+
135+
```typescript
136+
// ❌ Bad: non-deterministic — argument changes between executions
137+
await processJob.trigger({ timestamp: Date.now() });
138+
139+
// ✅ OK: call Date.now() in separated job
140+
const timestamp = await timestampJob.trigger();
141+
await processJob.trigger({ timestamp });
142+
```
143+
144+
```typescript
145+
// ❌ Bad: non-deterministic — external data may change between executions
146+
const items = await fetch("https://api.example.com/items").then((r) => r.json());
147+
for (const item of items) {
148+
await processItem.trigger({ id: item.id });
149+
}
150+
151+
// ✅ OK: call fetch("https://api.example.com/items").then((r) => r.json()); in separated job
152+
const items = await fetchItemsJob.trigger();
153+
for (const item of items) {
154+
await processItem.trigger({ id: item.id });
155+
}
156+
```
157+
158+
If the runtime detects that a `.trigger()` call at the same position has different arguments than the previous execution, it will throw an **argument hash mismatch error**.
159+
160+
**Guidelines:**
161+
162+
- Do not use non-deterministic values (random numbers, timestamps, external API responses) as `.trigger()` arguments.
163+
- Do not use conditions that may change between executions to decide whether to call `.trigger()`.
164+
- Any data that varies between executions should be fetched **inside the triggered job**, not passed as an argument from the calling job.
165+
118166
## Workflow Definition
119167

120168
Define a workflow using `createWorkflow` and export it as default:

0 commit comments

Comments
 (0)