|
| 1 | +--- |
| 2 | +'@objectstack/spec': minor |
| 3 | +'@objectstack/service-automation': minor |
| 4 | +'@objectstack/runtime': minor |
| 5 | +'@objectstack/client': minor |
| 6 | +--- |
| 7 | + |
| 8 | +**BREAKING** — the automation `trigger` routes now answer **409** for a disabled |
| 9 | +flow and **422** for a flow whose definition has no start node, instead of HTTP |
| 10 | +200 wrapping an inner `{success: false}`. |
| 11 | + |
| 12 | +This finishes the migration the previous release started. That changeset flipped |
| 13 | +two of the four outcomes and said of the other two: |
| 14 | + |
| 15 | +> **Also unchanged, pending a ruling:** a DISABLED flow and one with no start |
| 16 | +> node still answer 200 with the inner failure. Both are exits that never |
| 17 | +> dispatched anything, and telling them apart needs a producer-side |
| 18 | +> classification the closed `AutomationResult.code` union cannot yet express. |
| 19 | +
|
| 20 | +That is the paragraph this change resolves. The union was widened deliberately — |
| 21 | +two new members, with measured need — rather than the transport guessing from |
| 22 | +message text or re-implementing the engine's enable-state policy. |
| 23 | + |
| 24 | +`POST /api/v1/automation/:name/trigger` and the legacy |
| 25 | +`POST /api/v1/automation/trigger/:name` now answer, in full: |
| 26 | + |
| 27 | +| Status | `error.code` | The run | |
| 28 | +|:---|:---|:---| |
| 29 | +| `404` | — | never dispatched: no such flow | |
| 30 | +| `409` | `FLOW_DISABLED` | never dispatched: the flow is switched off | |
| 31 | +| `422` | `FLOW_NO_START_NODE` | never dispatched: the definition has no `start` node | |
| 32 | +| `400` | `FLOW_FAILED` | RAN, and was rejected | |
| 33 | +| `200` | — | succeeded, or PAUSED at a screen node — a pause is not a failure | |
| 34 | + |
| 35 | +The three refusals report no run because none exists: no node executed and |
| 36 | +nothing was written. Only `400` describes a run, and only it carries |
| 37 | +`error.details.summary` / `error.details.errorMessage`. |
| 38 | + |
| 39 | +Why two statuses and not one: a disabled flow is reversible operational state — |
| 40 | +enable it and the identical request succeeds, which is what `409` means. A flow |
| 41 | +with no start node cannot be executed as stored, and no retry helps, which is |
| 42 | +what `422` means. Collapsing them would tell an operator to flip a switch that |
| 43 | +will not help. |
| 44 | + |
| 45 | +**`@objectstack/spec`:** `AutomationResult.code` gains `'FLOW_DISABLED'` and |
| 46 | +`'FLOW_NO_START_NODE'`. The union stays closed; these are trigger-time refusals |
| 47 | +classified *before* dispatch, documented as a group distinct from the existing |
| 48 | +resume-refusal members. Both are registered in the ADR-0112 error-code ledger. |
| 49 | + |
| 50 | +**`@objectstack/service-automation`:** `execute()` stamps the matching `code` on |
| 51 | +its disabled-flow and no-start-node exits. They continue to carry **no** |
| 52 | +`status` — that absence is what lets a transport tell a never-dispatched exit |
| 53 | +from a run that dispatched and failed (`status: 'failed'`) without inspecting |
| 54 | +`summary`, `durationMs` or the message. |
| 55 | + |
| 56 | +**`@objectstack/client`:** `client.automation.trigger()`, `.execute()` and |
| 57 | +`client.project(id).automation.execute()` already rejected on a failed run; |
| 58 | +they now reject with these two additional classifications, so a caller can tell |
| 59 | +"enable the flow and retry" from "the flow definition is broken": |
| 60 | + |
| 61 | +```ts |
| 62 | +try { |
| 63 | + await client.automation.execute(flow, { params }); |
| 64 | +} catch (err: any) { |
| 65 | + err.httpStatus; // 409 | 422 | 400 | 404 |
| 66 | + err.code; // 'FLOW_DISABLED' | 'FLOW_NO_START_NODE' | 'FLOW_FAILED' |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +Callers that branch only on `FLOW_FAILED` keep working for the case they |
| 71 | +handle, but will no longer see these two refusals under it — they arrive with |
| 72 | +their own codes, which is the point. |
| 73 | + |
| 74 | +Not affected, and deliberately so: `POST /api/v1/actions/...` with a |
| 75 | +`type: 'flow'` action, and metadata-declared `type: 'flow'` endpoints. Both |
| 76 | +dispatch the same flow through a different door with its own response |
| 77 | +conventions, and whether they should inherit this table is tracked separately. |
| 78 | + |
| 79 | +<!-- adr-0087: not-required (no-migration-prescription) retires no metadata surface: no Zod schema, no authorable key, and no stored sys_metadata row changes shape, so `objectstack migrate meta` has nothing to rewrite and no ledger entry could be written for it. What changes is an HTTP status plus two new members of a runtime result type, and the channel that reaches those consumers is this changeset plus the compiler. --> |
0 commit comments