hzhang
e706f3d6ef
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.
Dialectic.Backend — v2 (Go)
Greenfield Go rewrite of the Python v1 backend. Agent-native debate
platform per /home/hzhang/arch/DIALECTIC-V2-DESIGN.md.
Python v1 history is preserved on branch archive/python-v1.
What's here (Phase 2A + 2B + 2C, 2026-05-23)
| Subsystem | Status |
|---|---|
HTTP server (chi router) |
✅ |
Config from env (internal/config) |
✅ |
MySQL via sqlx + embedded SQL migrations |
✅ |
Schema: topics, signups, camps, rounds, arguments, verdicts, agent_keys, system_keys, verdict_schemas |
✅ |
| Auth middlewares: agent bearer (real), OIDC browser (Phase 2 stub w/ dev bypass) | ✅ |
/api/healthz |
✅ |
/api/topics list / get / create / set-visibility |
✅ |
/api/topics/{id}/signups list / create (agent self-enroll) |
✅ |
| Orchestration engine (camp allocation, round driver, judge invocation) | ⬜ Phase 2D |
| SSE live transcripts | ⬜ Phase 2D |
| Full OIDC + Keycloak JWKS verification | ⬜ Phase 4 |
| Nginx + CF Origin Cert on server.t3 | ⬜ Phase 2E |
Layout
main.go entrypoint (load → wire → serve)
go.mod
Dockerfile
docker-compose.dev.yml backend + mysql for local iteration
internal/
config/ 12-factor env loader
db/
db.go sqlx + embedded migration runner
migrations/001_init.sql v2 schema, idempotent
models/ entity types (sqlx + json tags)
store/ query layer (per-entity)
auth/ agent api-key + oidc middlewares
httpapi/
routes.go chi router + auth chains
handlers/ per-endpoint handlers
Run locally
docker compose -f docker-compose.dev.yml up --build
# backend on http://localhost:8090
curl http://localhost:8090/api/healthz
Env vars (see internal/config/config.go for the full list):
| Var | Default (dev) | Required in prod |
|---|---|---|
ENV_MODE |
dev |
must be prod |
HTTP_ADDR |
0.0.0.0:8090 |
— |
CORS_ALLOW_ORIGINS |
* |
concrete list (no *) |
DB_HOST/PORT/NAME/USER/PASSWORD |
dev defaults | ✓ password required |
AGENT_API_KEY_PEPPER |
— | ✓ |
OIDC_ISSUER / OIDC_CLIENT_ID |
— | ✓ |
OIDC_DEV_BYPASS_TOKEN |
unset | ignored in prod |
SYSTEM_API_KEY |
unset | populate when announce-channel push lands |
Dev bypass for browser routes
In ENV_MODE=dev with OIDC_DEV_BYPASS_TOKEN=<token> set:
curl -H "x-dev-bypass: <token>" http://localhost:8090/api/topics
# attached as user 'dev-operator' with role 'dialectic-admin'
In prod, this header is ignored regardless of value.
Agent bearer for plugin routes
The OpenClaw plugin (Dialectic.OpenclawPlugin, Phase 3) calls with:
Authorization: Bearer <raw-agent-api-key>
The key is hashed with AGENT_API_KEY_PEPPER and matched against
agent_keys.key_hash. To provision an agent's key (Phase 3 will add a
proper hf user create-dialectic-key CLI; for now, manual SQL):
INSERT INTO agent_keys (agent_id, key_hash)
VALUES ('manager', SHA2(CONCAT('<pepper>:', '<raw>'), 256));
What's next
- Phase 2D: camp allocation algorithm + round driver + judge invocation. Wired to Fabric announce channel (via system-api-key) + the Dialectic.OpenclawPlugin's tool for agent argument submission.
- Phase 2E: nginx config + CF Origin Cert + deploy to server.t3.
- Phase 3: Dialectic.OpenclawPlugin — agent-facing tools.
- Phase 4: frontend rewrite (STYLE.md + real Keycloak OIDC + visibility toggle UI).
- Phase 5: end-to-end integration with
analyze-intelworkflow.