# 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*