OdbDesignServer — implementation plan (decisions applied)
| Status | ACTIVE — executing. All decisions recorded (incl. REST TLS cert source = Option C, 2026-09-10 follow-up). First tranche on nam/server-issues-impl: Phase 0 + M3.1. |
| Source | server-issues.md (options + pros/cons + decisions) — this doc turns those decisions into sequenced, file-level work. |
| Related | https-tls-options.md (REST TLS — DECIDED: Option C, 2026-09-10) · opt/phase2-grpc-optimizations.md (SI19 implementation spec) · gh-pages-coverage-integration.md |
| Method | Every milestone = one nam/<feature> branch → PR → nam20485, merged with merge commits only (AGENTS.md, directive 2026-09-10). C++ milestones ride the multi-platform PR builds; docs/workflow milestones ride the static checks. |
Decisions being implemented
| SI | Decision (from server-issues.md NOTE blocks) | Milestones |
|---|---|---|
| SI1 | Option 1 now — redoc.html in the swaggerui sidecar; annotation pass in the single swagger YAML. Spec-provenance question answered in §SI1-A below. |
M0.3, M0.4 |
| SI2 | Option B, branch set {development, release}. |
M0.5 |
| SI3 | Keep main; no changes. |
— (none) |
| SI4 | Decided 2026-09-10: Option 1 — Traefik IngressRouteTCP termination, app plaintext in-cluster. Cert source decided: Option C (cert-manager private CA, IP SANs) — M3.1 unblocked. |
M3.1 |
| SI5a | Keycloak on k3s + JWT bearers (Crow middleware + gRPC interceptor); stopgap hardening first. | M2.1–M2.3, M2.5 |
| SI5b | Option 1 — ownership sidecar metadata enforced at two choke points; device flow via Keycloak; sanitizeFilename fix included. |
M2.4 |
| SI6 | Items 1 (serialized-response cache) + 2 (ETag/Cache-Control); item 3 via SI7; item 4 opportunistic; 5/6 demand-driven. | M1.3, M1.4, M1.5 |
| SI7 | Option 1 — single-flight background load + RequestLoadDesign RPC + POST /designs/<name>/load + upload auto-warm; progress deferred to SI8. |
M1.1, M1.2 |
| SI8 | Option 1 — WebSockets events channel with polling fallback by construction. | M3.2 |
| SI19 | B+C hybrid — 2.1 + 2.2 now as standalone PRs; 1.3 (arenas) sequenced with SI6.1 under one benchmark. | M0.1, M0.2, M1.4 |
Phase overview (dependencies, not calendar):
Phase 0 (now, all parallel, no interdeps):
M0.1 proto arenas option M0.2 compression level M0.3 /redoc sidecar
M0.4 spec annotation pass M0.5 Pages per-branch coverage
Phase 1 (perf track, strictly ordered at the cache boundary):
M1.1 single-flight + LRU eviction ──► M1.2 background load + RequestLoadDesign
M1.3 ETag/Cache-Control (any time) M1.4 response cache + arenas (one benchmark) ──► M1.5 watcher (optional)
Phase 2 (identity track, strictly ordered):
M2.1 auth stopgaps ──► M2.2 Keycloak on k3s ──► M2.3 JWT middleware + interceptor
──► M2.4 ownership + device flow ──► M2.5 Basic removal
Phase 3 (edge & events):
M3.1 gRPC TLS (Option C — unblocked, first tranche) M3.2 WS /events (after M1.2)
Phase 0 — quick wins (parallel)
M0.1 — SI19.2.1: enable protobuf arenas in all .proto files
- Branch:
nam/grpc-arenas-option - Spec: phase2-grpc-optimizations.md Item 2.1 (implementation-grade; follow it verbatim).
- Files: all 26 protos under
OdbDesignLib/protoc/+OdbDesignServer/protoc/grpc/service.proto— addoption cc_enable_arenas = true;aftersyntax, delete the stale//option optimize_for = CODE_SIZE;comments. - Notes: wire-compatible, no behavior change. Regeneration wipes the build dir (keep
vcpkg_installed/) per the protobuf-gencode workspace rule. - Accept: full build (all presets); all tests pass;
grep -L cc_enable_arenas **/*.protoreturns nothing. - Effort: 1–2 h.
M0.2 — SI19.2.2: compression level config
- Branch:
nam/grpc-compression-level - Spec: phase-2 doc Item 2.2, plus the recorded delta:
OdbDesignServer/config.jsonnow hascompression: {enabled: true, algorithm: "gzip"}— the rewrite replaces two fields withcompression.level("none"|"low"|"medium"|"high", unknown →"high"), not one. - Files:
OdbDesignServer/Config/GrpcServiceConfig.h/.cpp(grpc_compression_levelreplacesbool compression_enabled; parse helper),OdbDesignServer/OdbDesignServerApp.cpp(SetDefaultCompressionLevelreplacesSetDefaultCompressionAlgorithm(GRPC_COMPRESS_GZIP)+ startup log),OdbDesignServer/config.json,OdbDesignTests/GrpcServiceConfigTests.cpp(four level strings + unknown fallback). - Accept: per phase-2 doc acceptance criteria, updated for the
algorithm-field removal. - Effort: 1–2 h.
M0.3 — SI1: /redoc page in the swaggerui sidecar
- Branch: sidecar repo change (image content) + this repo:
nam/redoc-route - This repo:
deploy/kube/local-ingress.yaml— add/redocpath route →odbdesign-server-swaggeruiservice (mirror the existing/swaggerblock at lines 19–25);deploy/nginx/nginx.conf— add alocation /redoc(or extend the swagger-ui catch-all at 153–165) serving the new page. Nodeploy.ps1change needed — the spec ConfigMap pipeline already refreshes both UIs. - Sidecar repo: add
redoc.htmlusing a vendored, pinnedredoc-standalonebundle (no CDN dependency — deployments are tailnet/LAN, may have no egress) pointing at the mounted spec path (/spec/odbdesign-server-0.9-swagger.yaml), cross-linked from swagger-ui and vice versa. - Accept:
https://<ingress>/redocrenders definitions from the ConfigMap spec;/swaggerunchanged; works in both k3s and compose shapes. - Effort: ~0.5 day (the annotation pass below is the long pole, not this).
M0.4 — SI1: annotation pass on swagger/odbdesign-server-0.9-swagger.yaml
- Branch:
nam/swagger-annotations - Work (all in the single YAML — both UIs consume it):
- Property-level
description:on every schema undercomponents/schemas, sourced from the comments inOdbDesignLib/protoc/*.proto. - Complete error-response sets per operation (
400/401/403/404/500). examples on all large schemas (StepDirectory,LayerDirectory,FeaturesFile,MatrixFile,Design,FileArchive).- Add the SI7/SI8 endpoints to the spec as they land (M1.2
POST /designs/<name>/load, M3.2/eventsnote); swap security schemes when M2.3 lands.
- Property-level
- Validation:
npx @redocly/cli lint(orswagger-cli validate) in CI as a docs job — catches YAML/schema errors the C++ builds can’t see (same rationale asAnalyze (actions)for workflow edits). - Accept: ReDoc Definitions panel fully described; linter passes with no errors (warnings triaged).
- Effort: 1–2 days (mostly transcription from proto comments — agent-shaped work).
SI1-A: spec provenance (curation + generation) — answer to the open question
The recorded question: can the spec be dynamically generated from source or live endpoints instead of hand-curated, and where does Kiota fit?
- From source code: no realistic path in Crow. Crow registers routes at runtime (
route_dynamic/CROW_ROUTE); it has no annotation/reflection facility for OpenAPI, and no generator exists for it. The C++ frameworks that do generate OpenAPI from code (Drogon ≥1.9 viadrogon_ctl, oat++ line) require a framework migration — not worth it for this. The proto layer is generatable (protoc already emits*_pb2.py-style descriptors) — and that’s exactly what the current spec’s schema blocks already mirror. The hand-curated YAML is the right source of truth for this codebase. - From live endpoints: possible but strictly worse. Traffic-capture tools (
mitmproxy2swagger,har-to-openapi) infer coarse schemas from observed JSON — no descriptions, wrong-guess types for proto3’s omitted-defaults, no enums/constraints. They would destroy the current detail level. Useful only as a verification signal, not a generator. - Kiota: wrong direction for this problem. Kiota is an OpenAPI consumer — it generates API clients from a spec, not specs from code. Once the spec is where we want it (M0.4), Kiota is an excellent way to generate typed clients for the server, and worth a look then. It cannot help produce the spec.
- The pragmatic best-of-both: drift checking (adopted). Keep the curated YAML as source of truth, and add a CI check that the route surface can’t silently drift from it:
- Add a build-flag-gated
GET /debug/routesendpoint that dumps Crow’s registered routes (Crow exposes the router’s rules — enumerate and serialize as JSON), OR a small script parsingCROW_ROUTE/route_dynamicregistrations fromControllers/*.cpp. - CI job diffs that route list against the spec’s
paths:— new/removed/renamed endpoints fail the check. - Schema-level drift (message shape vs spec components) stays manual for now; revisit if it bites. This keeps the annotation richness and gets the generator’s main benefit (no silent staleness). Fold into M0.4’s CI lint job.
- Add a build-flag-gated
M0.5 — SI2: per-branch coverage on Pages ({development, release})
- Branch:
nam/pages-coverage - Constraint (from gh-pages-coverage-integration.md): Pages = one deployment; only
jekyll-gh-pages.ymlmay calldeploy-pages— it stays the sole publisher. - Changes, all in
.github/workflows/jekyll-gh-pages.yml:- Keep triggers (
push: release,workflow_dispatch); addschedule: weekly(staleness refresh). - New step before
upload-pages-artifact: for each branch in[development, release]— find that branch’s latest successfulcode-coverage.ymlrun (gh run list --workflow=code-coverage.yml --branch=<b> --status=success --limit=1 --json databaseId,headSha,createdAt) andgh run download <id> -n linux-coverage-report, extracthtml/→_site/coverage/<b>/. (Degrade gracefully: missing/stale artifact → publish a placeholder page saying so, never fail the docs deploy.) - Generate
_site/coverage/index.htmllinking each branch report with its run SHA + date. - Permissions: add
actions: readto the existingcontents: read,pages: write,id-token: write. - Un-comment the Doxygen copy step (
cp -r ./OdbDesignLib/doxygen/html ./_site/api) —docs/README.mdlinks there — and fix those README links to the canonicalhttps://source.odbdesignserver.com. - Add a “Code coverage” link to the Jekyll index (
docs/index.md).
- Keep triggers (
- Also:
.github/workflows/code-coverage.yml— artifact retention 14 → 90 days (a quiet branch must stay fetchable between release-window deploys). - Never deploy from PRs (fork or otherwise) — keep deploy steps gated on the existing triggers.
- Accept: after a
releasepush:https://source.odbdesignserver.com/coverage/showsdevelopment/andrelease/reports with correct SHAs; site otherwise unchanged. - Effort: 1–2 days.
Phase 1 — performance track (touches the DesignCache hot path; ordered)
M1.1 — SI6.3: single-flight loads + byte-budget LRU eviction in DesignCache
- Branch:
nam/design-cache-singleflight - Depends: nothing (start of the perf track).
- Files:
OdbDesignLib/App/DesignCache.h/.cpp; newOdbDesignLib/App/DesignCacheConfig(or extendOdbDesignArgs):--cache-max-mb(default e.g. 4096). - Steps:
- In-flight map:
std::unordered_map<std::string, std::shared_future<std::shared_ptr<…>>>(two: archives + designs) guarded by a dedicated mutex.GetDesign/GetFileArchivemiss → emplace future (parse runs once; concurrent callers.wait()on the same future) → on completion, move into the existing maps and erase the in-flight entry. Preserve the current double-checked-locking semantics for readers. - Byte accounting: estimate per-design bytes (archive file size + serialized response sizes once M1.4 exists; file size until then) stored alongside each entry; LRU list on last-served time; evict from the front on insert over budget. Never evict an in-flight or failed entry.
- State machine hooks: per-design state (
Unloaded | Loading | Loaded | Failed) + an observer callback list (load started/finished/failed) — M1.2’s RPC, M3.2’s events, and M1.5’s invalidation all hang off this; design it now so they’re additions, not rewrites.
- In-flight map:
- Tests: concurrent
GetDesignon a cold design parses exactly once (instrument or count via test seam); eviction respects budget; failed parse doesn’t poison the cache (retry works). - Thread-safety review: this is the boundary change everything else depends on — review
FileArchive/Designconstruction for cross-thread safety (phase-1 gRPC work established the pattern). - Effort: 2–3 days.
M1.2 — SI7: background load + RequestLoadDesign + REST twin + upload auto-warm
- Branch:
nam/request-load-design - Depends: M1.1 (in-flight map + state machine).
- Files:
OdbDesignServer/protoc/grpc/service.proto:RequestLoadDesign(RequestLoadDesignRequest{design_name}) returns (RequestLoadDesignResponse{status, design_name});enum LoadStatus { ACCEPTED = 0; ALREADY_LOADING = 1; ALREADY_LOADED = 2; NOT_FOUND = 3; }.OdbDesignServer/Services/OdbDesignServiceImpl.cpp:RequestLoadDesign= state-machine lookup → ifUnloaded, kickDesignCache::LoadDesignAsync(async, does not wait) → return status.GetDesignsemantics unchanged (warm = data; cold = blocks — now no longer the only path).OdbDesignServer/Controllers/DesignsController.cpp:CROW_ROUTE … /designs/<string>/load(POST) →202 Accepted+ same status JSON.OdbDesignServer/Controllers/FileUploadController.cpp: afterfastmove_file, fire-and-forgetLoadDesignAsync(log failures; never fail the upload response on warm failure).- Config:
--max-background-loadssemaphore (default 2) to prevent upload-batch parse storms. swagger/odbdesign-server-0.9-swagger.yaml: document the POST route.
- Tests: in-process gRPC test (pattern of existing
OdbDesignTests/Grpc*Tests.cpp); REST route test; NOT_FOUND for unknown name; ALREADY_* transitions. - Accept:
RequestLoadDesignreturns in <100 ms for a large design; a subsequentGetDesignafter load completion returns data without re-parsing. - Effort: 2–3 days.
M1.3 — SI6.2: ETag + Cache-Control on data endpoints
- Branch:
nam/http-caching - Depends: nothing inside Phase 1 (can land before/parallel to M1.1/M1.2).
- Files:
OdbDesignLib/App/RouteController.cpp(or a smallUtils/ETag.hused by it): ETag = hash(design name, archive mtime, size, endpoint path); setETag+Cache-Control: private, max-age=3600on data GETs; honorIf-None-Match→304with empty body (before doing any serialization work — that’s the whole point). - Notes: applies to the per-design data endpoints, not the directory-list endpoints (those are cheap and change often). Gzip interplay: ETag must be the strong variant of the representation — compute before compression; vary handling via Crow’s existing compression middleware.
- Tests: 200 + ETag on first fetch; conditional refetch → 304; changed mtime → new ETag.
- Effort: ~1 day.
M1.4 — SI6.1 + SI19.1.3: serialized-response cache + arena allocation (one benchmark)
- Branch:
nam/serialized-response-cache(arenas may be a stacked branchnam/grpc-arena-allocoff it, or one PR — one benchmark either way). - Depends: M1.2 (populate after background load completes).
- Files:
- New
OdbDesignLib/App/ResponseCache(or extendDesignCache): keyed (design, variant) →std::stringJSON per endpoint family + serialized protobuf bytes forGetDesign. Populated by the M1.2 background-load completion callback; served byte-identical from cache. Byte accounting feeds M1.1’s budget. - Invalidation: archive mtime/size change (M1.5 watcher or reload check), re-upload overwrite (
FileUploadController),POST /filemodels/<string>(DesignCache::AddFileArchivepath). Invalidation drops the entries; next request re-populates. Airtight invalidation is the acceptance bar. - SI19.1.3 per the phase-2 spec:
IProtoBuffable::to_protobuf(TPbMessage*)default (swap-based) +FeatureRecordin-place override + arenas inGetLayerFeaturesStream/GetLayerFeaturesBatchStream. - Benchmark: a script (checked into
scripts/) timing N cold + N warm fetches of the largest test design, both channels, recorded in the PR before/after. One campaign covers M1.1–M1.4 + arenas.
- New
- Tests: warm response byte-identical to cold; invalidation on all three triggers; arena messages serialize identically (golden-message tests per phase-2 acceptance).
- Effort: 3–5 days.
M1.5 — SI6.4 (optional, opportunistic): designs-dir watcher
- Branch:
nam/designs-dir-watcher - Files:
DesignCache: background thread,std::filesystempolling at a slow interval (e.g. 5 s) — inotify is unreliable over PVC/network mounts, so polling-with-mtime-compare is the portable design; refresh cached listing (feeds list endpoints) + detect replaced archives → invalidate M1.4 entries via the M1.1 state machine. - Accept: list endpoints no longer scan per call; replacing an archive invalidates caches without server restart.
- Effort: 1–2 days.
Phase 2 — identity track (strictly ordered)
M2.1 — SI5a stopgaps (day one, regardless of Keycloak timing)
- Branch:
nam/auth-stopgaps - Files:
OdbDesignLib/App/BasicRequestAuthentication.cpp: delete theodb/plusplushardcoded fallback (lines 48–65); env creds missing + auth enabled → fail closed (503 with loud log on protected routes; startup warning). Update the spec’s auth description (it documents the fallback behavior).Utils/crow_win.h+ newOdbDesignLib/App/AuthMiddleware(Crow middleware in thecrow::Crow<CORSHandler, AuthMiddleware>stack) performing the check once per request before handlers; delete the per-handlerAuthenticateRequest(req)calls from all controllers. Skip-list:/healthz*,/ready,/helloworld*.OdbDesignServer/OdbDesignServerApp.cppCORS: origins fromODBDESIGN_SERVER_CORS_ORIGINSenv (comma list);*only when--disable-authentication.
- Tests: request without creds → 401 (not 403-with-fallback); missing env + enabled → fail closed; every existing route still enforced (middleware-level, so provable by construction); CORS headers match configured origins.
- Effort: ~1 day.
M2.2 — SI5a: Keycloak on k3s (Argo CD GitOps)
- Where: platform/deploy repo (GitOps branch
nam20485), not this repo — same place as the rest of the workload manifests (per the Argo CD handoff plan). No C++ changes. - Steps: pinned Keycloak chart (keycloakx) + Postgres w/ PVC; IngressRoute for
auth.<domain>(tailnet-only until M3.1’s TLS decision lands — do not expose plaintext beyond the tailnet); realm export JSON committed as config: realmodbdesign, rolesadmin/user, public clientsodbdesign-web(PKCE) andodbdesign-cli(device flow enabled); initial admin via one-time bootstrap secret, then disabled. - Accept: OIDC discovery (
/.well-known/openid-configuration) reachable in-cluster and from tailnet; device flow end-to-end with a throwaway user; Argo CD shows synced/healthy. - Effort: 2–3 days (mostly realm config; the yak-shaving line item).
M2.3 — SI5a: JWT validation in Crow middleware + gRPC interceptor
- Branch:
nam/jwt-auth - Depends: M2.1 (middleware shape), M2.2 (issuer exists).
- Files:
vcpkg.json: addjwt-cpp(pinned version, per the override rules in AGENTS.md).OdbDesignLib/App/TokenAuthentication(new, next toBasicRequestAuthentication): parseAuthorization: Bearer, verify against Keycloak JWKS (fetched at startup, refresh on unknownkid), checkiss/aud/exp, extractsub+ roles into a request-context struct. Shared by both channels.- Crow:
AuthMiddlewaregains modebasic | bearer | both(env/arg; defaultbothduring transition) — the transition window. - gRPC:
OdbDesignServer/Interceptors/AuthInterceptor(first interceptor in the codebase —ServerBuilder::InterceptorFactoryreturning a sync interceptor reading theauthorizationmetadata key, sameTokenAuthenticationcore; health/reflection services stay anonymous, everything else enforced). swagger/…swagger.yaml: addbearerAuthsecurity scheme alongsideBasicAuth.
- Tests: valid/missing/expired/wrong-audience tokens on both channels;
bothmode accepts either;--disable-authenticationstill bypasses (local dev). - Accept: a Keycloak-issued token fetches a design over REST and gRPC; Basic still works in
bothmode. - Effort: 2–4 days.
M2.4 — SI5b: ownership store + enforcement + device flow + sanitizeFilename
- Branch:
nam/design-ownership - Depends: M2.3 (identity in request context).
- Files:
- Ownership store in
DesignCache: sidecar<design>.meta.json({ "owner": "<sub>", "shared": "all" | "none" }), atomic write (temp + rename), loaded with the design, listed in directory scans; missing meta → synthesizeowner=admin, shared=all(legacy designs keep working; write-back optional). - Enforcement choke points (exactly two): REST —
RouteController/AuthMiddlewarepath check resolving design name from the route; gRPC — shared preamble helper inOdbDesignServiceImpl. Rule:adminrole passes;owner == subpasses;shared == allpasses; else 403 /PERMISSION_DENIED. Applies to reads, uploads (stampowner = sub), deletes when they exist, andRequestLoadDesign. FileUploadController::sanitizeFilename— implement it (strip path separators, control chars, reserved names, length cap); it’s a live traversal-shape gap in the same code being touched.- Device flow: documented client recipe (
docs/):odbdesign-clipublic client, device-authorization endpoint → approve in browser → poll → bearer token → sameAuthorizationheader. No server code beyond M2.3. - Swagger: annotate per-route auth notes; document the ownership model.
- Ownership store in
- Tests: owner/admin/stranger × shared/private matrix over both channels; upload stamps owner; legacy design without meta readable by all; filename sanitization cases.
- Effort: 3–5 days.
M2.5 — SI5a completion: remove Basic
- Branch:
nam/remove-basic-auth - Depends: M2.4 steady + clients migrated (the optimized client uses tokens).
- Files: delete
BasicRequestAuthentication+BasicAuthscheme from the spec; default auth mode →bearer;--disable-authenticationstays for local dev. - Effort: ~0.5 day.
Phase 3 — edge & events
M3.1 — SI4: gRPC TLS via Traefik IngressRouteTCP + Option C cert chain
- Decided: Option 1 mechanism (2026-09-10) + Option C cert source (cert-manager + self-managed CA, IP SANs — 2026-09-10 follow-up). Unblocked.
- Files (this repo):
scripts/make-tls-ca.sh(new): one-time CA generation (openssl req -x509, 10-yr EC root), usage documented.deploy/kube/cert-manager/(new): vendored, version-pinned cert-manager static manifest + README (CA distribution/import instructions per platform).deploy/kube/issuer-ca.yaml(new; retires the stale stagingissuer.yaml):IssuerkindCA→ secretodbdesign-root-ca.deploy/kube/certificate-odbs-server.yaml(new):CertificatewithipAddresses: [192.168.122.200, 100.118.225.119]+dnsNames: [odbdesign.local, debian13vm…]→ secretodbdesign-server-tls.deploy/kube/local-ingress.yaml: addtls:referencing the secret (host-less IP routing preserved — clients verify against SANs, not SNI).deploy/kube/OdbDesignServer/service-grpc.yaml:type: LoadBalancer→ClusterIP.deploy/kube/odbdesign-grpc-ingressroute-tcp.yaml(new):IngressRouteTCPon :50051 withtls:→ same secret, h2c backend.scripts/deploy.ps1: optional-EnableTlsflag applying the TLS pieces (default remains plaintext —https-tls-options.md§3.6);scripts/validate-grpc-exposure.ps1updated for TLS mode (grpcurl drops-plaintext).
- Files (this repo):
deploy/kube/OdbDesignServer/service-grpc.yaml→ convert fromtype: LoadBalancerto ClusterIP backend of a newIngressRouteTCPon :50051 withtls:(h2c to the backend);scripts/deploy.ps1applies it;scripts/validate-grpc-exposure.ps1updated (grpcurl drops-plaintext). - Notes: app stays plaintext in-cluster; revisit passthrough/app-native TLS only if mTLS for machine clients is ever wanted (SI5b follow-up, not now).
- Effort: ~1 day once unblocked.
M3.2 — SI8: WebSocket events channel (/events) with polling fallback
- Branch:
nam/ws-events - Depends: M1.2 (its events are the first payload).
- Files:
OdbDesignServernewEventsController:CROW_WEBSOCKET_ROUTEat/events; connection registry + broadcast helper; typed JSON events{type: "design.load.started|finished|failed" | "design.list.changed", design, ts, runId}sourced from the M1.1 observer callbacks. Auth: requires the M2.3 token (query-param or first-message token; WS headers are awkward from browsers).- Proxy configs: Traefik ingress handles WS upgrades — review idle timeouts;
deploy/nginx/nginx.confneeds an explicitlocation /eventswithUpgrade/Connectionheaders + raisedproxy_read_timeout. - Swagger + client contract note: the channel is optional by construction — clients feature-detect and fall back to REST polling (the status quo), never a dependency. State this invariant in the spec description and client docs; OpenAPI doesn’t model WS, so document as a note.
- Client reconnect/resume semantics documented (no
Last-Event-IDequivalent in WS — simple reconnect + refetch state).
- Tests: event broadcast on load lifecycle; connection drop → clients keep functioning via polling (fallback smoke test).
- Effort: 3–5 days.
Risk register
| Risk | Where | Mitigation |
|---|---|---|
DesignCache concurrency regressions |
M1.1–M1.4 | The state machine + single-flight land first and alone (M1.1); everything after consumes it; concurrent-parse test is the acceptance bar. |
| Cache invalidation misses (stale data served) | M1.4 | Three explicit invalidation triggers + tests for each; when in doubt, invalidate. |
| Auth cutover breaks clients | M2.3/M2.5 | both transition mode; Basic removal is its own late milestone after the optimized client is on tokens. |
| Ownership rollout locks out users | M2.4 | Legacy-synthesis rule (shared=all) keeps every pre-existing design readable; matrix tests. |
| Keycloak becomes a single point of failure | M2.2 | Server caches JWKS with refresh-on-unknown-kid; token validation keeps working through short IdP outages (already-issued tokens verify locally). |
| Memory growth from eager loads | M1.2 | M1.1’s budget/eviction is a hard prerequisite; background-load semaphore caps parse storms. |
| WS through proxies silently broken | M3.2 | Proxy configs are per-deployment acceptance criteria (k3s AND compose), not afterthoughts. |
Definition of done (per milestone)
- Branch
nam/<feature>fromnam20485; PR tonam20485; merge commit only (never squash/rebase). - Multi-platform builds + tests green (C++ milestones); lint/static checks green (docs/workflow milestones).
- Acceptance criteria above demonstrated in the PR description (benchmark numbers for M1.4).
- Swagger spec + docs updated in the same PR when the API surface changes.
- k3s + compose deployment shapes both updated when deploy files change.