Socratic Trident

Ask before answering. Surface dissent by default. Commit to a transparency log.
A transparency-first system for verifiable, source-backed reasoning: structured debate outputs you can audit, hash, and verify independently.

---

Documentation

Start here	docs/RUNBOOK.md — setup, services, testing, exports, troubleshooting
Full index	docs/README.md — every guide, spec link, and workflow
Terms	docs/GLOSSARY.md
Postgres	docs/DATABASE_SETUP.md — port matrix (read before copying DATABASE_URL)
Contribute	CONTRIBUTING.md · CODE_OF_CONDUCT.md
Vulnerabilities	SECURITY.md — private reporting (not public issues)
Hardening	docs/SECURITY.md — CSP, tokens, deployment

Deploy & operate: docs/DEPLOY_PILOT.md (Docker Compose evaluation stack) · docs/DEPLOY_UI.md (includes Vercel) · docs/STAGE_SMOKE.md · docs/TESTING.md · docs/LOCAL_DEVELOPMENT.md

---

What this is

Socratic Trident is a full-stack application that makes epistemic discipline part of the product, not a footnote.

Mechanism	What you get
Ask-before-answer	Clarifying questions before conclusions
Adversarial debate	Multiple opposed positions by default (not a single monolithic answer)
Transparency log (v0)	Answers are hashed, signed, and committed before the UI treats them as final

A mirrored public ledger with wide checkpoint distribution is a future direction. Today’s stack is a verifiable append-only transparency log with independent receipt checking.

Principles: default dissent (≥2 opposed positions) · steelmanning · evidence discipline (cite or mark uncertainty) · structured, auditable outputs.

---

Architecture

flowchart LR
  subgraph userFacing [Browser]
    UI[apps/ui]
  end
  subgraph backend [Backend]
    API[apps/api]
    Ledger[apps/ledger]
    DB[(PostgreSQL)]
  end
  UI --> API
  API --> Ledger
  API --> DB
  Ledger --> Log[Append-only log]

Loading

Monorepo layout

apps/
  api/       Fastify orchestrator (sessions, inquiry, debate, bundle, ledger submit)
  ledger/    Transparency log service (STH, proofs)
  ui/        Vite + React — canonical product UI
  web/       Legacy Next.js shell — deprecated, excluded from workspace (see apps/web/README.md)
packages/
  canonical/, common/     Crypto & shared primitives (JCS, Merkle, Ed25519)
  db/                     Prisma + PostgreSQL
  debate-engine/          Pipeline, synthesis styles, evidence discipline
  evidence-pack/          Packs + retrieval (e.g. Tavily)
  model-providers/        OpenAI, Anthropic, Stub, optional Prime Intellect
  prompts/                Plain-text templates
  schemas/, spec/         JSON Schema, OpenAPI, invariants, contract tests
  verifier/               Library + st-verify CLI
  judge/                  Scoring & diagnostics
  eval/tse/               Truth-Seeking Evaluation harness (Python)

Independent verification: packages/verifier implements receipt, selective disclosure, and revision-chain checks; CLI: pnpm --filter @trident/verifier st-verify ….

---

Quick start

Complete procedures (Windows paths, real E2E, smoke tests) live in docs/RUNBOOK.md. Minimal path:

git clone https://github.com/fraware/Socratic-Trident.git
cd Socratic-Trident
pnpm install

# Build (Windows: bash scripts/build-windows.sh if you hit NODIST_PREFIX issues)
pnpm build

docker-compose up postgres -d
bash scripts/wait-for-db.sh
bash scripts/migrate-docker.sh   # or: set DATABASE_URL and pnpm db:migrate — see docs/DATABASE_SETUP.md

pnpm --filter @trident/ledger dev    # http://localhost:4001
export DATABASE_URL="postgresql://trident:trident_dev@127.0.0.1:5433/trident"
pnpm --filter @trident/api dev       # http://localhost:4000
pnpm --filter @trident/ui dev        # http://localhost:8080 — MSW if :4000 is free, else proxies to API
# Force mock API: pnpm dev:ui-mock   # Always MSW
# Force live proxy only: pnpm --filter @trident/ui dev:live

Always build before running services; packages such as @trident/prompts ship compiled dist/ consumed at runtime.

