timothy
fba5233caf
168 records -> docs/decisions/records/<area>/<topic>.md (163 active, 23 dirs) and docs/decisions/archive/<area>/<topic>.md (5 archived). The filename IS the key, so one-active-record-per-key becomes a filesystem property rather than a validator check, and supersession becomes a `git mv`. WHY: the monolith was a concurrency problem before an aesthetic one. A 3,900-line append target made parallel sessions collide -- PR #605 and PR #614 both hit append-vs-append conflicts during routine rebases, and hand-resolving those inside the corpus is exactly the operation the rationale-rewrite guard exists to police. HOW IT IS VERIFIED: a ~170-file diff cannot be meaningfully read, so correctness does not rest on reading it. The parser was taught BOTH formats first, so the body-diff guard parses the old form at the merge-base and the new form at head -- the migration validates itself, no bypass. The proof is a field-level equivalence harness: 168 records before and after, zero lost, zero gained, zero field mismatches, zero rationale bodies differing. Reviewers should scrutinise the harness; it is the actual evidence. What measuring caught that reading would not have: - ~500 lines sit OUTSIDE any record -- decisions.md's lifecycle schema and each topic file's preamble, mostly the only copy. Source files are kept and stripped, never deleted. They also cannot be filed per-area: topic files hold several areas and 4 of 23 areas span several files. - Archive discovery was a non-recursive glob; after the split it found ZERO archived records, surfacing as four bogus "supersedes points to unknown key" errors rather than an obvious failure. - ~32 live docs point into the corpus BY DATE, which the split dangles. Each stripped file now ends with a generated "Records formerly in this file" index, which also rescues the identical breadcrumbs in old issue comments. - decisions.md's "In this file:" list was 97 same-file anchor bullets that the split makes WRONG, not merely stale. Dropped; the generated index replaces them with links that resolve. The equivalence harness now runs against a checked-in FIXTURE, not the live corpus. The earlier version migrated the real tree, which made it a one-shot: the moment the migration landed there was nothing left to move and the tests failed for reasons unrelated to the code. A fixture keeps them testing the SCRIPT rather than the repo's current state. Keys preserved verbatim, warts included: `sched` (12) and `scheduling` (1) remain two directories for one concept. Renaming a key is not a move -- it changes identity, breaks the equivalence proof, and invalidates MemPalace's per-key drawers. Taxonomy normalisation is separate work. refs #610
4.3 KiB
key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
| key | title | status | since | supersedes | superseded-by | rule | signals | mechanics |
|---|---|---|---|---|---|---|---|---|
| api.versioning-v1 | 2026-07-13 — API versioning: the whole `/api` surface is mounted at `/api/v1`, additive-only after freeze (#286) | active | 2026-07-13 | none | none | The entire `/api` surface is versioned to `/api/v1` uniformly (no unversioned corner); legacy unversioned callers are rewritten in-pipeline (not redirected) with Deprecation/Link/Sunset headers, and post-freeze `/api/v1` is additive-only — a breaking change requires `/api/v2`. | `ApiVersionRewriteMiddleware`, `ApiRouteVersioningTests`, RFC 8594 Deprecation header · paths: `docs/api-conventions.md` §1/§9 · issues: #286, #197 | `ApiRouteVersioningTests`, `docs/api-conventions.md` §1/§9 |
The #197 cold review's C1 BLOCKER: /api/* was entirely unversioned (info.version was cosmetic), so the
first breaking change would silently break the SPA and any external/MCP client with no negotiation path. This is
the Phase-2 contract-freeze gate — versioning can't be added compatibly after the contract ossifies, so it
lands before freeze.
What changed. Every route under /api was swept to /api/v1 — all 251 controller route attributes, the ~24
Location-header literals, the scanner callback URL (CallLibraryScannerHandler.GetBaseUrl), and the
Startup request-log path literal. This is uniform: the machine JSON API, the browser-session auth surface
(/api/v1/auth/*, still IgnoreApi), the internal loopback callbacks (/api/v1/scan/*) and the scripted-build
surface (/api/v1/scripted/*) are all versioned, so there is no unversioned corner and the compat rewrite needs
no exclusion list. The OpenAPI v1.json (160 paths), endpoint-index.md, and the SPA (945 request literals +
its test mocks, incl. regex/positional URL parsers) were regenerated/swept in lockstep. No wire-DTO or
status-code change — only the path prefix moved.
Legacy compat = an in-pipeline rewrite, NOT a redirect (ApiVersionRewriteMiddleware, sequenced before
UseRouting in the API branch). A legacy caller hitting an unversioned /api/foo has its request path
rewritten to /api/v1/foo and continues in-pipeline — method, body, auth headers and query string all survive,
so curl / the future MCP server / bookmarked URLs keep working with no round-trip (a 307/308 redirect would have
been fragile for non-GET + custom-header clients). Rewritten (legacy) responses carry RFC 8594 Deprecation: true
Link: </docs>; rel="deprecation", and aSunsetheader whenApi:LegacyRoutesSunsetis configured. An already-versioned path (/api/v1/*) passes through untouched; a future/api/v2/*is not forced back to v1 (the middleware only fills in a missing version).
Freeze semantics (owner decisions): once shipped, /api/v1 is additive-only — new endpoints/optional
fields are fine; renaming/removing/retyping an existing one requires a new /api/v2, never an in-place break.
The legacy-rewrite compat shim has a 2-release sunset window (owner-chosen) before removal; the actual removal
is a tracked Phase-3 follow-up, not this PR. Existing pre-freeze warts (e.g. channel {id} vs {channelNumber},
the synthesized negative-id "(none)" group rows) are frozen as-is per their own prior decisions.
Route-convention standardization (#286, owner-requested). The leading-slash inconsistency (238 absolute
"/api/…" method routes vs 13 relative "api/…") is resolved: the standard is a leading-slash absolute route
on each method's [Http*] attribute, no class-level [Route] — except the two controllers where many actions
share a parametrized prefix (ScannerController {scanId}, ScriptedScheduleController {buildId}, ~40
methods), which keep a leading-slash absolute class [Route("/api/v1/…")] with relative method segments (the
right tool for a shared prefix). Enforced by ApiRouteVersioningTests: it reflects over every [ApiController]
in Controllers.Api, computes each action's effective route (ASP.NET's class+method combination rule), and
asserts it matches ^/api/v\d+/ — so a new controller that drifts (relative or unversioned) fails CI, the
"fix-it-while-you're-in-the-file" gate the dotnet format rules use. Browser-nav endpoints deliberately outside
/api (e.g. GET /auth/oidc/login) are out of scope for the test. Docs: api-conventions.md §1/§9. Refs #286 #197.