coulomb/the-custodian
4
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
the-custodian/docs/retired-legacy-interfaces.md
codex 0ab3e359ce docs: journal of retired legacy interfaces 
Fleet-level record of legacy interfaces retired under the State Hub
retirement program. Kept here rather than in state-hub because state-hub is
being archived -- once it is read-only its legacy-meter tables stop being
queryable in practice, and this needs to outlive that.

Records the 15 workstream->workplan aliases retired on 2026-08-20 under
STATE-WP-0079-T05 slice E2, the one retired earlier, and the 4 still held
with the reason each is held. Documents the retirement standard including
the volume-scaled quiet ladder and why it exists.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-20 07:28:36 +02:00

5.4 KiB
Raw Blame History

Retired legacy interfaces — journal

Scope: fleet-wide record of legacy interfaces retired under the State Hub retirement program. Maintained here, not in state-hub, because state-hub is being archived and this record must outlive it. Once the hub is read-only its legacy-meter tables stop being queryable in practice; this file is the durable reference.

Source of record while the hub is live: state-hub legacy-meter (/legacy-meter/interfaces), evidence captures in state-hub/docs/evidence/legacy-meter-weekly-review-*.json. Programme: STATE-WP-0069 (terminology retirement), STATE-WP-0079-T05 (retire legacy surfaces), slice E2 in state-hub/docs/retirement-cutover-slice-plan.md.

Retirement standard

An interface is retired only when all of the following hold:

  1. A replacement exists (replacement_ref) and is marked verified.
  2. No manual hold.
  3. Zero calls in a 7-day review window.
  4. Silence since last_seen_at of at least a volume-scaled quiet period — 7 days under 100 all-time calls, 30 days under 10 000, 60 days above.

Rule 4 exists because a clean window only proves silence for that window. A heavily-used interface can have an infrequent caller that falls outside it. This was not hypothetical: before the rule was added, captures ran over an 8-hour band rather than a week, and interfaces with live callers were reported as retirement candidates.

Implementation: RETIREMENT_QUIET_LADDER in state-hub/api/services/legacy_meter.py.

Retired 2026-08-20 — workstream→workplan terminology aliases (15)

Slice E2, STATE-WP-0079-T05. All replaced by the workplan spelling of the same surface.

Interface Kind Replacement Legacy since Retired All-time calls Last seen
mcp:create_workstream mcp_tool create_workplan 2026-07-10 2026-08-20 2 2026-07-10
mcp:list_workstreams mcp_tool list_workplans 2026-07-10 2026-08-20 2 2026-07-10
mcp:update_workstream mcp_tool update_workplan 2026-07-10 2026-08-20 0 —
mcp:update_workstream_status mcp_tool update_workplan_status 2026-07-10 2026-08-20 0 —
state://workstreams/{topic_slug} mcp_tool state://workplans/{topic_slug} 2026-07-10 2026-08-20 1 2026-07-10
rest_api:DELETE /workstreams/{workstream_id} rest_api /workplans/{workplan_id} 2026-06-06 2026-08-20 1 2026-06-06
rest_api:GET /decisions/?workstream_id rest_api /decisions/?workplan_id=<workplan_id> 2026-07-09 2026-08-20 1 2026-07-09
rest_api:GET /progress/?workstream_id rest_api /progress/?workplan_id=<workplan_id> 2026-07-13 2026-08-20 2 2026-08-12
rest_api:GET /workstreams/workplan-index rest_api /workplans/index 2026-06-04 2026-08-20 30 2026-07-03
rest_api:PATCH /workstreams/{workstream_id} rest_api /workplans/{workplan_id} 2026-06-04 2026-08-20 571 2026-07-08
rest_api:POST /decisions/ workstream_id rest_api POST /decisions/ with workplan_id 2026-07-09 2026-08-20 3 2026-07-09
rest_api:POST /progress/ workstream_id rest_api POST /progress/ with workplan_id 2026-07-08 2026-08-20 14 2026-07-10
rest_api:POST /tasks/ workstream_id rest_api POST /tasks/ with workplan_id 2026-07-08 2026-08-20 5 2026-07-08
rest_api:POST /workstreams/ rest_api /workplans/ 2026-06-04 2026-08-20 824 2026-07-08
rest_api:POST /workstreams/{workstream_id}/dependencies/ rest_api /workplans/{workplan_id}/dependencies/ 2026-06-04 2026-08-20 4,971 2026-07-01

Retired earlier (1)

Interface Kind Replacement Legacy since Retired All-time calls Last seen
event_subject:org.statehub.workstream.completed event_subject org.statehub.workplan.completed 2026-06-04 2026-07-08 255 2026-07-08

Still legacy — held, not retired (4)

These carry the workstream spelling but did not meet the standard on 2026-08-20. They are the three six-figure read paths plus one with live traffic — the set where a premature retirement would do the most damage.

Interface Replacement All-time calls Last seen Held because
rest_api:GET /workstreams/{workstream_id} /workplans/{workplan_id} 511,406 2026-07-31 quiet 19d of 60d required for 511406 all-time call(s)
rest_api:GET /workstreams/{workstream_id}/dependencies/ /workplans/{workplan_id}/dependencies/ 255,865 2026-07-08 quiet 42d of 60d required for 255865 all-time call(s)
rest_api:GET /workstreams/ /workplans/ 144,086 2026-08-10 quiet 9d of 60d required for 144086 all-time call(s)
rest_api:GET /tasks/?workstream_id /tasks/?workplan_id=<workplan_id> 595 2026-08-19 5 call(s) in review window

The quiet counters run on their own. Re-capture before deciding — the ladder is evaluated at review time, so an old capture is not evidence for a later retirement.

Updating this journal

After each retirement round in state-hub:

cd ~/state-hub
uv run python scripts/capture_legacy_meter_evidence.py --retire-keys ""

Then append a dated section here with the same columns. Keep retired rows forever — the point of the journal is that a reader in 2027 can tell what GET /workstreams/ was, what replaced it, and on what evidence it was removed.

Last updated: 2026-08-20