glm-5.2
1baa619ce9
The monolithic open-questions.md (1310 lines, 47 OQs) was large enough to be unmanageable, with high size variance (OQ-42 at 220 lines next to OQ-06 at 8). Decomposed into one file per OQ under docs/architecture/questions/ (NNN-slug.md, mirroring the ADR convention), with open-questions.md retained as the index: theme-grouped tables plus a cross-theme Deferred/Blocked section that surfaces the 6 deferred OQs with their Blocked-on conditions inline (the safe-exit visibility surface). Per-OQ content moved verbatim; all 62 inbound links stay valid (none used anchors). README's curated OQ summary dropped (now redundant with the index tables). Also seeds tasks/architecture/ with this task plus two follow-ups found during the decompose: OQ-09/10 missing structured Blocked-on fields, and the tasks/architecture/ blocker-task half of the Safe Exit protocol being unenforced.
3.1 KiB
OQ-39: to_openapi Published-Spec Versioning
-
Origin: ADR-017 Consequences, http-adapters.md
-
Status: resolved (2026-06-30 by ADR-045)
-
Door type: One-way (after first publication), two-way (before)
-
Priority: medium → resolved
-
Resolution: ADR-045 commits the versioning scheme. The gateway pattern (ADR-042) dissolved most of the original concern: the published doc describes 5 fixed gateway endpoints (
/search,/schema,/call,/batch,/subscribe), not the per-operation surface. Per-caller operation changes (add/remove/modify an operation, change an operation's schema) do not change the published doc — the operation set is discovered at runtime viaAccessControl-filtered/search, not preloaded into the doc. So the version does not churn on every operation change (the original OQ-39 worry, framed under the pre-ADR-042 per-operation-paths model).What remains is narrow: how the published gateway doc signals its version. The decision:
to_openapiemitsinfo.versionas semver. Standard OpenAPI field, standard semver interpretation — no alknet-specific detection mechanism.- The version tracks the gateway endpoint contract, not the operation set. Major = breaking change to the gateway (endpoint removed/renamed, required request field added, response shape changed, error-mapping semantics changed per ADR-023); Minor = additive (new endpoint, new optional field); Patch = wording/docs. Per-caller operation changes do not bump the version.
- Bump on change to the gateway shape, not on regeneration. A restart that regenerates the same gateway shape yields the same version.
- Consumers detect breaking changes via the major version. A
client compares
info.version's major component to the version it built against; a major bump signals "re-read the doc, something broke." Minor/patch are informational. - The additive traditional per-operation-paths projection (ADR-042 §5) versions independently on its own schedule — its surface does change with the operation set, so its versioning is the per-operation churn the original OQ-39 framed. That projection is opt-in and out of scope for ADR-045; the gateway doc is the default published contract and the one ADR-045 governs.
The original "version marker emitted so consumers can detect mapping changes" constraint (from ADR-017 Consequences) is satisfied by
info.versionsemver. ADR-045 lifts the "published artifact is a contract" blind spot in ADR-009's framework (it classifies doors by reversal cost in the codebase, not by compatibility cost for external consumers) into its Context and honors the constraint without changing ADR-009's framework. -
Cross-references: ADR-009, ADR-017, ADR-023, ADR-036, ADR-042, ADR-045, http-adapters.md