API sketch (session → debate → verify)

curl -s -X POST http://localhost:4000/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"query":"Should government fund X as a public good?"}' | jq .

# Then: inquiry/questions, inquiry/answers, debate/run — see RUNBOOK for full payloads.

jq '.bundle' response.json > bundle.json
jq '.receipt' response.json > receipt.json
pnpm --filter @trident/verifier st-verify receipt --bundle bundle.json --receipt receipt.json

---

Testing

Command	Use
pnpm test	Unit / package tests (includes conformance)
pnpm test:e2e:mock	Playwright, mock backend (CI-style)
pnpm e2e:real	Full integration stack
pnpm smoke-e2e	End-to-end system smoke
pnpm stage:smoke	Against a deployed URL (STAGE_SMOKE_BASE_URL, …)

Kinds of tests: conformance (cryptographic invariants, merge gates) · contract / schema golden tests · integration · UI E2E · optional stage contract tests when env vars are set · failure and resilience drills (docs/TESTING.md).

---

Security & verification

• Development: auto-generated ledger/publisher keys for tests only; not for production.
• Production: set LEDGER_PUBKEY_ED25519 / LEDGER_SECRETKEY_ED25519; use AUTH_ENABLED=true, AUTH_TOKENS, and ALLOWED_ORIGINS for internet-facing APIs. Exempt: /health, /metrics.
• Receipts: bundle hash, signed commitment, inclusion proof, STH — recomputed and checked by st-verify without trusting the server’s narrative alone.

Bearer header shape: Authorization: Bearer <token>. Details: apps/api/README.md, docs/SECURITY.md, docs/KEY_MANAGEMENT.md.

---

Development standards

Cryptography and bundles are deterministic: RFC8785-style JCS rules, fixed committed leaf order (COMMITTED_LEAF_PATHS_ORDERED in packages/spec/invariants.ts — must match conformance vectors), no silent semantic edits (revision chains use explicit patches). Conformance vectors under packages/verifier/test/vectors/ are immutable. TypeScript strict; runtime schema validation at boundaries.

---

Status & roadmap

Done (high level): Session → inquiry → debate → bundle + receipt; ledger v0; UI workflow + MSW + Playwright + a11y; OpenAPI + contract tests; PostgreSQL sessions; optional Bearer auth, rate limits, structured logs, /metrics; Dockerfiles and reference Compose stack (docs/DEPLOY_PILOT.md); Truth-Seeking Evaluation harness (packages/eval/tse); evidence discipline modes; Tavily retrieval when configured.

In progress / partial: argument graph depth; tournament UX polish; multi-round defaults vs. fast paths; more search providers; EUC validation depth in TSE.

Not in repo: first-party Kubernetes charts; bundled Prometheus/Grafana (metrics endpoint exists).

Fresh-clone sanity: pnpm install → pnpm build → Postgres + pnpm db:migrate → ledger + api + ui dev → conformance tests green and st-verify receipt succeeds on a produced bundle — see docs/RUNBOOK.md.

More detail: docs/RUNBOOK.md (smoke tests, failure drills, troubleshooting) · apps/api/README.md (HTTP API and auth).

---

Deployment notes

• Compose evaluation stack: docs/DEPLOY_PILOT.md — copy infra/compose/.env.pilot.example → infra/compose/.env, configure URLs and keys.
• UI (Vite, including Vercel): docs/DEPLOY_UI.md — API, ledger, and DB still run on suitable hosts.
• Single-origin routing behind one HTTPS host simplifies CORS: set ALLOWED_ORIGINS to that origin exactly (no * in production).

Default local ports

Service	Port
API	4000
Ledger	4001
UI (pnpm dev)	8080
UI (Playwright default)	5179

Feature flags (summary)

• USE_DEBATE_ENGINE: fixture vs. full pipeline (see RUNBOOK).
• USE_REAL_MODELS: real LLM keys vs. stub (USE_REAL_MODELS=false for cheap CI / local).

---

Contributing & license

Contributing, PR expectations, and releases: CONTRIBUTING.md.

License: this project is released under the MIT License (Copyright Socratic Trident contributors).

Security: report vulnerabilities via SECURITY.md only.