praxis/.ciagent/ARCHITECTURE.md

Praxis — Architecture (Research-Refined)

Status: Research-refined (Phase 0 RESEARCH stage). Informed by .ciagent/RESEARCH.md — web-verified vendor catalogs, GitHub metadata, official docs.

High-Level Topology

Three-tier architecture per PRD §7:

┌──────────────────────────────────────────────────────────┐
│  Client (Android, iOS, Web, WhatsApp, USSD)              │
│  - Voice I/O, cached scenarios, offline scenarios        │
└────────────────┬─────────────────────────────────────────┘
                 │
┌────────────────▼─────────────────────────────────────────┐
│  Edge / Region (per market)                              │
│  - ASR + TTS (low-latency, local accent models)          │
│  - Scenario runtime + role orchestration                 │
│  - Caching layer                                         │
└────────────────┬─────────────────────────────────────────┘
                 │
┌────────────────▼─────────────────────────────────────────┐
│  Core Platform                                           │
│  - LLM tutor (long-context, persona-aware, safety-tuned) │
│  - Scenario Authoring & Tagging                          │
│  - Mastery Rubric Engine                                 │
│  - User state, progress, credentialing                  │
│  - Analytics                                             │
└──────────────────────────────────────────────────────────┘

LLM Foundation (D-003, D-020 — research-verified)

