coulomb/state-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
state-hub/docs/workplan-terminology-transition.md
tegwick e302ca9f59
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 5s
Details
Build and Publish Multi-Context Image / build-and-push (push) Failing after 1m15s
Details
Add 8-hour default window for legacy-meter deploy monitoring 
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.
2026-07-09 01:36:02 +02:00

5.3 KiB
Raw Permalink Blame History

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:

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.