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