Open-weights models hosted via Ollama Cloud direct API (https://ollama.com/api/chat + OLLAMA_API_KEY) — no local daemon required for v0.1.

Model	Verified status	Role	Context	Mode
gemma4:cloud	✅ Real, current (256K ctx, Text+Image, "Low Usage" tier)	Role-play fast path / persona turns	256K	standard
deepseek-v4-flash:cloud	✅ Real, current (1M ctx, 284B MoE / 13B active, "Medium Usage" tier)	Coaching debrief + scenario-branch decisions	1M	no-think (latency); think/max-think reserved for offline analysis

Post-pilot cost-reduction path: self-host gemma4:e4b (edge, native audio modality, 9.6GB) on partner hardware for the ≤$3/learner/month target. Architecture must keep the model-call layer swappable (D-020).

Notable future option: gemma4:e2b/e4b support Text+Image+Audio input — potential future Ollama-hosted ASR for cost reduction (not v0.1; dedicated Deepgram is lower-latency + more accent-robust).

v0.1 Component Map (research-refined minimal viable voice loop)

Client: React + WebRTC (Pipecat client SDK)
   │  audio in/out (WebRTC, UDP, sub-50ms)
   ▼
Pipecat server (Python)
   ├─ VAD: Silero
   ├─ STT: Deepgram Nova-3 (cloud, streaming, WebSocket)
   ├─ LLM: Ollama Cloud direct API (https://ollama.com/api/chat)
   │     ├─ gemma4:cloud         (role-play fast path)
   │     └─ deepseek-v4-flash:cloud (debrief, no-think mode)
   ├─ TTS: Cartesia Sonic (cloud, ~120ms)  ← behind interface
   │     └─ fallback: Piper (self-hosted, ~80ms)  ← R4 mitigation
   ├─ Scenario runtime: Pipecat Flows + YAML→Pydantic scenarios
   ├─ Guardrail layer: pluggable interface (v0.1: Customer Service ruleset)
   └─ Learner state: SQLite (praxis.db, single-learner, no auth)

v0.1 deliberately excludes: edge-region split, multi-market deployment, caching layer, scenario authoring tools, mastery engine, credentialing, analytics, WhatsApp/USSD surfaces.

Latency Budget (< 600ms end-to-end — research-revised)

Segment	Budget	Source / note
Client capture + WebRTC uplink	~50ms	WebRTC UDP, Canada region
ASR (Deepgram Nova-3 first partial)	~250ms	Vendor claim; R1: measure in Phase 1
LLM first token (gemma4:cloud direct API)	~200ms	R3: measure in Phase 1
TTS first audio (Cartesia Sonic)	~120ms	Vendor/leaderboard; R2: measure in Phase 1
WebRTC downlink + playback	~50ms
Total (all-cloud target)	~670ms	⚠️ Marginally over 600ms
Total (Piper TTS mitigation)	~550ms	R4: pre-stage Piper self-hosted on pilot server

R4 — single biggest v0.1 technical risk: the all-cloud three-hop path likely lands ~670ms. The TTS service MUST sit behind an interface (D-014) and Piper-on-pilot-server MUST be pre-staged as the likely production v0.1 TTS. This is the first Phase 1 spike.

Critical Risks to Engineer Around

1. Accent robustness — even a great LLM fails if ASR mishears the learner. Canadian English/French accents, code-switching.
2. Hallucinated advice in safety-sensitive domains — health, electrical. Domain-specific guardrails, escalation, disclaimers. (v0.1 uses Customer Service path, lower risk, but architecture must support the guardrail layer.)
3. Cost per learner per month must stay ≤ $3 in target markets. v0.1 Canada pilot relaxes this, but architecture must not bake in assumptions that violate it.
4. Ollama model availability / cost — :cloud variants imply hosted inference; verify pricing and rate limits at research phase.

Deployment (v0.1)

• Single-region pilot (Canada)
• LLM via Ollama Cloud direct API (no local daemon)
• ASR via Deepgram cloud (North American endpoint)
• TTS: Cartesia cloud (quality benchmark) + Piper self-hosted on pilot server (R4 latency mitigation, likely production v0.1)
• Pipecat server on single pilot host (Python)
• Client: React web app (Pipecat client SDK, WebRTC transport)
• SQLite local file (praxis.db) on pilot host

Open Architecture Questions (resolved by research)

Question (from initial ARCHITECTURE.md)	Resolution
Client framework	React + WebRTC via Pipecat client SDK (D-015)
Streaming transport	WebRTC (Pipecat); WebSocket dev fallback (D-016)
ASR/TTS provider	Deepgram Nova-3 (ASR, D-013); Cartesia Sonic + Piper fallback (TTS, D-014)
Learner state store	SQLite confirmed (D-007 → 0.90)
Ollama deployment	Ollama Cloud direct API (D-020)
Scenario definition format	YAML DSL → Pydantic → Pipecat Flows (D-018)

Open Architecture Questions (remaining for PLAN stage)

• R1-R4 latency spikes (see Risks below) — first Phase 1 tasks
• Pipecat Flows schema mapping for the one branch point (escalate vs accept) in the refund scenario
• Guardrail ruleset concrete implementation (D-019) — system-prompt template + output filter
• SQLite schema for session log + progress + scenario state
• OLLAMA_API_KEY + DEEPGRAM_API_KEY + CARTESIA_API_KEY secret management (extend config.secrets.scopes)

---

v0.2 Deployment Architecture (Proxmox LXC + Docker-in-LXC)

Status: Research-refined (v0.2 RESEARCH stage). Informed by .ciagent/RESEARCH.md — Proxmox VE wiki, coreci script analysis, Docker/systemd ecosystem. Decisions: D-021 (LXC deploy), D-022 (Docker in LXC, nesting=1), D-023 (FastAPI StaticFiles), D-024 (infra-only keys), D-025/D-029 (build inside CT), D-026 (coreci secrets), D-027 (auto VMID), D-028 (Docker via apt), D-030 (vmbr0 DHCP).

Docker-in-LXC Topology

                    ┌─────────────────────────────────────────────────────────┐
                    │  Proxmox VE Host (PROXMOX_NODE)                          │
                    │  (D-026: secrets sourced from ~/coreci/.ciagent/         │
                    │   .env.secrets + praxis .ciagent/.env.secrets)           │
                    │                                                          │
                    │  Deploy operator runs:                                   │
                    │    scripts/proxmox/lxc-deploy.sh                         │
                    │     ├─ stage-snippet.sh  (upload hookscript to snippets) │
                    │     ├─ lxc-clone.sh      (POST /nodes/{node}/lxc)        │
                    │     ├─ lxc-config.sh     (PUT /config + SSH lxc.env)     │
                    │     ├─ lxc-start.sh      (POST /status/start)            │
                    │     └─ health-check.sh   (poll /health:8789)             │
                    │                                                          │
                    │  ┌────────────────────────────────────────────────────┐  │
                    │  │  LXC Container (VMID: auto via pve_nextid, D-027)  │  │
                    │  │  hostname: praxis                                   │  │
                    │  │  memory: 4096MB   rootfs: 16GB   (bumped from 2/8) │  │
                    │  │  features: nesting=1                                │  │
                    │  │  net0: bridge=vmbr0, ip=dhcp  (D-030)              │  │
                    │  │  hookscript: local:snippets/praxis-firstboot.sh     │  │
                    │  │  lxc.environment: GITEA_TOKEN, DEEPGRAM_API_KEY,   │  │
                    │  │    PRAXIS_PORT=8789, PRAXIS_HOST=0.0.0.0, ...       │  │
                    │  │                                                    │  │
                    │  │  post-start hook (runs on PVE host, pct exec → CT): │  │
                    │  │   1. apt install docker.io docker-compose-v2 git    │  │
                    │  │   2. git clone praxis repo → /opt/praxis            │  │
                    │  │   3. install-service.sh (user + env + systemd unit) │  │
                    │  │   4. systemctl start praxis                         │  │
                    │  │      → ExecStartPre: docker compose build           │  │
                    │  │      → ExecStart: docker compose up (foreground)    │  │
                    │  │                                                    │  │
                    │  │  ┌──────────────────────────────────────────────┐  │  │
                    │  │  │  Docker daemon                                │  │  │
                    │  │  │  ┌────────────────────────────────────────┐  │  │  │
                    │  │  │  │  praxis container                       │  │  │  │
                    │  │  │  │  image: python:3.12-slim + deps + dist │  │  │  │
                    │  │  │  │  ports: 8789:8789                      │  │  │  │
                    │  │  │  │  env_file: /etc/praxis/server.env      │  │  │  │
                    │  │  │  │  volume: praxis-db → /app/data         │  │  │  │
                    │  │  │  │  restart: unless-stopped               │  │  │  │
                    │  │  │  │                                         │  │  │  │
                    │  │  │  │  uvicorn 0.0.0.0:8789                  │  │  │  │
                    │  │  │  │  ├─ GET  /health       (FastAPI)       │  │  │  │
                    │  │  │  │  ├─ POST /pipecat/webrtc (FastAPI)     │  │  │  │
                    │  │  │  │  └─ GET  / ... (StaticFiles client/dist)│  │  │  │
                    │  │  │  └────────────────────────────────────────┘  │  │  │
                    │  │  └──────────────────────────────────────────────┘  │  │
                    │  └────────────────────────────────────────────────────┘  │
                    │           │                                              │
                    │       vmbr0 (bridge) ──── DHCP ──── CT eth0              │
                    └───────────┬──────────────────────────────────────────────┘
                                │  <ct-bridge-ip>:8789
                    ┌───────────▼───────────────────────┐
                    │  Operator / Learner (browser)     │
                    │  http://<ct-ip>:8789               │
                    │  (direct access, no proxy/TLS)    │
                    └───────────────────────────────────┘

Image Build Pipeline (Multi-stage Dockerfile)

Two-stage build, Debian-slim bases, python -m server entrypoint:

Stage 1: client-builder (node:22-slim)
  COPY client/package.json client/package-lock.json
  RUN npm ci                          ← cached unless deps change
  COPY client/
  RUN npm run build                   ← tsc -b && vite build → client/dist/

Stage 2: server (python:3.12-slim)
  RUN apt-get install gcc g++ libasound2-dev   ← only if source compilation
  COPY pyproject.toml
  RUN pip install --no-cache-dir .   ← pipecat-ai[deepgram,cartesia,piper,webrtc] + deps
  COPY server/ scenarios/ db/
  COPY --from=client-builder /app/client/dist ./client/dist
  EXPOSE 8789
  CMD ["python", "-m", "server"]      ← calls uvicorn.run(app, host=HOST, port=PORT)

Why Debian-slim (not Alpine): numpy + pipecat-ai native extensions compile against glibc; musl wheels are less universally available. The ~50MB size saving of Alpine isn't worth the compatibility risk.

Why python -m server (not uvicorn server.__main__:app): Matches the existing entrypoint (server/__main__.py:main()) which reads PRAXIS_HOST/PRAXIS_PORT from env and calls uvicorn.run(...). Single uvicorn process is correct for WebRTC/WebSocket (long-lived connections, not request-per-response).

Secret Injection Chain

~/coreci/.ciagent/.env.secrets          praxis/.ciagent/.env.secrets
  PROXMOX_API_URL                         GITEA_TOKEN
  PROXMOX_API_TOKEN                       DEEPGRAM_API_KEY
  PROXMOX_NODE                            CARTESIA_API_KEY (empty, D-024)
  PROXMOX_STORAGE                         OLLAMA_API_KEY (empty, D-024)
  PROXMOX_TEMPLATE_VOLID
  PROXMOX_TLS_SKIP_VERIFY
           │                    │
           └────────┬───────────┘
                    ▼
          lxc-deploy.sh sources both
                    │
                    ▼
          lxc-config.sh (SSH to PVE host)
          writes /etc/pve/lxc/<vmid>.conf:
            lxc.environment: GITEA_TOKEN=<token>
            lxc.environment: DEEPGRAM_API_KEY=<key>
            lxc.environment: PRAXIS_PORT=8789
            lxc.environment: PRAXIS_HOST=0.0.0.0
            lxc.environment: OLLAMA_BASE_URL=https://ollama.com/v1
            ...
                    │
                    ▼  (CT boots; systemd PID 1 has these env vars)
          firstboot-hook.sh → pct exec install-service.sh
                    │
                    ▼
          /etc/praxis/server.env  (root:praxis, chmod 0640)
            GITEA_TOKEN=<token>
            DEEPGRAM_API_KEY=<key>
            PRAXIS_PORT=8789
            ...
                    │
                    ▼
          praxis.service (EnvironmentFile=/etc/praxis/server.env)
          → ExecStart: docker compose up
                    │
                    ▼
          docker-compose.yml (env_file: /etc/praxis/server.env)
                    │
                    ▼
          Docker container (os.environ)
          → server/__main__.py reads PRAXIS_HOST, PRAXIS_PORT, DEEPGRAM_API_KEY, ...

.gitignore coverage: .env, .env.secrets, .env.* are all gitignored in praxis (verified). No secrets are committed.

CT Resource Sizing

Resource	Coreci default	Praxis v0.2	Rationale
Memory	2048 MB	4096 MB	Docker daemon (~200MB) + build peak (~1.2GB pip) + runtime (~500MB) + headroom
Rootfs	8 GB	16 GB	Docker engine (~400MB) + build layers (~1.6GB) + final image (~1GB) + repo + apt + headroom
CPU cores	(default)	2	Sufficient for build + single-learner runtime
Swap	(default)	0	LXC swap is host swap; not needed for pilot

Configured via lxc-clone.sh (memory=${PROXMOX_MEMORY_MB:-4096}, rootfs=${storage}:16) or env vars in the deploy script.

Health-Check Path

lxc-deploy.sh
  └─ health-check.sh <vmid>
       │
       ├─ PRAXIS_HEALTH_URL set? → use directly
       │
       └─ else: pve_get /nodes/{node}/lxc/{vmid}/interfaces
            │
            ├─ jq: .[] | select(.name != "lo") | (.inet? // .ip? // empty)
            │  (NOT .hwaddr — P18 bug fix from coreci)
            │
            └─ health_url = http://<bridge-ip>:8789/health
                 │
                 └─ poll curl -fsS --connect-timeout 2 $health_url
                    for PRAXIS_HEALTH_TIMEOUT seconds (default 300s)

Timing: CT start → DHCP lease (~5s) → firstboot hook: apt install Docker (~90s) + git clone (~10s) + install-service + systemctl start (~120s: docker compose build + up) → uvicorn binds :8789 → health passes. Total: ~3-5 min. PRAXIS_HEALTH_TIMEOUT=300 (5 min) covers this with margin.

Firstboot Hook Sequence

Proxmox invokes hookscript at post-start phase (runs on PVE HOST):
  $1 = VMID, $2 = phase

  Phase: post-start
    │
    ├─ 1. pct exec <vmid> -- apt-get install docker.io docker-compose-v2 git curl
    │     (D-028: Docker via apt inside CT)
    │
    ├─ 2. pct exec <vmid> -- git clone https://<GITEA_TOKEN>@git.cloudinit.dev/coreci/praxis.git /opt/praxis
    │     (D-029: clone inside CT, self-contained)
    │
    ├─ 3. pct exec <vmid> -- sh /opt/praxis/scripts/install-service.sh
    │     │
    │     ├─ create praxis user (useradd --system, add to docker group)
    │     ├─ mkdir /var/lib/praxis/data /var/log/praxis /etc/praxis
    │     ├─ write /etc/praxis/server.env from lxc.environment vars
    │     ├─ install praxis.service systemd unit
    │     └─ systemctl daemon-reload && enable praxis && restart praxis
    │           │
    │           ├─ ExecStartPre: docker compose build  (TimeoutStartSec=300)
    │           └─ ExecStart: docker compose up  (foreground, Type=simple)
    │
    └─ 4. (hook exits 0; external health-check.sh polls /health:8789)

Idempotency: The hook checks if praxis is already installed + active before re-running (mirrors coreci's pattern at firstboot-hook.sh:82). Re-running lxc-deploy.sh against a healthy CT skips the hook entirely (P16 idempotency via ct_exists + ct_running + health-check).

What's Reused Verbatim from CoreCI vs Adapted

Component	Verdict	Notes
api.sh	Verbatim	REQ-DEPLOY-03. PVE REST helpers are project-agnostic.
lxc-start.sh	Verbatim	POST /status/start is identical.
proxy/ct-exists.sh	Verbatim	Used by lxc-deploy.sh idempotency; no proxy dependency in the helper.
lxc-clone.sh	Adapted	hostname=praxis, memory=4096, rootfs=16, features=nesting=1 (kept).
lxc-config.sh	Adapted	hookscript=praxis-firstboot.sh, lxc.environment vars for praxis.
health-check.sh	Adapted	/health (not /healthz), port 8789, PRAXIS_* env names, timeout 300s.
rollback.sh	Adapted	Remove proxy backend-remove (no proxy in v0.2).
stage-snippet.sh	Adapted	SNIPPET_NAME=praxis-firstboot.sh, praxis repo raw URL.
timing.sh	Adapted	Metric prefix: praxis_deploy_timing_.
lxc-deploy.sh	Adapted	Remove PROXY_VMID/BACKEND_DOMAIN steps; VMID=auto (D-027).
firstboot-hook.sh	Heavy adaptation	Docker install + git clone + compose build/up (not host-fetch binary).
install-service.sh	Heavy adaptation	praxis user (docker group), /etc/praxis/server.env, praxis.service (docker compose up).

v0.2 Deployment Risks (from RESEARCH.md)

ID	Risk	Mitigation
R-DEPLOY-01	Pipecat wheel missing → source compilation OOM	Pre-test docker build locally; bump memory if needed
R-DEPLOY-02	systemd TimeoutStartSec insufficient for build+up	Set 300-600s or split build into separate oneshot service
R-DEPLOY-03	CT can't reach Gitea/apt mirrors	Validate internet access; fallback to host-clone+pct-push (D-025 hybrid)
R-DEPLOY-04	Docker-in-LXC on ZFS rootfs	Check storage type; use local (directory) if ZFS
R-DEPLOY-05	journald log flooding from compose up	Log rotation or StandardOutput=null for pilot
R-DEPLOY-06	First-boot build > 5 min (NFR breach)	Pre-build on host + docker load fallback

---

v0.3 Architecture (Mastery Scoring + Competency Rubrics + VC + Cohort Dashboard)

Status: Research-refined (v0.3 RESEARCH stage). Informed by .ciagent/RESEARCH.md v0.3 section. Decisions: D-031 (operator tier, overrides D-007 for operator surface), D-032 (mastery gate), D-033 (W3C VC 2.0), D-034 (k-anonymity), D-035 (IRT 1PL), D-036 (scenario library), D-037 (path structure), D-038..D-049 (clarify).

Hybrid Storage Topology (D-031)

Learner-local state stays in SQLite (D-007 preserved); operator-tier state goes to a new Postgres service. The two stores never share a session and never join via cross-DB FKs (learner_ref is an opaque string in Postgres).

LXC Container (from v0.2, memory bumped 4GB → 6GB)
  Docker daemon
  ├── praxis container (existing v0.2 + v0.3 additions)
  │     ├─ uvicorn 0.0.0.0:8789
  │     ├─ GET  /health                 (v0.2)
  │     ├─ POST /pipecat/webrtc          (v0.2)
  │     ├─ GET  / ... StaticFiles        (v0.2)
  │     ├─ /api/operator/*  NEW          (v0.3 — operator auth gate)
  │     ├─ /vc/verify/<id>  NEW          (v0.3 — public, unauthenticated)
  │     ├─ SQLite /app/data/praxis.db    (v0.2 + NEW v0.3 tables: learner_ability, mastery_progress)
  │     └─ Postgres pool (asyncpg)       (v0.3 — operator tier)
  │
  └── postgres container NEW (v0.3)
        ├─ postgres:16-slim
        ├─ pgdata named volume
        ├─ internal Docker network only (no published port)
        ├─ pg_isready healthcheck
        └─ Tables: operators, issued_credentials, mastery_gate_events, cohort_aggregates, issuer_keys

v0.3 Component Map (additions to v0.2)

Pipecat server (Python)
   ├─ ... (v0.2 voice loop unchanged) ...
   ├─ Rubric engine NEW (server/mastery/)
   │     ├─ rubric_loader.py    (rubrics/<skill>.yaml → Pydantic)
   │     ├─ rubric_scorer.py    (rule-based: signals → 1-5, deterministic — REQ-NFR-MAST-01)
   │     ├─ evidence_extractor.py (LLM extracts quotes+signals, temp=0, JSON-schema)
   │     └─ mastery_score.py    (weighted mean + conjunctive floor + path gate)
   ├─ IRT engine NEW (server/mastery/irt.py)
   │     ├─ 1PL/Rasch: P(success) = logistic(θ − b)
   │     ├─ Bayesian θ update per session (<100ms — REQ-NFR-IRT-01)
   │     └─ θ persisted to SQLite learner_ability (D-046)
   ├─ Scenario library NEW (server/scenarios/library.py)
   │     ├─ scenarios/<path>/<id>.yaml + scenarios/index.yaml (semver, rubric_criteria mapping)
   │     └─ AI variation review pipeline (_pending/ → expert review → library)
   ├─ Path engine NEW (server/paths/)
   │     ├─ paths/<slug>.yaml (6-week structure, mastery gates — D-037)
   │     └─ progression: current_week advances on gate-open (D-048)
   ├─ VC issuer NEW (server/vc/)
   │     ├─ issuer.py (Ed25519, pynacl + canonicaljson + base58, eddsa-jcs-2022)
   │     ├─ status_list.py (Bitstring Status List v1.0)
   │     ├─ verification.py (public GET /vc/verify/<id> — D-043)
   │     └─ issuer key in Postgres issuer_keys (encrypted at rest)
   ├─ Operator auth NEW (server/auth/)
   │     ├─ SessionMiddleware (Starlette, itsdangerous-signed cookie — D-041)
   │     ├─ argon2id passwords (argon2-cffi)
   │     ├─ current_operator Depends
   │     └─ slowapi 5/min login rate-limit
   ├─ Cohort aggregation NEW (server/cohort/)
   │     ├─ on-session-end hook → k-anonymized aggregate upsert to Postgres (D-045)
   │     └─ nightly reconciliation job (cron in praxis service)
   └─ Operator API NEW (server/operator/)
         ├─ /api/operator/login, /api/operator/logout
         ├─ /api/operator/cohort (k-anonymized, ≥10 learners/cell — D-034)
         └─ /api/operator/credentials (issued VCs, revocation)

Client (React)
   ├─ ... (v0.2 voice UI unchanged) ...
   └─ /operator/* NEW (v0.3 — cohort dashboard UI, auth-gated — D-044)

Mastery Scoring Flow (off the voice path)

Session end (server/session_recorder.py)
  │
  ├─ 1. Evidence extraction (LLM, async, off-voice-path)
  │     deepseek-v4-flash:cloud, temp=0
  │     Input: session turns + scenario.rubric_criteria
  │     Output (JSON-schema-validated): [{criterion_id, quote, signals: [...]}]
  │     Guard: fuzzy-match quote vs transcript → reject+re-extract on mismatch (R-MAST-02)
  │
  ├─ 2. Rule-based scoring (deterministic, no LLM — REQ-NFR-MAST-01)
  │     rubric_scorer.py: signals → 1-5 level per criterion
  │
  ├─ 3. Mastery Score (deterministic)
  │     scenario_score = weighted_mean(levels, weights)
  │     scenario_pass = scenario_score ≥ 3.0 AND every criterion ≥ 2 (conjunctive floor)
  │     path MasteryScore = mean(scenario_scores for passing scenarios only)
  │     path gate open = ≥3 distinct scenarios passed AND MasteryScore ≥ 3.5 (D-032)
  │
  ├─ 4. IRT θ update (deterministic, <100ms — REQ-NFR-IRT-01)
  │     θ ← θ + (outcome − P) × σ²/(σ² + 1); persist to SQLite learner_ability (D-046)
  │
  ├─ 5. Progression (deterministic)
  │     gate open → advance current_week (D-048)
  │     week-final gate open → issue VC (REQ-MAST-03)
  │     record mastery_gate_event in Postgres (REQ-NFR-MAST-02)
  │
  └─ 6. Cohort aggregation (async, k-anonymized)
        on-session-end hook → upsert k-anonymized aggregate to Postgres (D-045)
        nightly reconciliation reconciles 7-day windows

VC Issuance + Verification Flow

Mastery gate opens (week-final)
  ├─ issuer.py: build payload {scenariosPassed, rubricScore, completedWeeks:6, evidence, validUntil:+3y}
  │             canonicalize (JCS) → sign Ed25519 → store in Postgres issued_credentials
  └─ Verification (third party): GET /vc/verify/<id> → fetch pubkey from verificationMethod URL
        → validate Ed25519 sig → check Status List → return {valid, status, issuer, mastery, verifiedAt}

Postgres Schema (operator tier — D-040)

Tables: operators (id, username, password_hash argon2id), issued_credentials (id, learner_ref opaque-string, vc_payload_json, signature_b64, status, issued_at), mastery_gate_events (id, learner_ref, path, week, scenarios_passed_json, rubric_scores_json, gate_opened_at — REQ-NFR-MAST-02 audit), cohort_aggregates (path, week, window_start/end, metric, value, cell_suppressed — k-anon via write-time suppression, weekly partitions), issuer_keys (id, public_key Multikey, private_key_enc, status active|superseded). gen_random_uuid() in PG16 (no extension). No cross-DB FKs.

CT Resource Sizing (v0.3 bump)

Resource	v0.2	v0.3	Rationale
Memory	4096 MB	6144 MB	Postgres ~1GB + praxis ~2GB + build headroom (R-MT-01)
Rootfs	16 GB	16 GB	Postgres data on named volume, not rootfs
CPU	2	2-4	Postgres + praxis concurrent; 2 floor, 4 preferred

v0.3 Risks (from RESEARCH.md)

Top risks for PLAN: R-MAST-01 (N=3 thin for credential → label formative), R-AUTH-01 (Secure cookie + no-TLS pilot), R-MT-01 (Postgres resource contention), R-VC-01 (custom VC code ~200 LOC), R-MAST-02 (LLM hallucinated quotes → fuzzy-match guard), R-IRT-01 (cold-start θ → fall back to scenario.difficulty until ≥5 sessions). Full table in RESEARCH.md.