Skip to content

Commit f0f101e

Browse files
committed
docs: retire the workflow slot from four more hand-written pages (#4451)
The docs-drift check on PR #4473 earned its keep: my symbol-shaped grep (`IWorkflowService`, `WorkflowProtocol`, `api/v1/workflow`) found three pages and missed four PROSE mentions that describe the same retired slot in words. - `api/plugin-endpoints.mdx` documented three `/workflow/*` routes under a "not yet mounted … return 404 today" caveat. The caveat was already the tell: routes that 404 for the whole life of the declaration are not "not yet", and the slot behind them is gone now. The section becomes a redirect naming the three live mechanisms. - `kernel/services-checklist.mdx` carried it in three more places — the legend's 36-method count (now 33), the `null`-provider explanation, and a full "6. workflow Service" section still describing the three methods as pending rather than removed. The remaining `workflow` hits in `content/docs` are the ordinary English word (approval workflow, build workflow, GitHub Actions workflows) and stay.
1 parent 40fc905 commit f0f101e

2 files changed

Lines changed: 35 additions & 24 deletions

File tree

‎content/docs/api/plugin-endpoints.mdx‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -26,19 +26,21 @@ Authenticate with email and password (better-auth's email sign-in route, mounted
2626

2727
The following endpoints become available when the corresponding plugin is installed and registered with the kernel. Use the discovery `services` map to check availability.
2828

29-
### Workflow (`/workflow`) — Plugin Required
29+
### Workflow (`/workflow`) — removed in v17
3030

3131
<Callout type="warn">
32-
Not yet mounted. These routes are declared in the API protocol but the core dispatcher registers no `/workflow` handler and no bundled plugin provides a `workflow` service (only an in-memory dev stub), so they return **404** today. `discovery.services.workflow` reports `unavailable` in a standard install.
32+
There is no workflow endpoint, and there is no `workflow` service slot. The
33+
three routes documented here were declared in the API protocol and served by
34+
nothing — no dispatcher handler, no plugin — so they 404'd for the whole life
35+
of the declaration. The slot, the `WorkflowProtocol` methods behind it and the
36+
discovery fields that reported it were all retired in v17 ([#4451](https://github.com/objectstack-ai/objectstack/issues/4451)).
37+
Use the live mechanisms instead: an object validation rule of type
38+
`state_machine` for lifecycle transitions, an `approval` flow node for human
39+
approval pauses (ADR-0019), and lifecycle hooks / `record_change` flows for
40+
record-triggered automation.
3341
</Callout>
3442

35-
| Method | Endpoint | Description |
36-
|:-------|:---------|:------------|
37-
| GET | `/workflow/:object/config` | Get workflow configuration |
38-
| GET | `/workflow/:object/:recordId/state` | Get record's workflow state |
39-
| POST | `/workflow/:object/:recordId/transition` | Execute state transition |
40-
41-
Approve/reject are **not** workflow routes (ADR-0019): approval is a flow node, and decisions are recorded on the approvals runtime via `POST /approvals/requests/:id/approve` and `POST /approvals/requests/:id/reject`.
43+
Approve/reject were never workflow routes (ADR-0019): approval is a flow node, and decisions are recorded on the approvals runtime via `POST /approvals/requests/:id/approve` and `POST /approvals/requests/:id/reject`.
4244

4345
### Automation (`/automation`) — Plugin Required
4446

‎content/docs/kernel/services-checklist.mdx‎

Lines changed: 24 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,14 @@ The ObjectStack protocol defines **16 kernel services** registered via the `Core
2424
- ✅ Implemented — the 17 kernel-provided protocol methods (`DataProtocol` 9 + `MetadataProtocol` 8)
2525
- ⚠️ Framework — the slot is filled by the kernel's in-memory fallback: real reads and
2626
writes, no persistence (self-declares `degraded`, ADR-0076 D12)
27-
- ❌ Plugin Required — the remaining 36 methods declared across the other per-domain
27+
- ❌ Plugin Required — the remaining 33 methods declared across the other per-domain
2828
contracts (`analytics` 2, `automation` 1, `packages` 6, `views` 5, `permissions` 3,
29-
`workflow` 3, `realtime` 6, `notification` 7, `i18n` 3). *Declared* is not *routed*:
29+
`realtime` 6, `notification` 7, `i18n` 3). *Declared* is not *routed*:
3030
`packages` is answered kernel-side by the `/packages` dispatcher domain over the
31-
ObjectQL registry, `i18n` has a kernel in-memory fallback, and `views` / `permissions` /
32-
`workflow` have no implementation anywhere — the rest wait on whatever fills the slot
31+
ObjectQL registry, `i18n` has a kernel in-memory fallback, and `views` /
32+
`permissions` have no implementation anywhere — the rest wait on whatever fills
33+
the slot. (`workflow`'s 3 methods were the fourth such group; the whole slot
34+
retired in v17, [#4451](https://github.com/objectstack-ai/objectstack/issues/4451).)
3335
</Callout>
3436

3537
---
@@ -90,10 +92,12 @@ installable optional package, so they need no remedy (`NO_REMEDY_SLOTS` in the
9092
guard script). And `null` there does **not** always mean "nothing ships" — it
9193
means "no name belongs in an `Install X` sentence", which covers two cases:
9294

93-
- **Nothing provides the slot at all** — `search`, `workflow` (and the retired
94-
`graphql`). Discovery says exactly that rather than naming a plausible
95-
package: `No implementation ships for the '<slot>' slot — register a service
96-
under it to enable`.
95+
- **Nothing provides the slot at all** — `search`. Discovery says exactly that
96+
rather than naming a plausible package: `No implementation ships for the
97+
'<slot>' slot — register a service under it to enable`. (`workflow` and the
98+
never-real `graphql` sat here too until both were retired outright in v17,
99+
[#4451](https://github.com/objectstack-ai/objectstack/issues/4451) — a slot
100+
nothing fills and nothing consumes is better removed than explained.)
97101
- **A provider exists but cannot be installed** — `ai`. `@objectstack/service-ai`
98102
registers the slot in `objectstack-ai/cloud` and is `private: true`.
99103

@@ -333,13 +337,18 @@ the domain answers **501** with that remedy spelled out, not a generic "install
333337
plugin".
334338
</Callout>
335339

336-
### 6. workflow Service — 3 methods ❌ Nothing ships
337-
`getWorkflowConfig`, `getWorkflowState`, `workflowTransition`
338-
State machine transitions. No package registers the `workflow` slot
339-
(`CORE_SERVICE_PROVIDER.workflow` is `null`). Approve/reject are not workflow
340-
methods — per ADR-0019 they moved to the request-id-based approvals API under
341-
`/api/v1/approvals` (`POST /requests/:id/{approve,reject,recall}`, served by
342-
`@objectstack/plugin-approvals`).
340+
### 6. workflow Service — retired in v17
341+
The slot, its `IWorkflowService` contract and the three `WorkflowProtocol`
342+
methods (`getWorkflowConfig`, `getWorkflowState`, `workflowTransition`) were
343+
removed in [#4451](https://github.com/objectstack-ai/objectstack/issues/4451):
344+
nothing ever registered or resolved the slot (ADR-0115 Evidence 5), no method
345+
ever had an implementation, and no host ever mounted `/api/v1/workflow`. The
346+
three capabilities it named are live elsewhere — state-machine transitions are
347+
an object validation rule of type `state_machine`, approvals are `approval`
348+
flow nodes on the approvals runtime (ADR-0019 — decisions via
349+
`POST /api/v1/approvals/requests/:id/{approve,reject,recall}`, served by
350+
`@objectstack/plugin-approvals`), and record-triggered automation is lifecycle
351+
hooks + `record_change` flows.
343352

344353
### 7. automation Service — 1 method ✅ `@objectstack/service-automation`
345354
`triggerAutomation`

0 commit comments

Comments
 (0)