generated from coulomb/repo-seed
tegwick
166aedfa8d
Adds preferred workplan REST/event surfaces, legacy-meter telemetry and weekly review summaries, documentation/dashboard terminology updates, dashboard API loading fixes, and close-out sync for STATE-WP-0052 and STATE-WP-0054.
84 lines
3.9 KiB
Markdown
84 lines
3.9 KiB
Markdown
# Workplan Terminology Transition
|
|
|
|
Date: 2026-06-04
|
|
Status: implementation guide for `STATE-WP-0054`
|
|
|
|
## Position
|
|
|
|
`workplan` is the preferred State Hub term for repo-backed deliverable work.
|
|
`workstream` remains a legacy compatibility term for interfaces that already
|
|
exist in clients, database relationships, event subjects, scripts, and generated
|
|
bridge metadata.
|
|
|
|
The transition is compatibility-first:
|
|
|
|
- new clients should use workplan-named interfaces;
|
|
- existing workstream interfaces remain operational while they are used;
|
|
- retained workstream interfaces are registered in `legacy-meter`;
|
|
- every legacy registration records the preferred replacement; and
|
|
- weekly activity-core review uses legacy-meter data to decide when a legacy
|
|
interface is safe to retire.
|
|
|
|
Physical database renames are intentionally out of scope for this workplan.
|
|
|
|
## Preferred Interfaces
|
|
|
|
| Interface | Preferred path or subject | Legacy compatibility path or subject | Legacy-meter key |
|
|
| --- | --- | --- | --- |
|
|
| List workplans | `GET /workplans/` | `GET /workstreams/` | `rest_api:GET /workstreams/` |
|
|
| Create workplan | `POST /workplans/` | `POST /workstreams/` | `rest_api:POST /workstreams/` |
|
|
| Read workplan | `GET /workplans/{workplan_id}` | `GET /workstreams/{workstream_id}` | `rest_api:GET /workstreams/{workstream_id}` |
|
|
| Update workplan | `PATCH /workplans/{workplan_id}` | `PATCH /workstreams/{workstream_id}` | `rest_api:PATCH /workstreams/{workstream_id}` |
|
|
| Archive workplan | `DELETE /workplans/{workplan_id}` | `DELETE /workstreams/{workstream_id}` | `rest_api:DELETE /workstreams/{workstream_id}` |
|
|
| Workplan index | `GET /workplans/index` | `GET /workstreams/workplan-index` | `rest_api:GET /workstreams/workplan-index` |
|
|
| Workplan dependencies | `GET/POST /workplans/{workplan_id}/dependencies/` | `GET/POST /workstreams/{workstream_id}/dependencies/` | matching `rest_api:* /workstreams/...` keys |
|
|
| Delete dependency | `DELETE /workplans/{workplan_id}/dependencies/{dep_id}` | `DELETE /workstreams/{workstream_id}/dependencies/{dep_id}` | `rest_api:DELETE /workstreams/{workstream_id}/dependencies/{dep_id}` |
|
|
| Execution intent | `PATCH /execution/workplans/{workplan_id}/intent` | `PATCH /execution/workstreams/{workstream_id}/intent` | `rest_api:PATCH /execution/workstreams/{workstream_id}/intent` |
|
|
| Completion event | `org.statehub.workplan.completed` | `org.statehub.workstream.completed` | `event_subject:org.statehub.workstream.completed` |
|
|
|
|
Legacy REST responses include:
|
|
|
|
- `Deprecation: true`
|
|
- `X-StateHub-Replacement: <preferred interface>`
|
|
- `Link: <<preferred interface>>; rel="successor-version"`
|
|
|
|
## Legacy Meter
|
|
|
|
`legacy-meter` stores two kinds of data:
|
|
|
|
- `legacy_interfaces`: the registry of legacy interfaces, their legacy
|
|
timestamp, preferred replacement, owner component, hold status, and replacement
|
|
verification state.
|
|
- `legacy_interface_usage_buckets`: daily usage buckets for calls, tenants,
|
|
users, and components.
|
|
|
|
When identity headers are missing, usage is recorded in the explicit `unknown`
|
|
bucket. Clients can provide:
|
|
|
|
- `X-StateHub-Tenant`
|
|
- `X-StateHub-User`
|
|
- `X-StateHub-Component`
|
|
|
|
Useful endpoints:
|
|
|
|
| Endpoint | Purpose |
|
|
| --- | --- |
|
|
| `POST /legacy-meter/interfaces` | Register or update a legacy interface. |
|
|
| `GET /legacy-meter/interfaces` | List registered legacy interfaces. |
|
|
| `POST /legacy-meter/usage` | Record explicit usage outside an instrumented route. |
|
|
| `GET /legacy-meter/summary` | Show usage counters for a review window. |
|
|
| `GET /legacy-meter/weekly-review` | Activity-core-friendly weekly review payload. |
|
|
|
|
## Retirement Rule
|
|
|
|
An interface is a retirement candidate only when all of the following are true:
|
|
|
|
- it is registered as legacy;
|
|
- it has a replacement reference;
|
|
- the replacement has been verified;
|
|
- it has no manual hold;
|
|
- it had zero measured calls in the review window.
|
|
|
|
State Hub owns the usage state and the review payload. Activity-core owns the
|
|
weekly wakeup, review activity, and any follow-up dispatch.
|