feat: greenfield Go rewrite (Phase 2A + 2B + 2C core)

Replaces the Python v1 (preserved on archive/python-v1 branch).

Stack: Go 1.23 + chi router + sqlx + MySQL 8. Distroless static
container. 12-factor config from env. Embedded SQL migrations.

Schema (internal/db/migrations/001_init.sql):
- topics: 议题 with 4-timestamp lifecycle (signup_open/close +
  debate_start/end), visibility (default private), status state machine,
  verdict_schema FK
- signups: agent self-enrollment with willing_camps (JSON array of
  pro|con|judge), pre_validated audit flag, (topic,agent) unique
- camps: post-allocation lock (one row per topic+camp) — written by
  Phase 2D allocator
- rounds + arguments: chronological debate transcript
- verdicts: judge structured output, one per topic, with token-cost
  trail for future budgeting
- agent_keys + system_keys: peppered sha256 hashes, never raw
- verdict_schemas: seeded with binary, claim-resolution (for
  analyze-intel), policy-recommendation, free-form

Auth (internal/auth):
- AgentAPIKey: real bearer-token middleware against agent_keys;
  best-effort last_used_at touch on success
- OIDCBrowser: Phase 2 stub. Dev mode accepts x-dev-bypass header
  (constant-time compare); prod 401s with a Phase-4-pending hint.
  Real Keycloak JWKS verification lands with the frontend rewrite.

HTTP API (internal/httpapi):
- /api/healthz — db ping + version + uptime
- GET /api/topics — list with status/visibility/limit/offset filters;
  anonymous callers see public only
- GET /api/topics/{id} — visibility-gated (private → 404 hide)
- POST /api/topics — create with RFC3339 lifecycle validation
  (signup_open < signup_close <= debate_start < debate_end)
- PUT /api/topics/{id}/visibility — dialectic-admin role gate
- POST /api/topics/{id}/signups — agent self-enroll; rejects when
  topic.status != signup_open OR outside signup window; idempotent
  upsert per (topic, agent)
- GET /api/topics/{id}/signups — list (any authed caller)

Auth chains:
- optionalAuth: try bearer → try oidc → fall through anonymous
  (handlers branch on Caller.Kind == ""). Uses captureWriter to demote
  inner 401s to "try next" without leaking response bytes.
- requireAnyAuth: chain that 401s if neither succeeds.
- requireAgent: strict bearer-only (signup POST).

Run: `docker compose -f docker-compose.dev.yml up --build`. Migrations
auto-apply on first connect; idempotent on reboot. README documents
env vars, dev bypass usage, agent-key provisioning SQL, and the
Phase 2D/E/3/4/5 roadmap.

go vet clean, gofmt clean, single 11M static binary.

internal/httpapi/routes.go

