docs(adr): generalize ADR-001 motivation — drop private consumer name and its internal ADR reference

The framework ADR must be self-contained: it described the motivating failure
modes by naming a specific downstream service and one of its internal ADRs, which
no framework reader has context for. Reworded to 'a downstream service' and to the
general authorization-boundary rationale.
This commit is contained in:
2026-08-14 01:08:36 -06:00
parent a778227fc2
commit e76dc48688
+4 -3
View File
@@ -26,7 +26,7 @@ So the two most ordinary REST shapes — `GET /roles/{id}` and
`HandlerFunc` and hand-write the decode, the validation call, the encoding and the `HandlerFunc` and hand-write the decode, the validation call, the encoding and the
status. This is a **correctness** problem, not only ergonomics: `HandlerFunc` is the status. This is a **correctness** problem, not only ergonomics: `HandlerFunc` is the
single path by which a handler reaches production without `v.Struct(req)` ever single path by which a handler reaches production without `v.Struct(req)` ever
running. Two failure modes followed, both observed in a consumer (`kch-core-svc`): running. Two failure modes followed, both observed in a downstream service:
1. **Unvalidated bounds** — a list endpoint that forgets to clamp answers 1. **Unvalidated bounds** — a list endpoint that forgets to clamp answers
`?per_page=99999`; the validator that would refuse it is not in the code path. `?per_page=99999`; the validator that would refuse it is not in the code path.
@@ -73,8 +73,9 @@ validates the assembled struct once with the `valid.Validator` already in scope.
There is no `header:` tag, in this version or a later one. Headers are middleware's There is no `header:` tag, in this version or a later one. Headers are middleware's
concern (authentication, request identity, tenancy). A `header:` tag would make one concern (authentication, request identity, tenancy). A `header:` tag would make one
specific mistake ergonomic — filling a tenant/actor identifier from a value the specific mistake ergonomic — filling a tenant/actor identifier from a value the
client fully controls — which `kch-core-svc`'s own ADR-007 forbids. Reducing that client fully controls, exactly the boundary a service's own authorization rules
mistake to one word in a struct tag would make it likely rather than merely possible. exist to defend. Reducing that mistake to one word in a struct tag would make it
likely rather than merely possible.
## Options considered ## Options considered