LABR-070 · Go Router Doctrine · Cube Catch-All + Chi Migration Arc

§1 — What We Proved Today

Root Cause

The Auto-Redirect Trap

Registering /clo in the routes map caused Go 1.22 ServeMux to silently claim /clo/ as a redirect target. All 5 CLO GOAT URLs returned 404 despite correct file existence and ingress config.

Go 1.22 quirk #1 90min investigation

Secondary Cause

Wrong Backend in Ingress

The /clo/* ingress paths were pointing to pemos-portal (scaled to 0) from a previous session. They needed to point to mefine-static.

ingress backend mismatch 5 paths fixed

Resolution

Cube Catch-All Doctrine

Move slash-nested route families into the "/" catch-all with prefix dispatch. Bypasses Go mux pattern registration for all paths that would trigger auto-redirect conflicts.

v154 deployed doctrine filed

§2 — The Six Go 1.22 ServeMux Quirks

Quirk 1 — CRITICAL

Registering /foo auto-claims /foo/ with a 301 redirect. Any explicit Handle("/foo/", ...) registered after is silently ignored.

Quirk 2

{$} end-of-path marker required to match exactly /foo/ without also matching /foo/bar. Missing from many route designs.

Quirk 3

Pattern conflict panics at registration. Panics may be silent in production binaries, leaving first-registered handler active.

Quirk 4

Method-specific routes (GET /foo) interact non-obviously with catch-all routes (/foo). Registration order affects behavior.

Quirk 5

{name} captures one segment only. {name...} for remainder capture. Mismatch causes silent 404s on nested paths.

Quirk 6

Hostname in pattern string activates host-based routing silently. Accidental use causes 404 for all requests without matching Host header.

§3 — Cube Catch-All Doctrine (Canonical)

CUBE CATCH-ALL · Pattern for Slash-Nested Route Families

Any route family of the form /prefix/<name> that would conflict with an existing /prefix registration: handle in the "/" catch-all with explicit prefix dispatch.

// The Pattern
dispatchMap := map[string]string{
    "amani":   "clo-amani-sovereign.html",
    "harvey":  "clo-harvey-sovereign.html",
    // ...
}
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
    if strings.HasPrefix(req.URL.Path, "/clo/") {
        name := strings.TrimSuffix(strings.TrimPrefix(req.URL.Path, "/clo/"), "/")
        if file, ok := dispatchMap[name]; ok {
            serveEmbedded(w, file); return
        }
        http.NotFound(w, req); return
    }
    // ... rest of catch-all
})

This is the Quasicrystal node pattern: each named node in the family is a vertex in a quasicrystal graph. The dispatch map IS the crystal lattice. Adding a new GOAT = adding a vertex. The catch-all is the crystal's ambient space.

§4 — Migration Arc to Chi

NOW · Cube Doctrine
stdlib + catch-all

NEAR · Chi Pilot
new services only

MID · Hybrid
chi wraps mefine

FAR · Full Chi
all routes unified

Chi is the primary recommendation for new Go services in the fleet. It uses the same http.Handler interface (full stdlib compat), has explicit non-magical routing, first-class middleware, and route grouping. No auto-redirects. No implicit behavior. Aligns with SET-OPS sublime entity principle: each route is either present or not — no intermediate states.

§5 — Quasicrystal + Living Graph Weave

The Cube Catch-All dispatch map is a quasicrystal: non-periodic, deterministic, each vertex (route name) connects to exactly one file node. The living graph weave:

Quasicrystal Layer

Route Crystal

Each dispatchMap entry is a crystal vertex. The catch-all is the lattice boundary. Adding routes = growing the crystal. Removing = pruning without breaking symmetry.

quasicrystal routing

SOT Living Graph

Route as Graph Edge

Each route maps URL node → file node → crew node. In the SOT graph: AMANI owns /clo/amani. HARVEY owns /clo/harvey. The graph edge carries crew provenance.

SOT graph edge crew provenance

SET-OPS Validation

Route Assertion

SET-OPS gate: for each entry in dispatch map, assert file exists in embed FS at startup. If any assertion fails → pod fails to start → rollout blocked. No silent 404s.

startup assertion gate enforced