@@ -0,0 +1,177 @@
+package httpapi
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	chimw "github.com/go-chi/chi/v5/middleware"
+	"github.com/go-chi/cors"
+	"github.com/jmoiron/sqlx"
+
+	"git.hangman-lab.top/hzhang/Dialectic.Backend/internal/auth"
+	"git.hangman-lab.top/hzhang/Dialectic.Backend/internal/config"
+	"git.hangman-lab.top/hzhang/Dialectic.Backend/internal/httpapi/handlers"
+	"git.hangman-lab.top/hzhang/Dialectic.Backend/internal/store"
+)
+
+// Mount returns the root router with all v2 endpoints wired. Owners of
+// individual middleware chains:
+//
+//   - /api/healthz             : public (no auth)
+//   - /api/topics              : mixed — list/get optional auth (anon
+//     sees public only); create requires CallerAgent or CallerUser
+//   - /api/topics/{id}/signups : agent-only (CallerAgent)
+//
+// Browser-side OIDC and agent-side bearer middlewares co-exist on the
+// same route by being "optional auth" — if either succeeds, Caller is
+// attached; otherwise the handler sees anonymous and decides whether
+// to 401 or fall through to public behavior.
+func Mount(cfg *config.Config, db *sqlx.DB, version string) http.Handler {
+	r := chi.NewRouter()
+
+	// Boilerplate middleware — these run on every request.
+	r.Use(chimw.RealIP)
+	r.Use(chimw.RequestID)
+	r.Use(chimw.Logger)
+	r.Use(chimw.Recoverer)
+	r.Use(chimw.Timeout(30 * time.Second))
+	r.Use(cors.Handler(cors.Options{
+		AllowedOrigins:   cfg.CORSAllowOrigins,
+		AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
+		AllowedHeaders:   []string{"Accept", "Authorization", "Content-Type", "x-dev-bypass"},
+		ExposedHeaders:   []string{},
+		AllowCredentials: true,
+		MaxAge:           300,
+	}))
+
+	// Auth middlewares — composed as "try agent, then user, else pass anonymous".
+	optionalAuth := optionalAuthChain(db, cfg)
+	requireAgent := auth.AgentAPIKey(db, cfg.AgentAPIKeyPepper) // strict bearer
+	requireAnyAuth := requireAnyAuthChain(db, cfg)
+
+	// Handler instances.
+	topicStore := store.NewTopicStore(db)
+	signupStore := store.NewSignupStore(db)
+	health := handlers.NewHealthHandler(db, version)
+	topicsH := handlers.NewTopicsHandler(topicStore)
+	signupsH := handlers.NewSignupsHandler(topicStore, signupStore)
+
+	// Routes.
+	r.Route("/api", func(r chi.Router) {
+		r.Get("/healthz", health.Healthz)
+
+		// Topics: list+get optional-auth (visibility-gated by handler);
+		// create+visibility-flip require any auth.
+		r.Group(func(r chi.Router) {
+			r.Use(optionalAuth)
+			r.Get("/topics", topicsH.List)
+			r.Get("/topics/{id}", topicsH.Get)
+		})
+		r.Group(func(r chi.Router) {
+			r.Use(requireAnyAuth)
+			r.Post("/topics", topicsH.Create)
+			r.Put("/topics/{id}/visibility", topicsH.SetVisibility)
+		})
+
+		// Signups: agent-only.
+		r.Group(func(r chi.Router) {
+			r.Use(requireAgent)
+			r.Post("/topics/{id}/signups", signupsH.Create)
+		})
+		// List signups: any authenticated caller.
+		r.Group(func(r chi.Router) {
+			r.Use(requireAnyAuth)
+			r.Get("/topics/{id}/signups", signupsH.List)
+		})
+	})
+
+	return r
+}
+
+// optionalAuthChain: if either auth method succeeds, attach Caller;
+// otherwise let the request through anonymous. Handlers decide what
+// to do with anonymous (typically: serve public subset, hide private).
+func optionalAuthChain(db *sqlx.DB, cfg *config.Config) func(http.Handler) http.Handler {
+	agent := auth.AgentAPIKey(db, cfg.AgentAPIKeyPepper)
+	oidc := auth.OIDCBrowser(cfg.IsDev(), cfg.OIDCDevBypassToken)
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Bearer present → try agent path; on success it ServeHTTPs next.
+			// On failure it 401s, which we want to demote to "anonymous" for
+			// optional auth. The pattern is: capture the response; if it's
+			// 401, fall through to OIDC; if OIDC also 401s, finally fall
+			// through to next (anonymous).
+			if r.Header.Get("authorization") != "" {
+				rw := &captureWriter{ResponseWriter: w}
+				agent(next).ServeHTTP(rw, r)
+				if rw.status != http.StatusUnauthorized {
+					return
+				}
+				// reset captured state and try anon path (since OIDC
+				// won't apply if there's no cookie / bypass header)
+			}
+			if r.Header.Get("x-dev-bypass") != "" {
+				rw := &captureWriter{ResponseWriter: w}
+				oidc(next).ServeHTTP(rw, r)
+				if rw.status != http.StatusUnauthorized {
+					return
+				}
+			}
+			// Anonymous — call next with no Caller attached.
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+// requireAnyAuthChain: 401 if neither agent nor user auth succeeds.
+func requireAnyAuthChain(db *sqlx.DB, cfg *config.Config) func(http.Handler) http.Handler {
+	agent := auth.AgentAPIKey(db, cfg.AgentAPIKeyPepper)
+	oidc := auth.OIDCBrowser(cfg.IsDev(), cfg.OIDCDevBypassToken)
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Header.Get("authorization") != "" {
+				rw := &captureWriter{ResponseWriter: w}
+				agent(next).ServeHTTP(rw, r)
+				if rw.status != http.StatusUnauthorized {
+					return
+				}
+			}
+			oidc(next).ServeHTTP(w, r)
+		})
+	}
+}
+
+// captureWriter records the status so the optional-auth chain can
+// distinguish "401 from inner middleware (try next)" from "actual
+// response from handler (deliver)". Body bytes are passed through
+// when status != 401.
+type captureWriter struct {
+	http.ResponseWriter
+	status      int
+	wroteHeader bool
+	suppressing bool
+}
+
+func (c *captureWriter) WriteHeader(s int) {
+	c.status = s
+	c.wroteHeader = true
+	if s == http.StatusUnauthorized {
+		// don't actually write — we may fall through
+		c.suppressing = true
+		return
+	}
+	c.ResponseWriter.WriteHeader(s)
+}
+
+func (c *captureWriter) Write(b []byte) (int, error) {
+	if c.suppressing {
+		// swallow; caller will fall through to next chain step
+		return len(b), nil
+	}
+	if !c.wroteHeader {
+		c.ResponseWriter.WriteHeader(http.StatusOK)
+		c.wroteHeader = true
+	}
+	return c.ResponseWriter.Write(b)
+}