diff --git a/docs/retired-legacy-interfaces.md b/docs/retired-legacy-interfaces.md new file mode 100644 index 0000000..c1d2e3e --- /dev/null +++ b/docs/retired-legacy-interfaces.md @@ -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=` | 2026-07-09 | 2026-08-20 | 1 | 2026-07-09 | +| `rest_api:GET /progress/?workstream_id` | rest_api | `/progress/?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=` | 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*