|
| 1 | +--- |
| 2 | +'@objectstack/spec': major |
| 3 | +'@objectstack/service-automation': patch |
| 4 | +'@objectstack/plugin-approvals': patch |
| 5 | +--- |
| 6 | + |
| 7 | +refactor(spec)!: retire `ActionDescriptor.isAsync` — a second spelling of `supportsPause` that nothing ever read (#6748, ADR-0049) |
| 8 | + |
| 9 | +<!-- adr-0087: registered action-descriptor-is-async-retired --> |
| 10 | + |
| 11 | +**FROM → TO:** `isAsync: true` → delete the key; declare `supportsPause: true` (plus the |
| 12 | +`resumeAuthority` its pauses need) and return `suspend: true` from `execute()`. |
| 13 | +`isAsync: false` → delete the key; there was never anything to preserve. |
| 14 | + |
| 15 | +`ActionDescriptor.isAsync` declared "suspends the flow awaiting an external reply" and no |
| 16 | +execution path read it. Measured fresh before removal across all three repos — objectstack, |
| 17 | +objectui and cloud — with zero property reads: every hit was the declaration itself, a |
| 18 | +generated baseline, one of five shipped descriptors WRITING it, a fixture pinning the |
| 19 | +shape, or prose. Declaring it never made a node suspend; omitting it never stopped one. |
| 20 | + |
| 21 | +This is the remove leg of the ADR-0049 disposition its sibling took the other way. The two |
| 22 | +keys said the same thing — "this node type can suspend the run" — and #6667 split them by |
| 23 | +evidence: `supportsPause` became an enforced fact (`AutomationEngine` now refuses a |
| 24 | +suspension whose type does not declare it, at the one seam every suspension passes |
| 25 | +through), while `isAsync` had no consumer to grow into. Keeping both would leave the |
| 26 | +platform publishing two names for one capability with only one of them honoured — and |
| 27 | +`screen` declared BOTH, so a plugin author copying it had no way to tell which. |
| 28 | + |
| 29 | +The retirement kit: |
| 30 | + |
| 31 | +- **Tombstone, not deletion** (`retiredKey()`): `ActionDescriptorSchema` is not `.strict()`, |
| 32 | + so a plain delete would let existing descriptors parse clean and lose the key in silence |
| 33 | + (the ADR-0104 shape). Authoring `isAsync` now fails `tsc` at the descriptor literal and |
| 34 | + fails the parse inside `defineActionDescriptor()` — with the prescription in the message. |
| 35 | +- **ADR-0087 D3 `SemanticMigration`** (`action-descriptor-is-async-retired`) plus the exact |
| 36 | + `RETIRED_KEYS_BY_MAJOR` entry. No D2 conversion, deliberately: a descriptor is published |
| 37 | + from an executor's TypeScript and never stored in stack metadata, so there is no source |
| 38 | + for `os migrate meta` to rewrite — the `EnhancedApiError.fieldErrors` disposition. |
| 39 | +- The five shipped writers stop writing it (`screen`, `map`, `wait`, `approval`, |
| 40 | + `approval_revise`); the descriptors they publish lose the key, which is why the two |
| 41 | + runtime packages appear here. |
| 42 | +- Generated baselines (`authorable-surface/automation.json` gains `[RETIRED]`, |
| 43 | + `authorable-defaults/automation.json` loses the default line), `spec-changes.json`, the |
| 44 | + upgrade guide and the reference docs regenerated. |
| 45 | + |
| 46 | +No runtime behaviour changes — that impossibility is the reason for the removal. The same |
| 47 | +commit also corrects `supportsPause`'s TSDoc, which still described itself as a declaration |
| 48 | +no execution path reads; #6667 made that false (#6749). |
0 commit comments