Router Byte Trial · Full Doctrine

A route declaration is an intent (TC-0). A compiled binary containing that route is a declaration (TC-1). A stat() call confirming the static file exists is gate evidence (TC-2). A SHA-256 hash of the file content is the notarized truth (TC-6). The Router Byte Trial doctrine formalizes this chain: every route must declare, assert its file, pass the middleware chain, and only then serve. No naked mux handles. No unverified static claims.

// Before: flat string map — just a name
routes := map[string]string{
    "/foo": "foo.html",
}

// After: RouteSpec — a legal claim with assertion fields
type RouteSpec struct {
    Pattern   string   // URL pattern registered with mux
    File      string   // Static file path (relative to static/)
    SHA256    string   // Expected SHA-256 hex of file content
    Stat      bool     // Whether stat() was verified at boot
    Warm      bool     // Whether file was pre-loaded into cache
    Chain     []string // Named middleware chain required
    TrialID   string   // TrendalTrial ID if under active trial
}

// RouteManifestEntry — serializable record for /__router__/manifest
type RouteManifestEntry struct {
    Pattern   string    `json:"pattern"`
    File      string    `json:"file"`
    SHA256    string    `json:"sha256"`
    StatOK    bool      `json:"statOk"`
    WarmState string    `json:"warmState"` // cold|warming|warm
    Chain     []string  `json:"chain"`
    AssertedAt time.Time `json:"assertedAt"`
}

// mustAssertRoutes validates all registered routes at boot time.
// It performs stat() and SHA-256 hash checks for every static file.
// If any route fails assertion, the server panics — it will not start.
// This is the Router Byte Trial admission gate.
func mustAssertRoutes(specs []RouteSpec, staticDir string) []RouteManifestEntry {
    manifest := make([]RouteManifestEntry, 0, len(specs))

    for _, spec := range specs {
        filePath := filepath.Join(staticDir, spec.File)

        // TC-2: Gate — stat() check
        info, err := os.Stat(filePath)
        if err != nil {
            panic(fmt.Sprintf(
                "ROUTER BYTE TRIAL FAIL: route %q — stat(%q) failed: %v",
                spec.Pattern, filePath, err,
            ))
        }
        if info.IsDir() {
            panic(fmt.Sprintf(
                "ROUTER BYTE TRIAL FAIL: route %q — %q is a directory, not a file",
                spec.Pattern, filePath,
            ))
        }

        // TC-6: WORM — SHA-256 hash check
        f, err := os.Open(filePath)
        if err != nil {
            panic(fmt.Sprintf(
                "ROUTER BYTE TRIAL FAIL: route %q — open(%q) failed: %v",
                spec.Pattern, filePath, err,
            ))
        }
        h := sha256.New()
        if _, err := io.Copy(h, f); err != nil {
            f.Close()
            panic(fmt.Sprintf(
                "ROUTER BYTE TRIAL FAIL: route %q — hash(%q) failed: %v",
                spec.Pattern, filePath, err,
            ))
        }
        f.Close()

        actual := fmt.Sprintf("%x", h.Sum(nil))
        if spec.SHA256 != "" && actual != spec.SHA256 {
            panic(fmt.Sprintf(
                "ROUTER BYTE TRIAL FAIL: route %q — SHA256 mismatch\n  expected: %s\n  actual:   %s",
                spec.Pattern, spec.SHA256, actual,
            ))
        }

        manifest = append(manifest, RouteManifestEntry{
            Pattern:    spec.Pattern,
            File:       spec.File,
            SHA256:     actual,
            StatOK:     true,
            WarmState:  "cold",
            Chain:      spec.Chain,
            AssertedAt: time.Now(),
        })

        log.Printf("[ASSERT OK] %-40s -> %s (sha256: %s...)", spec.Pattern, spec.File, actual[:12])
    }

    return manifest
}

// Correct: every handler goes through Alice chain
chain := alice.New(
    middleware.RequestID,
    middleware.Logger,
    middleware.RateLimit,
)

// Standard static route — full chain
mux.Handle("/labr-075", chain.ThenFunc(serveStatic("labr-075-router-doctrine.html")))

// Even internal endpoints wear the chain
mux.Handle("/__router__/manifest", chain.ThenFunc(serveManifest))
mux.Handle("/readyz",              chain.ThenFunc(serveReadyz))

// FORBIDDEN: naked handle
// mux.HandleFunc("/readyz", readyzHandler)  // NO. Chain it.