53 lines
1.6 KiB
Markdown
53 lines
1.6 KiB
Markdown
---
|
|
title: FlowEvent and FLOW_RESULT
|
|
description: Stable event and result contracts shared by local and backend execution.
|
|
---
|
|
|
|
# FlowEvent and FLOW_RESULT
|
|
|
|
`FlowEvent` is the ABI between products, clients, backends, and flow packages.
|
|
|
|
```ts
|
|
type FlowEvent<T = unknown> = {
|
|
id: string;
|
|
type: string;
|
|
source?: string;
|
|
occurredAt?: string;
|
|
receivedAt: string;
|
|
payload: T;
|
|
};
|
|
```
|
|
|
|
## Fields
|
|
|
|
| Field | Required | Meaning |
|
|
|-------|----------|---------|
|
|
| `id` | Yes | Caller-owned idempotency key. Use deterministic ids for duplicate suppression. |
|
|
| `type` | Yes | Trigger type matched by `flow.toml`. |
|
|
| `source` | No | Product or subsystem that emitted the event. |
|
|
| `occurredAt` | No | When the domain event happened. |
|
|
| `receivedAt` | Yes | When the flow system accepted the event. |
|
|
| `payload` | Yes | Domain payload validated by each step schema. |
|
|
|
|
## Result status
|
|
|
|
Steps print one final line:
|
|
|
|
```text
|
|
FLOW_RESULT {"status":"completed","message":"done"}
|
|
```
|
|
|
|
Known semantic statuses:
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| `skipped` | Step intentionally did no work. |
|
|
| `completed` | Step completed without durable changes or with expected work done. |
|
|
| `changed` | Step completed and changed state. |
|
|
| `needs_intervention` | A human decision or action is needed. |
|
|
| `blocked` | External state blocks progress. |
|
|
| `failed` | Step failed semantically even if the process exited cleanly. |
|
|
|
|
Backends also track process status such as `queued`, `running`, `completed`,
|
|
`failed`, and `canceled`. Clients expose `effectiveStatus` and
|
|
`needsAttention` to combine process and semantic result state.
|