state-hub/docs/workplan-terminology-transition.md

# 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`.