Design Documents¶

This section preserves the full design rationale behind go-codex's foundational, cross-cutting architectural patterns — decisions that shaped how MULTIPLE apis/ports work, not a single feature. Unlike docs/roadmap/, everything here IS implemented and shipped; unlike docs/concepts/, these are not usage guides — they keep the ORIGINAL reasoning, rejected alternatives, and the review history that led to the shipped design, for future maintainers extending the same pattern to a new boundary.

A document graduates here from docs/roadmap/ — and only from there — when it meets either bar:

• It is fully shipped AND establishes a pattern multiple apis/ports/packages are expected to follow (not a single-adapter feature); or
• The design fundamentally changes how an existing api/port/package works.

This is a deliberately high bar, reserved for bigger architecture designs and reworks worth keeping in full. Most shipped roadmap docs still just follow docs/roadmap/'s own existing lifecycle (removed once shipped, or kept in place if a follow-on phase remains open) — see .github/skills/plan-a-new-codex-feature/SKILL.md for the exact policy.

Numbering convention¶

Every document here is filed as d-NNNN-<slug>.md — a sequential, zero-padded number assigned in the CHRONOLOGICAL order design docs were WRITTEN (not necessarily the order they shipped), mirroring an ADR-style numbering scheme. d-0001 is REST's own middleware/workflow simplification — the FIRST of these two designs, and the one the second one adopted and adapted concepts from. d-0002 is pub/sub's — written second, after REST's d-0001 had already landed, deliberately reusing and adapting as many of its concepts as pub/sub's own structural differences allow (role model, security merge/coverage, Client.Attach), with two-way sync back onto d-0001 itself whenever a gap surfaced in ONE that the other had already solved (see either doc's own addenda for the concrete back-and-forth). When promoting a NEW roadmap doc here, assign it the next sequential number — do not renumber existing documents.

Documents¶

| D-0007 — Declarative Middleware as Partial Route/Channel Definitions | middleware, api/rest, api/events, api/reqreply, adapters/mqtt5, adapters/mqtt, adapters/zeromq | States the general principle (confirmed via code, not aspirational) that a Middleware[In,Out] is a partial route/channel definition — its own merge-field-declared In/Out, stacked and aggregated with the route/channel's own declaration by the SAME mechanism in all 3 packages. Extracts a shared middleware.DecodeLayer/EncodeLayer mechanism (replacing 3 independently-duplicated per-package implementations); generalizes SecurityMiddleware[In,Out] in all 3 packages to dispatch its credential Fn through that shared mechanism via a conventional GrantedScopes Out field, merged (adapters/internal/scopesmerge) with any legacy Fn's own grants before ONE unified middleware.CheckScopes call, RECEIVING-side only (events' Subscribe, reqreply's Serve — never the sending side, confirmed via REST's own ClientMW, which never does this either). Extends middleware.ContextField[V] with SetContextFieldFromIn/SetContextFieldFromOut linking, so a middleware-derived value reaches the handler/caller automatically via context.Context, with zero manual re-extraction. Adds connection-level auth spec registration (Client.AddConnectSecurityScheme/Server.AddConnectSecurityScheme), closing a gap where a scheme referenced only via a Server.Security list (never by an individual route/channel) could not be spec-registered. Fully shipped in 3 rollout phases — Phase A (api/rest), Phase B (api/events), Phase C (api/reqreply) — each folding its own Transform/ClientTransform free functions into HandleMW/ClientMW/SubscribeMW/PublishMW directly via reflected-fn-shape detection (see D-0003's Addenda ⅘/6 for the compact per-phase shipped-changelog). Known, tracked, unfixed gap: .Use(mw).HandleMW(&mw, boundFn) for a Security-only mw throws DuplicateMiddlewareNameError in both api/rest and api/reqreply (not api/events) — a nontrivial design question (distinguishing a legitimate .Use()+bound combo from a genuine duplicate-name collision) deferred to a future session. Post-ship regression found and fixed (while adding real examples showcasing these capabilities): events.Client.Attach+ServeSubscribers — the PRIMARY workflow for all 3 pub/sub adapters — never dispatched bound SubscribeMW middleware or ContextField propagation at all; only the lower-level escape hatch (unit-tested, never used by Client.Attach) had the fix. Fixed across mqtt5/mqtt/zeromq; see this doc's own "Post-ship regression found and fixed" section for the full finding. | | D-0008 — Declarative Router Groups | api/rest, api/events, api/reqreply | A THIRD, group-level construct (distinct from Middleware) modeled on chi's own Router/Mount/Group/With/Routes/Walk: declares a path/topic PREFIX once and groups independently-declared Route/Channel-derived leaves (Route[Req,Resp]/SSERoute[Req,Event] for REST; Subscriber[T]/Publisher[T] for events; Route[Req,Resp] again for reqreply, the simplest variant with no second axis) under it, optionally attaching reusable-class middleware.RouteMiddleware to every leaf in one declaration instead of repeating .Use(mw) per route/channel. Router is a fully IMMUTABLE VALUE type (matching Route/Channel/Subscriber/Publisher exactly) — a deliberate, mid-design reconsideration that eliminated an earlier mutex-plus-pendingRoute-type draft entirely. Supports nesting (Mount), same-path/topic scoped-middleware subsets (Group, keeping chi's own baseline semantics for reqreply, method-scoped for REST, role-scoped for events), one-shot ad hoc middleware (With, accumulating not overwriting), and a Routes()/Walk() pair for a holistic, pre-registration view of the fully-assembled tree. WithHandleCallback (free function, all 3 patterns; events gets a role-targeted 3-way split mirroring Formats/SubscribeFormats/PublishFormats) recovers a grouped leaf's typed handle; ClientHandle's new variadic WithRouter opt (REST/reqreply only — events has no bare zero-argument accessor needing it) avoids a silent client/server path mismatch when a leaf is grouped under a Router on the server side. Fully shipped in 3 rollout phases — Phase A (api/rest), Phase B (api/events), Phase C (api/reqreply) — followed by a dedicated deferred-item review (6 "out of scope" candidates re-examined post-implementation, including concretely rejected alternatives for each: variable prefixes stay deferred as a deliberate simplicity-over-capability tradeoff; api/mcp support spun off as a prefix-less ToolGroup sketch in mcp-ports-declarative-middleware.md; bound-class middleware at Router level confirmed permanently impossible for this heterogeneous Router shape, with the strongly-typed Router[Req,Resp] alternative spun off into its own idea-stage doc, typed-router-groups.md; WithRouterTags and a ports.Pattern integration both gained concrete design sketches — including found gotchas/blockers — for a future implementer to start from; a Router-scoped fallback handler confirmed redundant for REST/events and structurally impossible for reqreply, given each pattern's real dispatch architecture). | | D-0009 — Internalizing Shared Cross-Pattern Mechanics | internal/router, internal/route, internal/middleware, api/rest, api/events, api/reqreply, stats | Relocated the public router/route/middleware packages under internal/, making "never imported by an end user of go-codex" a compiler-enforced fact (Go's internal/ import rule) instead of a documentation convention. Each pattern package gained its own thin public wrapper (type aliases + forwarding constructors) exposing the identical vocabulary — e.g. rest.BearerScheme/rest.SecurityMiddleware. Disposition/ResolveDisposition relocated to stats instead (not internal/middleware), since stats.DispositionObserver is a public, user-implementable extensibility interface. Migrated ~190 consumer files (~100 in-module, ~35 examples) with full build/vet/test/staticcheck/gosec/example verification at every phase. Establishes the standing design rule for future shared mechanics (codified in .github/instructions/go-codex.instructions.md, 2 skills, and review-go-codex's checklist §16). Addendum: SharedMiddleware/FromSecurityScheme (the legacy cross-pattern-shareable-value door shipped as part of this doc's original scope) were SUBSEQUENTLY REMOVED entirely in a later round — a from-scratch investigation found zero real callers needing a literal shared value across patterns; "shared config, declared twice per pattern" via each pattern's own SecurityMiddleware constructor is the sole surviving cross-pattern-sharing mechanism. Second Addendum: docs/roadmap/shared-api-layer-mechanics.md (the roadmap that originally phased the Router/Bound-Middleware/Error-Pattern consolidations feeding into this doc) was retired once all its phases resolved — its full phase-by-phase record (Bound Middleware's BoundCore-dropped correction and the real api/events spec-population bug found; the Declaration/Dispatch core phase's REJECTION, not deferral, once REST's and events' merge-field shapes were confirmed genuinely different-arity; Error-Pattern client helpers' consolidation) is folded into this doc's own second Addendum. |

How to read these documents¶

Each document here was originally a docs/roadmap/ design doc, refined through one or more critical review passes before and during implementation. Expect:

• Motivation — the problem that drove the pattern, and why a narrower fix wasn't enough
• Rejected alternatives — approaches considered and why they were set aside
• API surface — the actual shipped type signatures, as-built
• Known limitations and open risks — a running punch list, resolved item by item during implementation (kept, not deleted, so the reasoning survives)
• Coverage — how the pattern extends (or is planned to extend) across every api/port boundary it applies to, not just the first one it shipped for