tegwick
e302ca9f59
Expose hours query param on /legacy-meter/summary and weekly-review; capture_legacy_meter_evidence.py defaults to --hours 8 (--days 7 for weekly retirement gate). Re-capture post-deploy evidence with tighter window.
113 lines
5.3 KiB
Markdown
113 lines
5.3 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}`~~ **410 Gone** (2026-07-08) | `rest_api:DELETE /workstreams/{workstream_id}` (retired) |
|
|
| Workplan index | `GET /workplans/index` | ~~`GET /workstreams/workplan-index`~~ **410 Gone** (2026-07-09) | `rest_api:GET /workstreams/workplan-index` (retired) |
|
|
| 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`~~ **retired** (2026-07-08) | `event_subject:org.statehub.workstream.completed` (retired) |
|
|
|
|
Legacy REST responses include:
|
|
|
|
- `Deprecation: true`
|
|
- `Sunset: Wed, 30 Jun 2027 23:59:59 GMT` (planning horizon; removal remains legacy-meter-gated)
|
|
- `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.
|
|
|
|
## STATE-WP-0069 closeout (2026-07-08)
|
|
|
|
Completed in this workplan:
|
|
|
|
- `org.statehub.workstream.completed` dual-publish stopped; legacy subject retired
|
|
in legacy-meter.
|
|
- `DELETE /workstreams/{workstream_id}` returns **410 Gone** with replacement header.
|
|
- `scripts/consistency_check.py`, MCP adhoc bootstrap, and dashboard token summary
|
|
now call `/workplans/` (major `/workstreams` usage reduction).
|
|
- `flows/workplan.yaml` and `open_workplans` are preferred; legacy dual-keys remain
|
|
until legacy-meter clears callers.
|
|
|
|
Deferred until seven consecutive zero-usage review windows per key:
|
|
|
|
- MCP alias removal (`create_workstream`, etc.).
|
|
- Remaining `/workstreams` GET/POST/PATCH routes (still metered with Deprecation).
|
|
- `workstream_id` query/body param aliases on preferred routes.
|
|
|
|
Evidence capture:
|
|
|
|
```bash
|
|
python scripts/capture_legacy_meter_evidence.py # default 8h post-deploy monitoring
|
|
python scripts/capture_legacy_meter_evidence.py --days 7 # weekly retirement gate
|
|
# writes docs/evidence/legacy-meter-weekly-review-YYYYMMDD.json
|
|
```
|
|
|
|
Activity-core `weekly-legacy-meter-review` (`30 8 * * 1` Europe/Berlin) consumes
|
|
`/legacy-meter/weekly-review`; railiance-cluster rollout suggestion `05da5540`.
|