groove-dev 0.27.112 → 0.27.115

package/CENTRAL_COMMAND_REBUILD.md

@@ -0,0 +1,689 @@
+# Central Command — Complete Rebuild Specification
+
+This document contains everything needed to rebuild the Central Command ingestion server from scratch. Central Command is a Node.js Express server that receives training trajectory envelopes from Groove clients, verifies HMAC attestation, stores data as JSONL, stitches multi-chunk sessions, scores trajectories, tracks contributor credits, and serves a 384-dim embedding endpoint.
+
+## Architecture Overview
+
+```
+Groove Client                          Central Command (AWS)
+─────────────                          ────────────────────
+SessionAttestation                     SessionRegistry (SQLite)
+  → POST /v1/sessions/open    ──────►   ECDH key exchange
+  ← server_public_key                   shared_secret derived
+                                        sequence counter = 0
+TrajectoryCapture
+  → signs envelope with HMAC
+  → POST /v1/training/ingest  ──────►  EnvelopeVerifier
+                                         HMAC verification
+                                         Sequence check
+                                         Schema validation
+                                       EnvelopeStorage (JSONL)
+                                       TrajectoryStitcher
+                                       TrajectoryScorer
+                                       ContributorLedger (SQLite)
+
+DomainTagger
+  → POST /v1/embed            ──────►  EmbeddingService (ONNX)
+  ← 384-dim vector                     all-MiniLM-L6-v2
+```
+
+## Server Entry Point
+
+**Port:** 8443 (env: `GROOVE_CENTRAL_PORT`)
+
+**Dependencies:**
+```json
+{
+  "dependencies": {
+    "express": "^4.18.0",
+    "better-sqlite3": "^12.9.0",
+    "uuid": "^9.0.0",
+    "@xenova/transformers": "^2.x"
+  }
+}
+```
+
+**`server/index.js`** — Express app with:
+- CORS: `Access-Control-Allow-Origin: *`, methods GET/POST/OPTIONS
+- Body parser: `express.json({ limit: '5mb' })`
+- Per-IP rate limiting: 100/minute, 1000/hour (in-memory Map, cleaned every 5 min)
+- Request logging: `[ISO timestamp] METHOD /path STATUS DURATIONms`
+- Health endpoint: `GET /health` → `{ status: 'ok', uptime: process.uptime() }`
+- Graceful shutdown on SIGTERM/SIGINT (5s timeout)
+
+**Component initialization order:**
+```javascript
+const sessionRegistry = new SessionRegistry();          // ./data/sessions.db
+const storage = new EnvelopeStorage();                  // ./data/envelopes/
+const ledger = new ContributorLedger();                 // ./data/ledger.db
+const verifier = new EnvelopeVerifier(sessionRegistry);
+const stitcher = new TrajectoryStitcher(storage);
+const scorer = new TrajectoryScorer({ MODEL_TIERS, QUALITY_MULTIPLIERS });
+const enrichment = new EnrichmentPipeline();
+const centralStats = new CentralStats(storage, ledger, sessionRegistry);
+```
+
+**Route mounting:**
+```javascript
+app.use(createSessionRoutes(sessionRegistry));
+app.use(createIngestRoutes(verifier, storage, stitcher, scorer, enrichment, ledger, sessionRegistry));
+app.use(createStatsRoutes(centralStats));
+app.use(createEmbedRoutes());  // NEW: embedding service
+initEmbedding();               // NEW: load ONNX model in background
+```
+
+---
+
+## Endpoint Reference
+
+### 1. `POST /v1/sessions/open` — ECDH Key Exchange
+
+**Purpose:** Client opens a session, server generates ECDH keypair, derives shared secret for HMAC signing.
+
+**Request:**
+```json
+{
+  "session_id": "sess_<uuid>",
+  "public_key": "<base64 ECDH public key>",
+  "provider": "claude-code|codex|gemini",
+  "model": "claude-opus-4-6",
+  "machine_fingerprint": "<sha256 hex>",
+  "app_version_hash": "<sha256 hex>",
+  "groove_version": "0.27.113"
+}
+```
+All fields required. Returns 400 if any missing.
+
+**Response (200):**
+```json
+{ "server_public_key": "<base64 ECDH public key>" }
+```
+
+**Response (429):** Rate limited — max 20 sessions per machine fingerprint per hour.
+
+**Crypto details:**
+- Curve: `prime256v1` (P-256)
+- `generateECDHKeypair()` → creates ECDH, returns `{ publicKey, privateKey }` as base64
+- `deriveSharedSecret(serverPrivateKey, clientPublicKey)` → `ecdh.computeSecret()` as base64
+- Shared secret stored in SQLite alongside session metadata
+- Sequence counter starts at 0
+
+### 2. `POST /v1/sessions/close` — Session Close (HTTP)
+
+**Request:**
+```json
+{ "session_id": "sess_<uuid>" }
+```
+
+**Response:** `{ closed: true }` or `{ closed: true, already_closed: true }`
+
+### 3. `POST /v1/training/ingest` — Envelope Ingestion
+
+**Purpose:** Receives signed trajectory envelopes. Handles three envelope types: CHUNK, SESSION_CLOSE, USER_FEEDBACK.
+
+**Common validation for all types:**
+- Envelope must have `session_id`
+- Server generates `envelope_id` (not trusted from client): `env_<uuid>`
+- Dedup check via `processed_envelopes` table
+
+#### 3a. Regular CHUNK Envelopes
+
+**Request shape:**
+```json
+{
+  "session_id": "sess_<uuid>",
+  "chunk_sequence": 0,
+  "contributor_id": "<32-char hex>",
+  "attestation": {
+    "session_hmac": "<64-char hex>",
+    "sequence": 0,
+    "app_version_hash": "<64-char hex>"
+  },
+  "metadata": {
+    "provider": "codex",
+    "model_engine": "gpt-5.5",
+    "agent_role": "frontend",
+    "agent_id": "frontend-3",
+    "team_size": 3,
+    "task_complexity": "medium",
+    "groove_version": "0.27.113",
+    "domain_tags": null,
+    "session_embedding": null,
+    "routing": null,
+    "leaf_context": null,
+    "session_quality": 50
+  },
+  "trajectory_log": [
+    {
+      "step": 1,
+      "type": "thought",
+      "timestamp": 1745794234.567,
+      "content": "I'll scaffold the project...",
+      "token_count": 45
+    },
+    {
+      "step": 2,
+      "type": "action",
+      "timestamp": 1745794235.123,
+      "tool": "command_execution",
+      "arguments": { "command": "mkdir -p src" },
+      "content": "Executing: mkdir -p src",
+      "token_count": 12
+    }
+  ]
+}
+```
+
+**Verification flow:**
+1. Session must exist and be `active`
+2. Attestation must have non-empty HMAC string
+3. HMAC verification: strip `attestation` from envelope, JSON.stringify the rest, verify against stored shared_secret with sequence number
+4. Atomic sequence check + increment (prevents replay)
+5. Schema validation (see Schema section below)
+6. Per-session envelope limit: max 200
+
+**HMAC computation:**
+```javascript
+// payload = uint32BE(sequence) + Buffer(JSON.stringify(envelopeWithoutAttestation))
+const key = Buffer.from(sharedSecretB64, 'base64');
+const seqBuf = Buffer.alloc(4);
+seqBuf.writeUInt32BE(sequenceNumber);
+const payload = Buffer.concat([seqBuf, Buffer.from(envelopeBytes)]);
+const hmac = createHmac('sha256', key).update(payload).digest('hex');
+```
+
+**Constant-time comparison** for HMAC verification (XOR each char, bitwise OR accumulator).
+
+#### 3b. SESSION_CLOSE Envelopes
+
+**Request shape:**
+```json
+{
+  "session_id": "sess_<uuid>",
+  "type": "SESSION_CLOSE",
+  "attestation": { "session_hmac": "...", "sequence": 5, "app_version_hash": "..." },
+  "metadata": {
+    "provider": "codex",
+    "model_engine": "gpt-5.5",
+    "agent_role": "frontend",
+    "agent_id": "frontend-3",
+    "domain_tags": {
+      "primary": { "domain": "react_frontend", "confidence": 0.4932 },
+      "secondary": { "domain": "vue_frontend", "confidence": 0.4729 },
+      "tertiary": { "domain": "typescript_node", "confidence": 0.4001 }
+    },
+    "session_embedding": {
+      "model": "sentence-transformers/all-MiniLM-L6-v2",
+      "vector": [0.0123, -0.0456, "...384 floats"],
+      "source_text": "frontend\nI'll scaffold the Vite game project..."
+    },
+    "session_quality": 80
+  },
+  "outcome": {
+    "status": "SUCCESS",
+    "session_quality": 80,
+    "quality_tier": "TIER_A",
+    "quality_tier_reason": "high_quality_no_errors",
+    "user_interventions": 0,
+    "total_steps": 45,
+    "total_chunks": 2,
+    "total_tokens": 32606,
+    "duration_seconds": 337,
+    "files_modified": 12,
+    "errors_encountered": 1,
+    "errors_recovered": 1,
+    "coordination_events": 0,
+    "training_eligible": true,
+    "training_exclusion_reason": null
+  }
+}
+```
+
+**After verification + storage:**
+1. Marks session as `closed` in registry
+2. Stitches all chunks for the session into a single trajectory
+3. Scores the stitched trajectory
+4. Credits the contributor in the ledger
+
+#### 3c. USER_FEEDBACK Envelopes
+
+**Request shape:**
+```json
+{
+  "session_id": "sess_<uuid>",
+  "type": "USER_FEEDBACK",
+  "attestation": { "session_hmac": "...", "sequence": 6, "app_version_hash": "..." },
+  "feedback": {
+    "signal": "accepted|modified|rejected|iterated",
+    "timestamp": 1745794500.0,
+    "context": "session completed successfully with no user interventions",
+    "target_step": 45,
+    "revision_rounds": 0,
+    "delta_summary": null
+  }
+}
+```
+
+**Verification:** Same HMAC check but session can be active OR closed (feedback may arrive after close). No sequence increment for feedback.
+
+### 4. `POST /v1/embed` — Embedding Service
+
+**Purpose:** Returns 384-dim sentence embedding for domain tagging and session fingerprinting.
+
+**Request:**
+```json
+{
+  "input": "React TypeScript frontend development",
+  "model": "sentence-transformers/all-MiniLM-L6-v2"
+}
+```
+- `input` — string, required, server truncates to 512 chars
+- `model` — string, optional (only one model, ignore or validate)
+
+**Response (200):**
+```json
+{
+  "data": [
+    {
+      "embedding": [0.0123, -0.0456, "...384 floats"],
+      "index": 0
+    }
+  ],
+  "model": "sentence-transformers/all-MiniLM-L6-v2"
+}
+```
+
+**Client reads:** `data?.data?.[0]?.embedding` — must be `Array<number>`, length 384.
+
+**Error responses:**
+- `400` — missing `input`
+- `503` — model not loaded yet (server startup)
+
+**Health probe:** Client sends `{ "input": "health check" }` on init with 5s timeout. If 200, switches to embedding mode. If fails, falls back to keyword matching silently.
+
+**Implementation:**
+```javascript
+import { pipeline } from '@xenova/transformers';
+
+let embedder = null;
+let loading = false;
+
+export async function initEmbedding() {
+  if (embedder || loading) return;
+  loading = true;
+  try {
+    embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+    console.log('[embedding] model loaded');
+  } catch (err) {
+    console.error('[embedding] failed to load model:', err.message);
+  }
+  loading = false;
+}
+
+export async function embed(text) {
+  if (!embedder) throw new Error('Model not loaded');
+  const result = await embedder(text, { pooling: 'mean', normalize: true });
+  return Array.from(result.data);
+}
+
+export function isReady() {
+  return embedder !== null;
+}
+```
+
+- Model loads once at startup (~2-5s), ~200MB memory
+- Inference: ~5-15ms per call on CPU
+- `initEmbedding()` called at server start, non-blocking (don't await)
+
+### 5. Stats Endpoints
+
+| Endpoint | Method | Returns |
+|----------|--------|---------|
+| `/v1/stats/summary` | GET | `{ totalEnvelopes, totalSteps, totalSessions, activeSessions, uniqueContributors, storageSizeMb, totalPointsAwarded }` |
+| `/v1/stats/daily?days=7` | GET | Array of `{ date, envelopes, steps, sessions, points }` |
+| `/v1/stats/models` | GET | Object keyed by model name: `{ sessions, steps, points, percentage }` |
+| `/v1/stats/providers` | GET | Object keyed by provider: `{ sessions, steps, points }` |
+| `/v1/stats/leaderboard?limit=10` | GET | Array of `{ contributor_id (truncated), total_points, total_sessions }` |
+
+---
+
+## Data Storage
+
+### SQLite: `./data/sessions.db` (SessionRegistry)
+
+**Table: `sessions`**
+```sql
+CREATE TABLE sessions (
+  session_id TEXT PRIMARY KEY,
+  server_private_key TEXT NOT NULL,
+  server_public_key TEXT NOT NULL,
+  shared_secret TEXT NOT NULL,
+  client_public_key TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  model TEXT NOT NULL,
+  machine_fingerprint TEXT NOT NULL,
+  app_version_hash TEXT NOT NULL,
+  groove_version TEXT NOT NULL,
+  expected_sequence INTEGER DEFAULT 0,
+  envelope_count INTEGER DEFAULT 0,
+  status TEXT DEFAULT 'active',
+  created_at TEXT NOT NULL,
+  closed_at TEXT
+);
+```
+
+**Table: `processed_envelopes`**
+```sql
+CREATE TABLE processed_envelopes (
+  envelope_id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  processed_at TEXT NOT NULL
+);
+```
+
+- WAL mode, foreign keys ON
+- `checkAndIncrementSequence()` runs in an IMMEDIATE transaction (atomic)
+- Rate limit: max 20 sessions per `machine_fingerprint` per hour
+- Data dir created with mode `0o700`
+
+### SQLite: `./data/ledger.db` (ContributorLedger)
+
+**Table: `credits`**
+```sql
+CREATE TABLE credits (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  contributor_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  points REAL NOT NULL,
+  base_points INTEGER NOT NULL,
+  multiplier_breakdown TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+```
+
+**Table: `balances`**
+```sql
+CREATE TABLE balances (
+  contributor_id TEXT PRIMARY KEY,
+  total_points REAL NOT NULL DEFAULT 0,
+  total_sessions INTEGER NOT NULL DEFAULT 0,
+  last_credit_at TEXT,
+  trust_score REAL NOT NULL DEFAULT 1.0
+);
+```
+
+- Credits run in a transaction (insert credit + upsert balance)
+- Trust score clamped 0-10
+
+### JSONL: `./data/envelopes/YYYY-MM-DD.jsonl` (EnvelopeStorage)
+
+- One JSON object per line, one file per day
+- Files created with mode `0o600`
+- 50GB quota, warns at 40GB
+- Reads parse all lines, filter by session_id for stitching
+
+---
+
+## Shared Modules (used by both client and server)
+
+### `shared/crypto.js` — ECDH + HMAC
+
+```javascript
+import { createECDH, createHmac, createHash, randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+// Curve: prime256v1 (P-256)
+generateECDHKeypair()        → { publicKey: base64, privateKey: base64 }
+deriveSharedSecret(priv, pub) → base64 shared secret
+signEnvelope(secret, bytes, seq) → hex HMAC
+verifyEnvelope(secret, bytes, seq, hmac) → boolean (constant-time)
+computeAppHash(filePath)     → sha256 hex of file contents
+```
+
+**HMAC payload:** `uint32BE(sequence) || envelopeBytes` where `envelopeBytes` is `JSON.stringify(envelope)` with `attestation` field removed.
+
+### `shared/constants.js`
+
+```javascript
+export const CURRENT_CONSENT_VERSION = '1.0';
+export const CHUNK_SIZE = 200;
+export const CHUNK_TIMEOUT_MS = 300_000;         // 5 min
+export const MAX_QUEUE_SIZE = 10_000;
+export const OBSERVATION_TRUNCATE_HEAD = 50;
+export const OBSERVATION_TRUNCATE_TAIL = 20;
+export const SUPPORTED_PROVIDERS = ['claude-code', 'codex', 'gemini'];
+
+export const MODEL_TIERS = {
+  'claude-opus-4-6': 5,
+  'claude-opus-4-7': 5,
+  'claude-sonnet-4-6': 3,
+  'gpt-4.5': 5,
+  'gpt-5.5': 5,
+  'o3': 5,
+  'o4-mini': 2,
+  'gemini-2.5-pro': 3,
+  'gemini-2.5-flash': 1.5,
+};
+
+export const QUALITY_MULTIPLIERS = {
+  correction: 10,
+  coordination: 5,
+  errorRecovery: 3,
+  heavyTask: 2,
+  highQuality: 1.5,
+};
+
+export const OBSERVATION_TOKEN_LIMIT = 4096;
+export const TIER_A_MIN_QUALITY = 70;
+export const TIER_B_MIN_QUALITY = 50;
+export const TRAINING_MIN_STEPS = 5;
+export const TRAINING_MIN_TOKENS = 500;
+export const TRAINING_MIN_DURATION = 10;
+export const TRAINING_EXCLUSION_REASONS = ['too_few_steps', 'no_actions', 'no_observations', 'insufficient_tokens', 'too_short'];
+
+export const USER_MESSAGE_MAX_CHARS = 2000;
+
+export const CENTRAL_COMMAND_URL = process.env.GROOVE_CENTRAL_URL || 'https://api.groovedev.ai';
+export const EMBEDDING_SERVICE_URL = process.env.EMBEDDING_SERVICE_URL || `${CENTRAL_COMMAND_URL}/v1/embed`;
+```
+
+### `shared/envelope-schema.js` — Validation
+
+**Valid step types:** `thought`, `action`, `observation`, `correction`, `resolution`, `error`, `coordination`, `edit`, `instruction`, `clarification`, `approval`
+
+**Valid quality tiers:** `TIER_A`, `TIER_B`, `TIER_C`
+
+**Valid feedback signals:** `accepted`, `modified`, `rejected`, `iterated`
+
+**Valid outcome statuses:** `SUCCESS`, `CRASH`, `KILLED`
+
+**Valid complexities:** `light`, `medium`, `heavy`
+
+**Limits:**
+- Max 500 steps per envelope
+- Max 10,000 chars per step content
+- Max 100,000 token_count per step
+- Max 50,000 step number
+- Timestamps: within last 7 days, max 1 hour in future
+- Sequence: 0 to 1,000,000
+- contributor_id: 32-char hex
+- session_hmac: 64-char hex
+- app_version_hash: 64-char hex
+- agent_role: max 50 chars
+- agent_id: max 100 chars
+- team_size: 1-50
+- groove_version: max 20 chars
+
+**Metadata fields validated:**
+- `domain_tags` — object or null, with primary/secondary/tertiary each having domain (string) and confidence (0-1)
+- `session_embedding` — object or null, with model (string), vector (non-empty array of finite numbers), source_text (string)
+- `routing` — object or null, with leaf_id (string), routing_confidence (0-1), fallback_used (boolean), optional leaf_lifecycle_stage (string), optional parent_leaf_id (string or null)
+- `leaf_context` — object or null, with leaf_id, leaf_version, confidence_at_route (0-1), chassis_model
+
+---
+
+## Server Components (detailed)
+
+### TrajectoryStitcher
+
+Stitches multi-chunk sessions into a single trajectory on SESSION_CLOSE.
+
+```javascript
+stitch(sessionId):
+  1. Get all envelopes for session from storage
+  2. Separate chunks (non-SESSION_CLOSE) from close envelope
+  3. Sort chunks by chunk_sequence
+  4. Concatenate all trajectory_log steps, sort by step number
+  5. Compute: unique tools used, step type distribution, total tokens
+  6. Return {
+       session_id, contributor_id, metadata (from first chunk),
+       trajectory_log, outcome (from close envelope),
+       total_steps, total_tokens, unique_tools_used,
+       step_type_distribution, total_chunks
+     }
+```
+
+Also has `linkCoordination(trajectory)` — annotates coordination steps with partner info.
+
+### TrajectoryScorer
+
+Scores stitched trajectories for contributor credits. All scoring derived from actual steps, never trusts client-reported values.
+
+```javascript
+score(stitchedTrajectory):
+  - basePoints = min(steps.length, 5000)
+  - modelMultiplier = MODEL_TIERS[model_engine] || 1
+  - correctionBonus = min(correctionSteps, 30% of trajectory) * 10
+  - coordinationBonus = min(coordSteps, 20% of trajectory) * 5
+  - errorRecoveryBonus = min(errorsRecovered, errorSteps) * 3
+  - complexityBonus = (heavy task) ? basePoints * 1 : 0
+  - subtotal = (basePoints * modelMultiplier) + all bonuses
+  - qualityBonus = (hasResolution && 5-5000 steps) ? floor(subtotal * 0.1) : 0
+  - totalPoints = subtotal + qualityBonus
+```
+
+### EnrichmentPipeline
+
+Currently a stub — returns trajectory with `enrichment: { cognitive_target: 'pending', model_verified: 'pending', quality_assessment: 'pending' }`. Placeholder for future LLM-as-a-Judge enrichment.
+
+### CentralStats
+
+Aggregation layer over storage + ledger + registry.
+
+- `summary()` — total envelopes, steps, sessions, active sessions, unique contributors, storage size, total points
+- `dailyGrowth(days)` — per-day envelope/step/session/point counts
+- `modelBreakdown()` — per-model session/step counts with percentage
+- `providerBreakdown()` — per-provider session/step counts
+- `topContributors(limit)` — leaderboard (contributor_id truncated to 8 chars)
+- File size safety: skips files > 100MB, caps at 100K lines per file
+
+---
+
+## Rate Limiting
+
+### Per-IP (middleware)
+- 100 requests per minute per IP
+- 1000 requests per hour per IP
+- IP from `X-Forwarded-For` header (first entry) or `req.ip`
+- Returns 429 with `retryAfter` seconds
+- Stale entries cleaned every 5 minutes (>120s since minute window AND >7200s since hour window)
+
+### Per-Machine (session open)
+- Max 20 sessions per `machine_fingerprint` per hour
+- Returns 429 on session open attempt
+
+### Per-Session (envelope ingest)
+- Max 200 envelopes per session
+- Returns 429 on exceeding
+
+---
+
+## Verification Flow (exact implementation)
+
+Both `verify()` and `verifyClose()` follow the same pattern:
+
+```
+1. Check session_id exists
+2. Check session status is 'active'
+3. Check attestation block exists
+4. Check session_hmac is non-empty string
+5. Reconstruct HMAC:
+   a. Copy envelope, delete attestation key
+   b. JSON.stringify the copy
+   c. verifyEnvelope(shared_secret, jsonBytes, sequence, hmac)
+6. Atomic sequence check + increment
+7. Schema validation via validateEnvelope()
+```
+
+`verifyFeedback()` is the same except:
+- Session can be active OR closed (no status check)
+- No sequence check/increment
+
+`verifyClose()` additionally calls `sessionRegistry.closeSession(sessionId)` after validation.
+
+---
+
+## Deployment Notes
+
+### Install
+```bash
+npm install express better-sqlite3 uuid @xenova/transformers
+```
+
+### Environment Variables
+```bash
+GROOVE_CENTRAL_PORT=8443     # server port (default 8443)
+```
+
+### Data Directories (auto-created)
+```
+./data/sessions.db           # session registry
+./data/ledger.db             # contributor ledger
+./data/envelopes/            # JSONL storage (YYYY-MM-DD.jsonl)
+```
+
+All created with restrictive permissions (0o700 dirs, 0o600 files).
+
+### First Run
+The ONNX model (`Xenova/all-MiniLM-L6-v2`) downloads from Hugging Face on first startup. ~80MB download, cached locally after first run. Server starts accepting requests immediately — embedding endpoint returns 503 until model loads (~2-5s).
+
+### Verification Test
+```bash
+# Health check
+curl https://api.groovedev.ai/health
+# Expected: {"status":"ok","uptime":...}
+
+# Embedding test
+curl -s -X POST https://api.groovedev.ai/v1/embed \
+  -H "Content-Type: application/json" \
+  -d '{"input": "React TypeScript frontend development"}' \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Vector length: {len(d[\"data\"][0][\"embedding\"])}')"
+# Expected: Vector length: 384
+
+# Stats
+curl https://api.groovedev.ai/v1/stats/summary
+```
+
+---
+
+## Critical Contract: What the Client Sends
+
+The Groove client (`moe-training/client/`) sends to these exact URLs:
+
+| Client Component | Endpoint | When |
+|-----------------|----------|------|
+| `SessionAttestation.openSession()` | `POST /v1/sessions/open` | Agent spawn |
+| `TransmissionQueue._drain()` | `POST /v1/training/ingest` | Every chunk + session close + feedback |
+| `SessionAttestation.closeSession()` | `POST /v1/sessions/close` | Agent complete/crash |
+| `DomainTagger.init()` | `POST /v1/embed` | DomainTagger init (health probe) |
+| `DomainTagger._embed()` | `POST /v1/embed` | Domain tagging + session embedding |
+| `TrajectoryCapture._retryOfflineQueue()` | `GET /health` | Every 60s when offline queue has items |
+
+Base URL: `https://api.groovedev.ai` (from `CENTRAL_COMMAND_URL` constant).
+Embedding URL: `https://api.groovedev.ai/v1/embed` (from `EMBEDDING_SERVICE_URL` constant, defaults to `CENTRAL_COMMAND_URL + /v1/embed`).
+
+All requests use `AbortSignal.timeout()`:
+- Session open/close: 10s
+- Ingest: 30s (with 5 retries, exponential backoff up to 60s)
+- Embed: 10s (regular calls), 5s (init health probe)
+- Health check: 5s