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