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>
This commit is contained in:
codex
parent
dbccfd3073
commit
0ab3e359ce
1 changed files with 94 additions and 0 deletions
94
docs/retired-legacy-interfaces.md
Normal file
94
docs/retired-legacy-interfaces.md
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
# 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`:
|
||||
|
||||
```bash
|
||||
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*
|
||||
Loading…
Add table
Add a link
Reference in a new issue