hzhang
57a1fa1b33
State machine driver + camp allocator + judge-submitted verdicts +
broadcast hook to Fabric announce channel.
internal/orchestrator/
- allocator.go: pure function implementing the 3-camp rule from the
2026-05-23 design session — for each camp (pro/con/judge), random
pick from volunteers; backfill unfilled camps from remaining
unallocated signups if pool is large enough; <3 final → cancel
with diagnostic reason. rng injected for test determinism.
- allocator_test.go: 7 tests covering empty/insufficient/single-volunteer
/multi-volunteer-no-dup/backfill/insufficient-backfill/large-pool
distinctness invariants. All pass.
- ticker.go: scans every 15s (configurable via ORCHESTRATOR_TICK_INTERVAL),
drives 3 state transitions atomically:
created → signup_open (post fabric announcement async)
signup_open → signup_closed | cancelled (run allocator, write camps)
signup_closed → debating (open round 0)
debating → completed is driven by the verdict POST handler (the
implicit "judging" sub-state is captured by the gate
status==debating AND now>=debate_end_at). Per-topic transitions
use SELECT FOR UPDATE so concurrent ticker instances are safe.
internal/fabric/announce.go: HTTP client posting to a Guild announce
channel using x-fabric-system-key header (the Phase 1 gate). Wraps
the formatted topic announcement (title/summary/timing/schema). All
4 config fields required to enable; any missing → no-op with log
(orchestrator runs fine without Fabric coupling for dev).
internal/store/{round,camp,argument,verdict}_store.go: CRUD layer
for the remaining v2 entities. CampStore.WriteAllocation accepts a
tx so the orchestrator can wrap allocator+camps+status into one
atomic transition.
internal/httpapi/handlers/arguments.go:
- POST /api/topics/{id}/arguments — agent posts during debate. Gates:
agent must be in a camp on this topic; status==debating; content
nonempty and <=32KB; attached to latest open round.
- GET /api/topics/{id}/arguments — full transcript, visibility-gated.
internal/httpapi/handlers/verdict.go:
- POST /api/topics/{id}/verdict — judge submits. Gates: caller==judge
camp; status==debating AND now>=debate_end_at; verdict valid JSON;
rationale required. On success: writes verdicts row (unique on
topic_id → 409 on dup) and flips topic.status to completed.
- GET /api/topics/{id}/verdict — visibility-gated.
config: 5 new env vars — FABRIC_GUILD_BASE_URL,
FABRIC_ANNOUNCE_CHANNEL_ID, FABRIC_SYSTEM_API_KEY,
FABRIC_BOT_BEARER_TOKEN, ORCHESTRATOR_TICK_INTERVAL.
routes.go: wired new handlers — POST signups/arguments/verdict gated
on agent bearer; GET arguments/verdict on optional-auth chain
(public topics readable anonymously).
main.go: instantiates announcer + ticker; ticker.Run in a goroutine
sharing the lifetime ctx.
go vet + gofmt clean; 7/7 allocator tests pass; 12M static binary.
Next: Phase 2E (deploy to t3 with nginx + CF origin cert) or
Phase 2D.5 (SSE stream for live transcript subscribers).
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.