Skip to content
Vox: The AI-Native Programming Language

research-index

Vox Architecture & Research Index (2026)

Section titled “Vox Architecture & Research Index (2026)”

This file tracks the single source of truth for Vox architecture, research findings, and strategic explainers.

Documentation coverage ledger

Section titled “Documentation coverage ledger”

Purpose: Make discoverability explicit — what is indexed here vs generated elsewhere vs intentionally niche.

BucketIndexed hereNotes
Architecture *ssot*.mdYes (thematic sections)Examples: mesh SSOT, wire format, terminal exec, cryptography — see Core SSoT and audits.
Language platform (compiler / LSP / diagnostics)YesLanguage platform (compiler, LSP, diagnostics) section below (2026-05-11 closure pass).
architecture-index.mdRetiredRemoved from git (Starlight sidebar replaces it). Offline navigation: this file + where-things-live.md.
Detector-rule draftsPartial2026-05-09-detector-rule-ssot-plan.md, 2026-05-09-detector-rule-ssot-design.md — linked here for searchability; owners should fold outcomes into enforcement phases.
docs/src/archive/NoTombstoned per root AGENTS.md; do not ingest for new planning.

Strategic & Value Proposition

Section titled “Strategic & Value Proposition”

AI-First Language Fixtures

Section titled “AI-First Language Fixtures”
  • AI-First Fixtures — Research (2026) — Evidence-grounded design for author-time AI fixtures across lexer/parser/HIR/codegen, vox-actor-runtime LLM substrate, orchestrator routing, MCP/ACI, and telemetry. Ships a machine-readable candidate catalog (contracts/agentos/ai-first-fixtures.v1.yaml) with JSON Schema, five fixture classes (agent control, model selection, query templates, deferred fill, search substitution), spike backlog S1–S8, and ADR drafts for proposed decorators (@subagent, @prompt, @hole, @search). Implemented and observed (v0.7) — typed TelemetryEvent::AiFixture, Rust codegen wired to memory/search/cascade/subagent dispatch; TS lowering still advisory (vox/codegen/missing-ts-ai-lowering). Follow-on: ai-fixtures-ts-lowering-follow-on-2026.md.
  • Vox shell-tier stdlib SSOT (2026) — std.fs / std.process / structured formats (std.csv, std.toml, std.yaml, std.io): argv-first Rust builtins vs host shells and vox_run_shell.
  • Vox Marquee Explainer 2026 — The 500-word explainer for the Vox foundation and agentic-native philosophy.
  • v1.0 Release Criteria — Benchmark criteria for the stable 1.0 release. §5 LLM-Target Fidelity (CR-L1..CR-L8) added 2026-05-15.
  • Vox Model Selection — 2026-Q2 Refresh (2026-05-15) — Current-month (May 2026) frontier model audit + recommended task-to-model mapping for Vox’s existing 5-tier routing pipeline + rationale for the 2026-05-15 catalog refresh. Documents the rotation of 5 premium aliases in contracts/orchestration/model-routing.v1.yaml (codegen/debugging/security from claude-mythos-preview-20260407 → anthropic/claude-opus-4.7 since Mythos is preview-tier at $125/MTok while Opus 4.7 is GA at $5/$25 with 87.6% SWE-bench Verified; research from gemini-2.5-pro-preview → gemini-3.1-pro; planning to openai/gpt-5.5-pro for BenchLM agentic 90.1). §1 lists the 15 new catalog entries (Opus 4.7, Haiku 4.5, GPT-5.4/5.5-Pro/Mini/Nano, Gemini 3.1 Pro/Flash/Flash-Lite, DeepSeek V4 Pro/Flash, Kimi K2.6 Thinking, GLM 5.1, Qwen 3.6 27B, Qwen3-Coder-Next 32B) with per-model cost_per_1k_input + cost_per_1k_output + tier + strengths + _note rationale + supported_parameters. §2 surveys the May 2026 landscape across frontier coding (six models within 1.3pts on SWE-bench Verified), agentic/tool-call (GPT-5.5 Pro 90.1 BenchLM, Llama 3.1 405B 40.5 BFCL raw), reasoning specialty (4 useful shapes), open-source frontier (DeepSeek V4 Pro MIT 1M ctx, Kimi K2.6 LiveBench Coding leader 78.57, Qwen 3.6 Apache 2.0), small/cheap (Haiku 4.5 $1/$5, Gemini 3.1 Flash-Lite $0.25/$1.50, DeepSeek V4 Flash $0.28 cheapest output), local/Ollama-friendly (Qwen3-Coder-Next 32B <30ms VS Code latency), and free rate-limited (R1, Llama 3.3, Gemma 3 on OpenRouter). §3 maps each of the 13 Vox task categories (CodeGen/Testing/Debugging/TypeChecking/Research/Parsing/Review/General/Ars/Planning/InterAgent/ToolOrchestration/Visus) to primary+pro-fallback+light-floor models. §3.2 zooms in on vox repair: recommends Sonnet 4.6 with prompt caching enabled (80%+ cost cut on the 3-attempt loop since source code resends), with Opus 4.7 escalation for unusually-stuck sessions. §3.3 picks gpt-5.5-pro primary for CR-L0 spec-to-app and Opus 4.7 alternative at $1.20-1.50 typical per-spec cost. §3.4 recommends MENS base-model migration from Llama-4 Scout to Qwen 3.6 27B (+5pts SWE-bench, Apache 2.0 licensing-safe, 128K ctx ample for Vox training corpora). §4 cost analysis includes per-task estimated costs at typical 4K input/500 output, repair-session cost comparison ($0.064 Sonnet w/ caching vs $0.108 Opus w/ caching vs $0.026 DeepSeek V4 Pro), and CR-L1 panel measurement cost (~$92/RC recommended, ~$215/RC max-quality, ~$32/RC cost-floor). §5 sequences the migration: 2026-05-15 ratified (premium aliases + catalog + panel pins + this doc); v0.6 (enable prompt caching in repair.rs, update default openrouter model pref, retire llama3:latest Local default); v0.7+ council-gated (MENS retrain, OpenAiDirect provider, model-spec stability axis). §6 six open questions to council: Mythos retention, MENS retrain timing, OpenAiDirect security review, stability schema field, free-tier exploitation, prompt-caching passthrough verification. §7 appendix lists 12 benchmark sources with citation rationale.
  • Vox v1.0 LLM-Target Implementation Plan (2026-05-15) — Companion execution plan for CR-L0..CR-L8. Builds on the audit-doc self-critique (§9, G1–G18 + C1–C4 + omissions) and pegs every CR-L to phased tasks. §1 Phasing P0 (prep, 2 wks: Marquee manifest, eval dir, LLM panel pin, vox audit contract, council reconciliation review, AGENTS.md drift fix, owner assignment) → P1 (quick wins, 4 wks: CR-L5 ACI default-on, CR-L6 10-detector retirement-guard parity) → P2 (measurement infra, 7 wks: CR-L8 telemetry export, vox audit humaneval / mens-on-distribution / plan-fidelity / repair-corpus harnesses) → P3 (corpus eng, 12 wks: 164 HumanEval-Vox + 30 held-out, 50 repair projects, 50 plans, 3–5 Marquee apps, 10 spec-to-app fixtures) → P4 (hard work, 16 wks: project-scope repair, plan-mode iteration, vox new/deploy/doctor E2E, CR-L0 agent loop driver + measurement) → P5 (hardening, 8 wks: bar-or-demote decisions, release). §2 Dependency DAG showing CR-L0 sits at the bottom — every other CR-L feeds in; CR-L0 results reveal weakest sub-loop. Three parallel tracks (Lang platform / Runtime+Agent infra / DevOps+DX) with a floating Corpus engineer. §3 Fixture-corpus budget: ~340 fixtures across 5 corpora, ~1438 hours / ~48 person-weeks (~12 calendar weeks at 1 corpus eng + 0.25 FTE help). Held-out subset of 30 HumanEval problems marked training_eligible: false as MENS contamination guard. Corpus versioning via corpus_hash: <blake3> in each manifest. §4 CI contract for vox audit <thing>: single surface (--json/--markdown/--html/--baseline/--threshold/--corpus/--llm-panel), exit codes {0=met, 1=missed, 2=infra-error}, canonical JSON report shape, contracts/reports/<thing>/<date>.json atomic write, vox.audit.<thing> telemetry. 9 subcommands enumerated. Single vox-audit crate, Subcommand trait, each CR-L registers an impl. §5 Risk register R1–R13: R1 corpus contamination (held-out subset), R2 LLM rate limits/cost (caching + budget alerts), R3 doc drift recurrence (CR-L6 audit gate + quarterly manual), R4 council rejection (P0.5 review block), R5 Marquee disagreement (P0.1 manifest review), R6 CR-L0 lands at 40–60% (sub-bar at 40% blocks GA; 4 wk buffer), R7 ACI default-on breaks IDE consumers (deprecation warning), R8 audit subcommand sprawl (PR template + schema), R9 repair-corpus rot (quarterly refresh from CR-L8 telemetry), R10 CI compute budget, R11 corpus eng staffing slip (severity high), R12 MENS poor on-distribution capping CR-L0 (demote MENS to candidate tier), R13 council bandwidth (bundle into 2 fixed reviews). §6 Rollback / demotion policy per CR-L: binary v1.0 gates are CR-L5/L6/L8 + CR-L7 sub-bar; CR-L0 sub-bar at < 40% blocks GA; CR-L1/L2/L3/L4 can demote with release-note honesty. Demotion policy itself is half the LLM-target credibility — a council that quietly removes failing criteria destroys the framework. §7 CR-L0 spec (adopted 2026-05-15): ≥ 60% pass + ≤ $5/spec, sub-bar < 40% blocks GA. Rationale: naive product of other CR-L bars ≈ 54%, so 60% is mildly ambitious; $5/spec at 2026-Q4 rates allows ~50K input + 10K output tokens. Why CR-L0 matters: only criterion exercising interaction between Vox primitives and a real agent — every other CR-L can pass while CR-L0 fails (= Vox is locally good but doesn’t compose into agentic workflow). §7.2 Deferred CR-L9–L12 (endpoint auth, LSP parity, emit correctness, latency/cost) tracked under existing follow-on plans; not adopted to avoid bar dilution. §8 Open questions 12 items including reference-LLM panel approval (OQ-7), corpus-eng staffing decision (OQ-8), Marquee composition (OQ-9), $5/spec re-baseline at GA (OQ-10), MENS post-v1.0 re-measurement cadence (OQ-11), demotion-as-release-note vs full-post-mortem (OQ-12).
  • Vox as an LLM-Target Language — Audit & v1.0 Plan (2026-05-15) — Codebase-grounded audit of Vox’s readiness as a primary destination target for AI agents. §1 restates the vision in testable terms (V1–V5: writeability, repairability, retirement-guard parity, end-to-end CLI orchestration, corpus feedback loop). §2 inventories what already ships with file:line evidence — effect rows enforced at effect_check.rs, 47-rule LLM-aware lint suite at detectors/, vox repair MVP at repair.rs, JSON diagnostics with correction_hints/suggested_fixes/missing_cases at diagnostics.rs:96, MCP server with 50+ tool modules, doctest pipeline strict, test-first lefthook with MENS-reward rationale, layered agent discovery surface. §3 audits gaps with severity tiers — 🔴 no benchmark/measurement for self-repair (CR-D2 number unverifiable), 🔴 no corpus-feedback closed loop (reward_hook stubs unwired), 🔴 plan-mode fidelity unmeasured (CR-D1 number unverifiable), 🟠 deploy/health CLI gap (vox new/vox deploy/vox doctor absent from generated CLI surface), 🟠 retirement guards incomplete with stale AGENTS.md §Grammar Unification claim contradicting pipeline.rs:21 ADR-028 enforcement, 🟠 MENS on-distribution rate unmeasured, 🟠 ACI envelope opt-in by default, 🟡 codegen IR unification claimed but not landed, 🟡 inference hosting absent (deferred to mesh Phase 5–6), 🟡 mesh chaos/partition testing absent. §4 attainability verdict separates realistic v1.0 (achievable end-2026 with focus — measurement and integration work) from aspirational v1.0 (humans-never-write-code: not achievable without scope cuts elsewhere; pushes to 2027+); names CR-L8 as the single highest-leverage gap to close because it compounds. §5 proposes CR-L1 (HumanEval-Vox ≥ 80%), CR-L2 (MENS on-distribution ≥ 95%), CR-L3 (project-scope repair ≥ 70%), CR-L4 (plan-mode fidelity ≥ 85% measured), CR-L5 (ACI envelope default-on), CR-L6 (retirement-guard parity with AGENTS.md), CR-L7 (vox new/vox deploy/vox doctor end-to-end), CR-L8 (diagnostic→repair→corpus feedback loop). §6 sequences each CR-L onto an existing phase plan — CR-L5/L6 are 1- and 3-week wins from vox-language-rules-phase2-lint-extension-2026.md; CR-L8 pegs to Phase 4 Task 7 (telemetry export); CR-L1/L2 reuse @example decorator; CR-L3/L4/L7 are the substantive new work. Aggregate ~30 weeks serialized, ~14 weeks two-track. §7 surfaces six open council questions (bar height, append-vs-replace CR-D, mesh-in-v1.0 contradiction, immediate AGENTS.md corrective edit, “humans-as-orchestrators” as v1.0-marketing vs v1.x-stretch, eval corpus location). §8 maps verification entry points (compiler stages, diagnostic shape, ADR-028 enforcement, 47 detectors, repair MVP, MCP tools, telemetry, sibling docs).
  • Web App Archetype Coverage Map (2026-05-02) — Coverage map of 21 web-app archetypes against the current Vox substrate. Itemizes ~38 archetype-anchored blockers and a 24-item cross-cutting infrastructure spine (CC-00…CC-23) plus 17 MENS / orchestrator journey blockers (M1…M17). Pareto-ordered into 9 sequencing blocks targeting maximum archetype-coverage gain per unit-of-design-surface, mapped onto the existing Phase 1–5 interop plan. Backlog spine for prioritizing the next slate of language, runtime, codegen, and DevEx work.

Audits & Assessments

Section titled “Audits & Assessments”
  • WebIR / HIR split-brain inventory (2026) — Dual codegen paths, WebIR bridge, mobile/Tauri seams, and parity tests (baseline for IR work).
  • ADR 036 — WebIR vs HIR unification (compare-both) — Scored decision: HIR semantic core + WebIR projection; platform capability projection wiring.
  • Tauri audit (2026-05-11) — Codebase-wide reality check of Tauri usage vs SSOT claims: current desktop/mobile compile paths, capability projection wiring, build/CI cost implications, and a strategy-independent retire list for dead/misleading seams.
  • Tauri convergence migration plan (2026-Q2) — Executable ADR-037 follow-through plan for moving generated desktop/mobile apps to Tauri 2, porting Sherpa, retiring Capacitor, and enforcing Axum-as-app guardrails.
  • Vox Speech Surface Inventory 2026 — Repository-audited map of speech capture and speech-to-code surfaces: editor mic/file commands, Vox app Web Speech and mobile plugins, dashboard Loquela gap, CLI/MCP/streaming paths, and missing HTTP ingress.
  • Vox Speech Audit Findings 2026 — ASR-primary speech-to-code audit findings, KPI scorecard model, runtime matrix status, and verified gap list.
  • Vox Speech Improvement Backlog 2026 — Prioritized backlog for closing speech accuracy, surface parity, capture-format, mobile parity, and CI coverage gaps.
  • Vox Speech CI Gates Proposal 2026 — Required and advisory CI gate proposal for committed canary KPI, corpus manifest triples, runtime ASR canary, CUDA parity, Sherpa parity, and streaming coverage.
  • Documentation Reality Audit Program — Machine-readable claim inventory + findings backlog, dual-track triage (code vs doc vs historical), priority scoring; vox ci docs-reality-audit + contracts/reports/docs-reality-audit/.
  • Workspace reorg design (2026-05-08) — Original 10-phase plan: build-time floor removal (workspace-hack leaf exclusion), layer model, orchestrator/cli/plugin-host extractions, strict CI guard. Phases 0/1/2/4/5/9 landed; Phases 3/6/7/8 deferred. Companion: outcome doc.
  • Workspace reorg outcome (2026-05-08) — What landed: Phase 0–5+9 outcomes, build-time measurements (orchestrator −36%, CLI −74%), known inversions. Updated 2026-05-15 to record followup work (C1–C4, vox-package inversion removal, plan-doc pointers for Phase 6/7 successors C5/C3).
  • Build-time log (2026-05-08) — Per-phase build-time measurements, deferred-phase rationale, headline outcome table. Updated 2026-05-15: Phase 6 superseded by Tier D plan; Phase 9 inversion list corrected.
  • Crate org followup design (2026-05-08) — Spec for six follow-on PRs: Track A (SSOT drift), Track B (descriptions + naming), C1 (vox-mcp-meta merge), C2 (vox-package split), C3 (vox-cli-ci), C4 (ops_ludus), C5 (orchestrator-core), PR6 (arch-check lints). Status 2026-05-15: All PRs 1–6 landed. C3 and C5 deferred with plan docs.
  • Crate structure audit & consolidation plan (2026-05-15) — Snapshot of post-reorg crate sprawl: 102 crates, 5 hard-drift entries, vox-orchestrator at 65.5K LoC. Tiered consolidation plan (A–D). Tiers A (drift reconciliation + Rule 12 + [planned] table), B (SCIENTIA fold, −8 crates), and C (vox-foundation umbrella, −3 crates) all landed 2026-05-15. Tier D (orchestrator core extraction) deferred — see plan doc.
  • Tier D — Orchestrator core-extraction plan (2026-05-15) — Assessment of extracting vox-orchestrator-core from the orchestrator’s orchestrator/ subdir (12.8K LoC). Debunks the agentos/ vertical-slice path (358 LoC). Maps the Rust coherence blocker (20 sibling crate:: imports require co-moving the Orchestrator struct + ~8 modules). Post-split estimate: vox-orchestrator-core ~35K, vox-orchestrator ~32K. 7-task breakdown (D1 dep audit → D7 cleanup). Start only when Rule 13 fires (>15% LoC growth since last release tag).
  • C3 — vox-cli-ci extraction plan (2026-05-15) — Plan for extracting vox-cli/src/commands/ci/ (22K LoC, 74 files) into a new vox-cli-ci crate. Identifies the three shared-module blockers (artifact_policy, command_contract, command_registry_model — 366 LoC), routes them through vox-cli-core to avoid circular deps, and gives a 6-task breakdown (C3-T1 dep audit → C3-T6 verification). Start when vox-cli exceeds 80% of budget (72K LoC).
  • Workspace dependency audit closure (2026-05) — Workspace pins, schemars08 alias, LSP tower-lsp-server consolidation, deferred Candle/SWC ADRs; pairs with dependency policy.
  • Rust Warning Audit & Remediation Backlog (2026-05-11) — Closeout ledger from the May 2026 rustc / clippy / rustdoc audit. Records the workspace cargo clippy --workspace --all-targets -- -D warnings baseline (clean, exit 0); the two remaining broad allowances (vox-orchestrator blocked on compile errors in dei_shim/research/orchestrator/pipeline.rs; vox-orchestrator-mcp blocked on ~80 latent clippy::collapsible_if instances); the justified per-item suppression inventory (Category A: language mechanics, lock-across-await, RPIT trait shape; Category B: telemetry DTOs awaiting ADR-037 emit-site wiring); and the residual ~41 rustdoc errors all concentrated in vox-codegen (mechanical [Symbol] → `Symbol` rewrites). Defines per-PR / pre-merge / quarterly review cadence.
  • AI-assisted dev loop — compile overhead (2026) — Cache fragmentation (CARGO_TARGET_DIR), vox ci pre-push semantics, dev-loop-audit / --report-json tooling, informal thresholds vs build-timings.
  • CLI vs compilerd params backlog (2026) — SSOT target for merged clap + serde request structs (cli_args.rs / compilerd.rs).
  • Canonical runtime names — daemon, MCP, env (2026) — Frozen identifiers vs compatibility aliases (vox-orchestrator-d, gamify/ludus, DB/Turso); links machine registry env-vars.v1.yaml and prose env-vars.md.
  • Workspace test inventory (2026) — Regenerable vox ci test-inventory artifact: Rust test attrs, ignores (with WebIR caveat), golden Vox @test, app E2E paths, doctest candidates, harness-pattern totals; deterministic JSON + Markdown.
  • Legacy / tombstone remediation ledger (2026-05-11) — Retired MCP names (vox_ludus_* aliases), orchestrator/daemon naming, compiler-monolith path hygiene, contract SSOT decisions, verification commands.
  • Contracts outside index — classification (2026-05-11) — When contracts/index.yaml omits files (reports, derived registries, fixtures) and when to add rows.
  • Vox–React backend interop audit (2026-05-11) — Wire/OpenAPI/path parity, build targets + vox emit client, vox-client.ts §6 error parsing + Library package.json, runtime ops gaps (CORS/auth), prioritized backlog.
  • Repository cleanup ledger — deep reorg (2026-05-11) — Tracked removals (orphan artifacts), runtime DB untracking, clustered frontend/editor surfaces under apps/ + tests/fixtures/, and docs/superpowers/plans/<domain>/ sprawl reduction; includes verification notes.
  • Repository layout sprawl audit (2026-05-11) — Organization-focused audit: sparse directories, overlapping ops roots (infra/ vs docker/ vs repo compose), non-Rust artifact producer/consumer matrix, and tiered consolidation backlog (safe docs vs contract-wide moves).
  • Single-file parent directories — triage list (2026-05-11) — All ~203 tracked paths whose parent holds a single file; workspace for idiomatic vs merge tagging per sprawl audit next steps.
  • Boilerplate Reduction — Design Brief for Vox (2026-05-09) — Externally-authored ranking of 25 categories of repetitive scaffolding (async-state, cross-stack types, forms, auth, effect/IO, request validation, reactive sync, i18n, navigation, observability, durable jobs, file uploads, real-time, push, offline-first, webhooks, pagination, caching, a11y, theming, LLM glue, agentic orchestration, taint/consent, vector search, multiplayer) by frequency × time-burden × language-leverage. Filed verbatim with reviewer caveats (speculative McKinsey-derived percentages, missing reconciliation against existing primitives, P-stack regressions in proposed bare keywords, missing reproducibility/mesh/provenance dimensions). Useful as a vocabulary bridge for outside-in framings; not a roadmap input.
  • Boilerplate Reduction — Gap Analysis Against Vox’s Existing Backlog (2026-05-09) — Code-audited row-by-row reconciliation of the design brief’s 25 categories. Five-tier verdict scheme (✅ Shipped / 📋 Spec’d-Not-Shipped / 🟡 Partially Built / 🔵 No-Spec-Yet / ⚫ Out-of-Scope). Audit-corrected tally: 1 Shipped (#7 reactive state sync), 9 Partially Built (#1, #2, #9, #10, #11, #16, #21, #22), 13 Spec’d-Not-Shipped (#3, #4, #5, #6, #12, #13, #14, #15, #17, #19, #20, #23, #24, #25), 2 Genuine Deltas (#8 i18n catalog, #18 invalidation tags). Each graft (GA-01..GA-25) is filed as a self-contained Sonnet-4.6-followable task block with goal, status preconditions, files-to-read, files-to-modify, acceptance criteria, verification commands, P-stack rubric, and out-of-scope guardrails. §3 records audit findings (12 verdicts corrected from a pre-audit “Already Covered” framing that conflated CC-XX named gaps with shipped features). Anti-recommendations call out the brief’s external pure | retryable | streaming keyword family and agent { } keyword as P-stack regressions duplicating existing surfaces.
  • Mesh & Language-Level Distribution — SSOT & Upgrade Plan (2026-05-09) — The plan-of-record subsuming the research synthesis. Pins the canonical mental model (five spine primitives: DurablePromise[T], effect rows, content-addressed code, signed op-fragments, capability tokens), audits the codebase against the model with verified file:line citations (lock map in-memory; JWE decrypt happens but secrets dropped at remote_worker.rs:124; effect_check.rs is top-down emitting errors not warnings; oplog uses SHA3-256 chain), and sequences seven phases (Phase 0 Foundations: persist locks, lock-leader, authoritative leases, JWE-secret injection, TLS, probe trait, executor-behind-SkillRuntime, traceparent wiring; Phase 1 Language spine: DurablePromise[T] as single awaitable, @remote annotation, auto-derived activity_id, workflow determinism check, bottom-up effect inference, vox workflow preview; Phase 2 Code mobility: workflow content-hash via vox-package CAS, workflow.version(), vox workflow drain, CAS-bundle dispatch seeding, activity result caching ledger, vox dispatch preview, codegen lowering per DurabilityKind; Phase 3 VCS gossip: persist oplog to vox-db, sign capability mints + op-fragments, bounded gossip with Bloom-filter anti-entropy, vector-clock affinity, sealed-trait mint hardening, arch-check rule for raw Command::new("git"), op-log projections architecture; Phase 4 Dashboard control: live mesh routes, “Add a Node” wizard, donations as a donations.vox file, live topology canvas, audit-log scrubber, ⌘K palette, workflow visual debugger; Phase 5 Public-internet safety: Ed25519-signed envelope replaces JWT-HS256, GitHub-attestation gate, per-key quota + reputation EMA, signed deterministic replay attestation that doubles as kudos credit, per-job ephemeral keys, per-pairing X25519, mesh-wide model inventory; Phase 6 Grand network: federation envelope, public attestation registry, T4 micro-VM interface, redundant-execution voting, TEE attestation interface, Scientia discovery loop). Pins three release acceptance contracts (v0.6 single-machine multi-agent no data loss, v0.7 two-daemon LAN mesh durable distributed workflows, v1.0 internet-facing personal mesh) plus v1.x grand-network direction. Includes top-10 risk register with smallest-fix-per-risk mapped to task IDs (P0-T1..P6-T8), §4 distillation of ten huge high-win improvements (DurablePromise collapses 5→1; auto-derived activity_id removes #1 distributed footgun; existing oplog is 90% of distributed VCS; vox-package CAS makes version-skew structurally impossible; lock-leader on vox-db unblocks two daemons in 2 PRs; @remote obsoletes mesh_* naming; vox workflow preview converts runtime questions to compile-time; op-log projections collapse 4 sync protocols to 1; donations as a Vox file; one-envelope-two-birds attestation+kudos), and §9 long-arc direction marker (orchestrator itself written in Vox once Phases 1–2 land). Post-makeover (2026-05-09 indexing pass): the seven phase-implementation plans + one MENS plan have all landed (see §“Mesh Implementation Plans” below); SSOT extended with §3.5 cross-cutting Hopper track (Hp-T1..Hp-T9), §5.5 canonical vox-db migration policy (BASELINE_VERSION bump in manifest.rs only), §5.6 dashboard route convention (/api/v2/<surface>/<resource> REST + single /v1/ws WS multiplex), §5.7 audit-log signing surface (single signed sink for capability mints + destructive actions + hopper overrides); §1.2 effect rows extended with GpuCompute and Mutate to cover MENS Mn-T4/T5; risk register adds rows 11–14 (hopper starvation, hopper SPOF, p=0.05 spot-check correction, migration-scheme inconsistency).
  • Mesh, Dashboard & Distributed Compute — Research (2026-05-09) — Two-horizon synthesis (personal mesh today, grand volunteer compute network tomorrow) that audits the current state of vox-populi / vox-mesh-types / vox-plugin-populi-mesh (top footguns: local-first execution shadows authoritative leases, JWE secrets encrypted but never decrypted on the worker, hardware probes unvalidated, kudos accounting absent, bare HTTP); the vox-dashboard mesh-control surface (Phase-1 stubs only — node list, kill/pause/replay are fixture acks, no add-a-node wizard, FFScript is unrelated); the durable-workflow / language layer (workflow/activity/actor syntax-complete, execution-incomplete; effects parsed not enforced; no @remote annotation; idempotency is opt-in user strings); and multi-agent VCS coordination (single-machine-only; in-memory locks; soft-private capability mints). Surveys prior art across BOINC, Tailscale, Ray, Coolify, Temporal, Restate, Pijul, JJ, GitButler, Akash, libp2p/Iroh. Lays out: a layered identity model (Ed25519 + GitHub-attestation + per-pairing X25519 + per-job ephemeral), four-tier sandbox escalation (in-process → WASM → container → micro-VM), three result-attestation strategies (redundant exec, TEE, signed deterministic replay) mapped per TaskKind, top-18 dashboard killer features, top-7 language features ranked by ROI (workflow determinism check, auto-derived activity_id, @remote annotation, single DurablePromise[T] primitive, content-addressed versioning, par_map/pipeline/event_sourced syntax, vox workflow preview), and the smallest credible MVP for two-daemon multi-agent same-repo. Includes the 8-step critical path from trusted-LAN to safely-internet-facing and five things to explicitly NOT build (custom crypto, blockchain, TEE-first, onion routing, transitive web-of-trust). Feeds the next plan-of-record; not yet itself a plan.
  • Tooling Convergence — Findings & Plan (2026-05-09) — Cross-cutting audit of testing, linting, code-quality, architectural, doc, search, and CI/CD tooling. Inventories the 25+ axes of the project’s quality surface, identifies the three highest drift risks (TOESTUB three-mode fragmentation, missing rustfmt.toml/pre-commit hook, vox-drift-check not in CI), tabulates redundancy across pre-commit / pre-push / GitHub Actions / docs-quality stages, and proposes a three-phase convergence plan that picks one canonical owner per axis and routes every entry point through a new vox audit umbrella driven by a contracts/ci/check-targets.v1.yaml manifest. Includes a five-change first-PR proposal (rustfmt.toml, fmt pre-commit hook, drift-check in CI, drop continue-on-error for generator drift, collapse to single link checker) and explicit non-goals.
  • Research: Compiled Systems Native Code Emission for Vox (2026) — Audit of Vox backend, HIR, WebIR, and parser; brainstorming for native machine-code emission, zero-copy Rust lowering, and native GUI paths for performance-critical systems.
  • Claude Design Dashboard Assets (May 2026) — Raw JSX, JS, and HTML assets generated by Claude Design for the 7-surface dashboard port.
  • Zero-Copy Codegen Research and Implementation Findings (2026) — Findings and implementation details of the zero-copy Rust emission initiative in vox-codegen.
  • Implementation Plan: State Unification & TS Hardening (2026) — Technical roadmap for ensuring Vox’s structural state is emitted safely to React/TypeScript without split-plane issues.
  • Implementation Plan: Zero-Copy Rust Emission & Native Target (2026) — Technical roadmap for enriching HIR with type information and implementing smart ownership tracking in codegen to eliminate unnecessary clones.
  • Comprehensive Audit V2 (2026) — Deep dive into core system integrity.
  • Model Orchestration SSOT — Audit & Convergence Plan (2026-04-20) — Audit of MENS / Populi / OpenRouter routing, telemetry, automatic model discovery, Clavis secret plane, and decentralized key sync across mesh nodes; proposes a single SSOT and ~70 numbered FIX items.
  • Workspace Health & Dependency Governance Research (2026-04-20) — Research on transition from fragile heuristics to policy-driven architectural enforcement; implements automated dependency sprawl and performance regression gates.
  • Telemetry-Driven Cost Accounting Architecture (2026-04-21) — Documentation of the self-correcting pricing loop (v59) that transitions model orchestration from static estimates to verifiable ground-truth spend reporting and VfM optimization.
  • Inference Tuning Resolution Research (2026-04-21) — Research into precedence-based parameter resolution (Override > Registry > Base) for temperature and top_p across the Vox ecosystem.
  • Vox Orchestration Build Stabilization Findings (2026-04-21) — Documentation of schema hardening reconciliation, type mismatch resolution, and feature gate alignment across Populi, Oratio, and Mens.
  • Scientia × Mesh / Model-Routing Integration Research (2026-04-23) — Fundamental limitations of the current Scientia publication pipeline (static novelty blend, thin introspection, no loop back into routing, scoreboard too coarse to encode subjective model strengths), and a concrete proposal to close the loop: new DiscoverySignalFamily (ProviderObservation, ModelCapabilityEvidence), new FindingCandidateClass (ModelCapabilityAtlas, ProviderReliabilityAtlas), a model_profile_learning overlay consumed by ModelRegistry::inject_learned_profiles + new ScoringWeights fields, an active probe-suite harness, and a new quarterly publication output (Vox Provider Atlas) distributed through the existing Scientia adapter stack. Trait sketches, schema stubs, and a 5-phase rollout included.
  • Next-Generation AI Orchestrator: Systemic Flaws, Power User Demands, and Production Design Patterns (2026-04-23) — Comprehensive synthesis of enterprise AI orchestration failure modes (abstraction over-engineering, Python GIL bottlenecks, protocol mistranslation), quantified native-vs-interpreted performance benchmarks, multi-tier FinOps governance requirements, hallucination prevention strategies (HMAC receipt verification, entropy scoring, LLM-as-judge), mesh GPU disaggregated inference semantics, multi-agent coherence protocols (MCP vs. AISP), and a Vox-specific gap analysis identifying 11 implementation priorities.
  • FableForge End-to-End Roadmap Audit (2026-04-23) — Document-level audit of the 280-task / 14-phase FableForge visual-novel platform roadmap. Identifies 6 critical consistency errors (schema version collision, non-existent task references, phase/design conflicts), 5 redundant task pairs, 4 P0 safety tasks buried in Phase 8, 19 tasks pruned from the MVP critical path, 7 under-estimated effort items, 15 claims requiring real-code verification, and produces a re-ranked top-30 execution list compressed to a 14-week MVP path across 6 delivery units.
  • FFScript Panel Schema Spec v0.2.0 (2026-04-23) — Authoritative Zod schema for the Panel type (T-021/T-022/T-031). Resolves the schema version-naming collision from the audit, defines AspectRatio → workflow-dims mapping replacing hardcoded resolutions, specifies Background/Foreground/Bubble/Caption sub-schemas, documents the v0.1→v0.2 migration runner, and lists corrected acceptance criteria.
  • FFScript Mutation API Spec (2026-04-23) — Full TypeScript interface for the FFScriptDoc wrapper class (T-041–T-045, T-051–T-052, T-054): 15 public methods (panel CRUD, dialogue, choice/branch, scene, placement, bubble, batch), branded ID types, MutationResult/JSON-Patch return shape, typed error hierarchy, Immer integration notes, Convex integration pattern, and corrected effort estimate (L, not M).
  • FFScript Linter Engine Design (2026-04-23) — TypeScript interfaces and default rule catalogue for the pluggable FFScript linter (T-046–T-050, T-035–T-039 collapsed). Updated: LintFix uses serializable FixKind descriptor (Vox DiagnosticFix pattern) so fixes can be stored in Convex and replayed from CLI.
  • Populi Mesh North-Star (2026-05-01) — Strategic plan for taking the Populi mesh from single-node-correct to multi-node power-user dogfood. Decomposes seven workstreams (authoritative leases, GPU truth probes, cross-node secret pairing, model discovery, observability, test coverage, operator UX) into three sequenced capability slices (S1 single-machine, S2 two-node, S3 N-node) with a child-spec roadmap. Companion to the improvement backlog.
  • Populi Mesh Improvement Backlog (2026-05-01) — Flat tagged list of 210 mesh improvements (MESH-001..MESH-210) across transport, registry, hardware probes, cloud providers, mens training, dispatch, docs, UX, observability, security, configuration, persistence, leases, discovery, perf, resilience, migration, and skills. Picked up opportunistically when the relevant area is being touched for slice work.
  • Populi Mesh — Probe Correctness Spec (S1, 2026-05-01) — S1 child spec for workstream W2 partial. Refactors hardware probes (NVML / wgpu / DRM / Metal / DXGI) behind a HardwareProbe trait, adds a mock harness, ships failure-visibility via a probe_failures field on HardwareSummary, and operator-overridable probe order via [mesh.probe.order]. ~1000 LOC, no new dependencies.
  • Populi Mesh — A2A Durability Spec (S1, 2026-05-01) — S1 child spec for workstream W6 partial. Replaces three separate JSON-file stores (a2a / exec-lease / dispatch-results) with a SQLite-backed store behind a MeshStore trait, with WAL mode, schema versioning, lock contention detection, vox populi store migrate / check, and an in-memory backend for tests. ~2000 LOC.
  • Populi Mesh — Local Observability Spec (S1, 2026-05-01) — S1 child spec for workstream W5 partial. Defines the vox.mesh.* span-attribute namespace, threads a MeshTraceContext through orchestrator dispatch and populi handlers, adds a (forward-compat-only in S1) traceparent field on A2ADeliverRequest. No new dependencies.
  • Populi Mesh — Config Baseline Spec (S1, 2026-05-01) — S1 child spec for workstream W7 partial. Designs the workspace Vox.toml [mesh] schema, env-var precedence rules, vox populi config show / check verbs, sensible defaults so vox populi serve --enable works on a fresh box, and the populi-quickstart.md how-to. Maps all 36 existing VOX_MESH_* env vars to [mesh] keys.
  • Populi Mesh — Probe Correctness Implementation Plan (S1, 2026-05-01) — Step-by-step TDD implementation plan for the probe-correctness spec: 17 tasks, ~85 individual steps, every code change shown in full. Recommended starting plan for Slice S1 work because it has zero dependencies on other S1 specs and establishes the trait/mock pattern.
  • Unified Task Hopper — Research, Design Space, and Recommendation (2026-05-09) — Research-and-design-space doc for the cross-cutting “hopper” track (a single developer-facing intake surface fanning work across per-agent queues). Audits the existing AgentQueue / ScopeGuard / AgentEvent surface; surveys three design options (A: lightweight L1 module, B: persistent service crate, C: mesh-native via op-log gossip) and recommends Option A first; defines the typed developer-override contract (PrioritySource = Developer | Orchestrator | LearningPolicy partial order, gated by a new DeveloperOverride capability token); covers the VCS implications (branch-per-batch, inheritance from MergePolicyV1, mid-flight reprioritization state machine Inbox → Triaged → Assigned → Started → CommitMinted → Pushed → Closed, no auto-push); names three new AgentEvent variants (TaskReprioritized, HopperItemAdmitted, HopperItemOverridden) and the telemetry-driven priority-learning loop; explicitly defers Option C (mesh-replicated inbox) until Populi mesh dispatch is authoritative. Wired into the SSOT as cross-cutting track §3.5 with task IDs Hp-T1..Hp-T9 ranging across Phases 0–6.

Mesh Implementation Plans (Phase 0–6 + MENS + Hopper integration)

Section titled “Mesh Implementation Plans (Phase 0–6 + MENS + Hopper integration)”

The seven-phase decomposition of the Mesh & Language-Level Distribution SSOT, plus the cross-cutting MENS distributed-AI track. Each plan is TDD-style: failing test first, file map, ordered tasks with - [ ] substeps and concrete Rust/SQL/Vox code, per-task cargo test + commit suggestion, final phase-wide acceptance + rollback. All landed 2026-05-09; all integrate the unified-task-hopper Hp-T* track per SSOT §3.5; all use canonical vox-db migration policy per SSOT §5.5 (BASELINE_VERSION bump in manifest.rs, no date-stamped or numeric SQL files).

  • Mesh Phase 0 — Foundations Implementation Plan (2026-05-09) — TDD plan for P0-T1..T8: persist file-lock map to vox-db (BASELINE_VERSION 62), single lock-leader election with heartbeat, authoritative leases (ADR-017), JWE-secret injection into task exec context (closes the secret_count-only-logged dead-end at remote_worker.rs:124), TLS / WireGuard option on populi HTTP, hardware probe trait + mock harness (delegates to existing probe-correctness plan), in-process executor behind SkillRuntime trait, traceparent populated on dispatch + read on receiver; bundles the three new hopper AgentEvent variants (Hp-T2) into the events.rs touch. ~2300 lines.
  • Mesh Phase 1 — Language Spine Implementation Plan (2026-05-09) — TDD plan for P1-T1..T9: introduce DurablePromise[T] as the single canonical awaitable lowered to tokio::sync::oneshot + journal entry; deprecate Future[T]/Promise[T] with auto-rewrite hints; @remote fn annotation replacing mesh_* naming; auto-derived activity_id via BLAKE3 over (workflow_id ‖ call_site_span ‖ structural_arg_hash ‖ replay_counter); workflow determinism check (vox/workflow/non-deterministic-builtin); bottom-up effect inference flipping the existing top-down validator; effect-row enum extension with GpuCompute and Mutate (per SSOT §1.2 update, required by MENS Mn-T4/T5); side_effect { ... } block desugar to single-shot activity; vox workflow preview dry-run projector; stable diagnostic-ID namespace vox/<category>/<kebab> for everything new. ~3200 lines (verbose code snippets in parser/HIR/runtime triplet).
  • Mesh Phase 2 — Code Mobility Implementation Plan (2026-05-09) — TDD plan for P2-T1..T7: workflow content-hash via the existing SHA3-512 vox-package CAS (compiler stamps @generated-hash on each workflow/activity); workflow.version("change-1", min, max) patch-marker; vox workflow drain --version <hash> operational tool; CAS-bundle dispatch seeding (envelope ships BundleRef or full bytes); activity result caching ledger keyed on (activity_id, structural_arg_hash) with @activity(dedup="7d") configurable window (BASELINE_VERSION 63); vox dispatch preview routing-decision projector; codegen split lowering DurabilityKind to specific runtime calls (closing the “all three emit identical async Rust” gap). Bundle type accommodates both WorkflowBundle (P2) and ModelBundle (MENS Mn-T3) variants. ~2100 lines.
  • Mesh Phase 3 — VCS Gossip Implementation Plan (2026-05-09) — TDD plan for P3-T1..T9: persist op-log to vox-db (BASELINE_VERSION 64) with tiered retention (hot 10K VecDeque / warm db rows / cold compacted to Checkpoint ops); sign every capability mint and op-fragment with daemon’s vox-secrets-issued Ed25519 key; bounded gossip topic over A2A envelope with Bloom-filter anti-entropy (Demers et al. epidemic algorithm) sweeping every 30s; vector-clock file affinity for mesh-wide hint routing; LockWait outcome added to MergeOutcome; sealed-trait hardening for capability mint with new internal facade crate (lands DeveloperOverride for Hopper Hp-T4); vox-arch-check rule failing CI on raw Command::new("git") outside git_exec.rs; unknown-parent fragment hold + backfill with bounded queue + DLQ; op-log projections architecture (locks, affinity, capabilities, kudos, hopper-inbox all rebuild from log via the Projection trait — Hp-T5). ~1700 lines.
  • Mesh Phase 4 — Dashboard Control Implementation Plan (2026-05-09) — TDD plan for P4-T1..T13: wire mesh routes to live orchestrator state (replace fixtures); “Add a Node” wizard with one-shot install command + QR-code as coequal; donation-policy editor with donations.vox round-trip parse-edit-pretty-print; live topology canvas replacing empty NetworkTab.tsx; audit-log scrubber via op-log replay; per-node spend gauge + mesh-wide budget bar; mesh-aware ⌘K palette; workflow visual debugger; run-row drawer with vox.mesh.trace_id deep-link; non-removable privacy-class indicator on every job and span; onboarding wizard for joining someone else’s mesh; mesh-wide model registry view; P4-T13 Hopper panel (Hp-T6) with /api/v2/hopper/{inbox,assigned,history,submit,reprioritize,start_batch} REST + /v1/ws topic: "hopper" (per SSOT §5.6) + app/src/surfaces/HopperTab.vox panel + ⌘K hopper actions, every reorder mints DeveloperOverride and routes through the signed audit_log.rs writer (per SSOT §5.7). ~2700 lines.
  • Mesh Phase 5 — Public Internet Implementation Plan (2026-05-09) — TDD plan for P5-T1..T10: replace JWT-HS256 with Ed25519-signed envelope (signing covers DeveloperOverride capability for hopper Option C forward-compat); GitHub-attestation gate at pairing via Gist or .well-known (no Vox-owned server, per SSOT anti-goal); per-key quota + reputation EMA; result attestation via signed deterministic replay (per-job ephemeral Ed25519 subkey, lifetime EQUAL to lease TTL — explicit ephemeral.expires_at_unix_ms == lease.expires_at_unix_ms invariant asserted at dispatch); submitter-side spot-check sampler at p=0.05 (with explicit math correcting the SSOT’s “~1%” — at p=0.01 sensitivity is only ~63% over 100 jobs, p≥0.046 needed for ≥99%); kudos accounting end-to-end (one-envelope-two-birds attestation+kudos primitive); mesh-wide model inventory aggregation; per-pairing X25519 keys for JWE; JWT→Ed25519 cleanup window in v0.7. ~3600 lines.
  • Mesh Phase 6 — Grand Network Implementation Plan (2026-05-09) — TDD plan for P6-T1..T9: federation envelope adopting ATProto/ForgeFed JSON-LD shape (NOT ActivityPub transport); optional public attestation registry (vox populi attest publish with .well-known/vox-attestation.json or Gist hosting); Tier-4 micro-VM sandbox interface (firecracker/kata) with stub impl returning NotImplemented; redundant-execution voting with BOINC adaptive replication (skip for trust-tier ≥ Vetted); TEE attestation interface stubbed for SEV-SNP/TDX/Nitro/H100; opt-in Scientia discovery feedback loop publishing quarterly Vox Provider Atlas Findings; vox populi join <invite-url> flow with manifest verify and operator confirmation; periodic trust-graph snapshots via vox-publisher; P6-T9 Mesh-replicated hopper (Option C) completing Hp-T1+T5+T8 mesh adapter — the hopper’s persistent inbox gossips across paired peers via the same Bloom-filter path as op-fragments, with trust-tier ≥ Vetted admission and forgery-rejection. ~3000 lines.
  • Mesh MENS — Distributed Training & Execution Plan (2026-05-09) — TDD plan for Mn-T1..Mn-T15 (cross-cutting MENS distributed-AI track). Charter: training is Candle CUDA-only; inference is GPU-agnostic via existing hardware probes (NVML / wgpu / DRM / Metal / DXGI); SafeTensors as the only on-disk weight format. Audits MENS current state (update 2026-05-11: populi_train removed — mesh env + session scaffolding lives in crates/vox-distributed-training; Candle/NVIDIA gradient sync still future work). Surveys distributed training prior art (Candle, FSDP, ZeRO 1/2/3, Megatron-LM, Petals, Hivemind, SWARM, FedAvg, vLLM TP, llama.cpp RPC, mlx-distributed) with KEEP/ADAPT/REJECT verdicts. New crates vox-distributed-training (Mn-T1) and vox-inference (Mn-T2). ModelBundle { weights_hash: Sha3_512, weights_merkle_leaves: Option<Vec<Sha3_512>>, tokenizer_hash, config_hash, format } extending vox-package CAS — Merkle root for multi-shard models so partial-fetch verification works (Mn-T3). @inference / @training_step / @distributed_train: parser + HirCapability::{GpuCompute, Mutate} + effect lowering + VOX_CUDA_TIER compile gate in vox-compiler (tests/mens_decorators.rs); Rust codegen dispatch to vox-inference / vox-distributed-training still TODO. WorkerDonationPolicy extensions: accepts_training_workloads, accepts_inference_workloads, cuda_tier, metal_tier, vram_min_gb, accepts_sensitive_training_data (Mn-T7; complementary to P5-T9’s accept_sensitive_workloads which gates plaintext-workload visibility — both must hold for sensitive training admission). MENS corpus gaps for the five spine primitives + Vox annotations (Mn-T11 corpus harvester is .vox-only per AGENTS.md). Eval harness (Mn-T12) gating MENS emissions on compile-success + effect-check. Apple Silicon path via Candle-Metal default + mlx opt-in (Mn-T13). Stretch: Petals-style swarm inference for huge models (Mn-T14, deferred to v1.x). Reserved future host for the optional vox-priority-policy learning crate (Hp-T9 from hopper SSOT §3.5). ~1100 lines.

Multi-Agent VCS Replication

Section titled “Multi-Agent VCS Replication”
  • Agentic VCS Automation — Phase 1 Implementation Plan (2026-05-08) — Status: shipped (commits 3e294c1a5..7ca219d90). Step-by-step TDD plan: 9 tasks, ~50 steps, every code change shown in full. Landed capability tokens (WorkingTreeWrite, BranchCreate, WorkspaceId, BranchName) in vox-orchestrator-types, branch binding on AgentWorkspace, the central GitExec wrapper that refuses banned commands at spawn (graduates the markdown policy to Rust), a regex-based secret scanner (AWS / GitHub / OpenAI / Anthropic / Slack / Google / PEM), the vox_commit_create MCP tool that mints commit envelopes (Co-authored-by, Vox-Model-Id, Vox-Workspace) and refuses on workspace↔branch mismatch, the vox_branch_create tool that returns a freshly-minted capability, and a vox.vcs.* telemetry contract locked by integration test. Migrated git_log to the wrapper, added git-concurrency-policy.md, and updated where-things-live.md. Final review verdict: READY TO MERGE; 131 lib tests passing.
  • Agentic VCS Automation — Phase 2 Implementation Plan (2026-05-09) — Step-by-step TDD plan: 11 tasks. Lands the push/PR write-side: PushAllowed / ForcePushAllowed / DestructiveOp capability tokens, vox_push / vox_pr_open (templated body + CI-proof gate) / vox_force_push / vox_branch_delete MCP tools, a normalised flag-set matcher in GitExec that bans clean -fxX-style permutations and push --force / branch -D at the executor layer (raising the bar from Phase 1’s exact-window match), a pub(crate) run_unchecked bypass that only the gated tools can call, a vox-arch-check rule that fails CI on raw Command::new("git") outside git_exec.rs, migration of remaining direct git callsites, capability-ledger persistence via a new OperationKind::CapabilityMinted oplog variant, and the .vox glue scripts (scripts/vcs/{wip,sync,finish,recover}.vox) per AGENTS.md §VoxScript-First.
  • Agentic VCS Automation — Phase 3 Implementation Plan (2026-05-09) — Step-by-step TDD plan: 7 tasks. Adds the dashboard surface for agentic VCS state: read-only /api/v2/vcs/{branch-board,oplog,push-queue,ledger} JSON routes; a VcsBroadcastLayer tracing layer that taps vox.vcs.* events and forwards to a WebSocket at /api/v2/vcs/events; five HTML/HTMX panels (workspace branch board, oplog viewer, push queue, capability ledger, leaked-secret diff scanner). Read-mostly by design: undo affordances render the equivalent CLI command rather than executing — capability minting from the dashboard is deferred to Phase 4.
  • Agentic VCS Automation — Phase 4 Implementation Plan (2026-05-09) — Step-by-step TDD plan: 8 tasks. Lands the Vox-language @vcs.* decorator surface: parser support for @vcs.read_only / @vcs.requires(T) / @vcs.linear_working_tree / @vcs.audit_trail on fn declarations; HIR VcsEffectSet annotation per fn; type-checker rules (read-only cannot transitively call write-side; unannotated cannot call requires; linear cap consumed at most once); codegen-side tracing::info! insertion for audit_trail; hardening of Phase 1’s soft-private mint methods to pub(crate) + sealed-trait via a new vox-orchestrator-internal-mint facade crate enforced by an arch-check rule. After Phase 4 the scripts/vcs/*.vox files type-check without // vox:skip.
  • Agentic VCS Automation — Phase 5 Implementation Plan (2026-05-09) — Optional optimisation phase. Step-by-step TDD plan: 6 tasks. Introduces a GitBackend trait inside git_exec.rs and adds GitBackendGix (pure-Rust gix paths for status, log, diff, rev-parse, ls-files, show-ref); falls back to shell-out for everything else so the GitExec::run surface is unchanged. Adds a vox-vcs-bench Criterion crate that proves the speedup empirically (target ≥5× for rev-parse HEAD) and evaluates jj-lib for log+status to inform a possible Phase 5.5. Behind a gix-backend feature flag (default-on) that is the production rollback path.
  • Agentic Version Control Automation — Failure Modes, jj Footguns, and a Vox-Language Capability Proposal (2026-05-08) — Companion to the replication trio focused on the agent-fatigue / automation-safety angle. Inventories the existing Vox VCS surface (read-only git_tools.rs, jj-inspired vcs_tools/, banned-list policy, no write-side MCP, no dashboard surface). Surveys 2024–2026 reports of how LLM agents fail at VCS (wrong-branch races, hallucinated Co-authored-by: trailers, secret leakage at ~2× human rate, destructive-op incidents). Catalogs jj’s parallel-subagent footguns via the agentjj migration evidence. Proposes a five-layer fix: capability tokens in vox-orchestrator-types, @vcs.* Vox decorators (read_only / requires / linear_working_tree / audit_trail), write-side MCP tools that mint commit envelopes and enforce Clavis secret-scan, dashboard panels (workspace branch board, oplog viewer, push queue, capability ledger, leaked-secret diff scanner), and .vox automation scripts. Lists 10 numbered gaps with target file paths and explicit anti-goals (no jj CLI as agent surface, no new bare keyword for VCS effects, banned-list graduates from prose to Rust).
  • Multi-Agent VCS Replication — Landscape Research (2026-05-03) — Survey of jj, Pijul, Automerge/Patchwork, Yjs, Sapling/Mononoke, Iroh/Hypercore, and the 2025-2026 multi-agent coding products. Confirms no off-the-shelf system provides codebase-scale auto-converging replication; recommends building op-log gossip on top of existing jj-lib + Populi mesh investment (Path 1) over pivoting to Pijul (Path 2) or an Automerge hybrid (Path 3). Cites Automerge-Repo 2.0 (May 2025), Pijul Nest activity, Mononoke’s Meta-internal-only status, ICSE 2025 “Semantic-Aware Replicated Data Types” paper, and Patchwork (Ink & Switch).
  • Multi-Agent VCS Replication — Architecture Spec (2026-05-03) — Op-log gossip architecture on jj-lib + Populi mesh. Defines AgentChange, OpFragment, ConvergenceSet, MergePolicy, ConvergenceEngine primitives; the gossip wire protocol (Populi A2A envelope extension); the auto-merge / surface / arbitrate / block classifier informed by Pijul patch theory and ICSE 2025 SARDT rules; and the four-phase rollout: (1) local multi-agent, (2) conflict UX, (3) mesh gossip, (4) policy/safety. jj-workspace-per-agent migration deferred to Phase 5+.
  • Multi-Agent VCS Replication — Phase 1 Implementation Plan (2026-05-03) — Step-by-step TDD plan for Phase 1 (local multi-agent op-log gossip): 16 tasks, ~80 individual steps, every code change shown. Builds the convergence/ module in vox-orchestrator, extends jj_backend.rs with op-fragment serialization, ships the MergePolicyV1 byte-range classifier, migrates change_create to return AgentChange, adds vox.convergence.* telemetry, and lands a 5-agent + forced-conflict golden test fixture. Phases 2–4 will be drafted as separate plans when queued.

Vox Language Rules & Enforcement

Section titled “Vox Language Rules & Enforcement”
  • Vox Language Rules & Enforcement — Top-Level Plan (2026-05-09) — Five-phase plan to close the gap between LANGUAGE_DESIGN_PRIORITIES.md philosophy (P0–P5, C1–C5) and machine-checkable enforcement. Absorbs a 73-item Rust↔Vox AI-rules audit into Vox-only sequenced work. Optimizes for Vox as a large-language-model destination target: stable diagnostic IDs (append-only with deprecation aliases), --for-llm JSON mode with minimal repro per diagnostic, generated-hash codegen provenance, single-source-of-truth across the Rust↔Vox seam, runtime fuel/panic-trap monitors, and an effect system that makes wrong programs structurally unrepresentable. Phases 1–4 ~13 engineering weeks; Phase 5 multi-quarter.
  • Vox Language Rules — Phase 1: SSOT Collapse (2026-05-09) — Step-by-step plan: 14 tasks. Collapses hand-mirrored Rust↔Vox surfaces (builtin registry → typechecker manifest → LSP completions → mens system prompt → mdbook reference) into single-source-of-truth + xtask-generated outputs. Adds #[vox_diagnostic] proc-macro and the diagnostic catalog scaffolding consumed by Phases 2–5. Every generated output gets a @generated-hash blake3 header; vox-arch-check::generated-file-drift rejects hand-edits. Closes the bare-keyword table behind an xtask add-keyword flow that requires an ADR.
  • Vox Language Rules — Phase 2: Lint Extension (2026-05-09) — Step-by-step plan: 16 tasks. Extends vox-code-audit with 14 new detectors (direct-LLM-call rejection, env.get-secret-shape rejection, ?-operator opportunity, ADR-citation discipline, decorator-position lint, duplicate-prefix names, long-range coupling, panicking-builtin-in-handler, etc.). Each detector ships with stable ID, serializable LintFix descriptor, --explain page, confidence + alternatives, and a negative-example corpus entry. Adds vox check --for-llm JSON output mode with minimal-repro per diagnostic — the largest single delta between Vox and a typical compiler for LLM-agent consumption. Adds @example decorator that becomes both a doctest and a Mens corpus entry, killing doc/test/corpus drift.
  • Vox Language Rules — Phase 3: Cheap Typechecker Rules (2026-05-09) — Step-by-step plan: 9 tasks. Adds typechecker rules that promote convention to compile error: Id[T] required at API boundaries (kills the largest LLM hallucination class for CRUD), named tagged-union error types (no Result[T, str] on public APIs), single workspace syntax_version, machine-checked @deprecated with version-distance escalation, training_eligible propagation in import graph, and a note-severity precursor for the Phase 5 net-effect declaration. Includes vox migrate id-strings codemod for the largest mechanical migration ahead of the rule escalating to error.
  • Vox Language Rules — Phase 4: Runtime Monitors (2026-05-09) — Step-by-step plan: 11 tasks. Ships runtime safety nets the compiler can’t reach: per-call fuel decremented per HIR step, allocation observer with cap, stack-depth cap, panic-trap boundary on every vox run invocation, runtime telemetry redactor for @secret-tagged fields (defense-in-depth alongside the future Phase 5+ static taint), capability-violation runtime trap (gated until Phase 5), idiom fingerprint export (vox.idiom.* events feed back into corpus weighting — closes the LLM-target feedback loop), vox playground --deterministic --seed N for reproducible doctests, and per-call sandbox under vox-bounded-fs in CI mode. CI-strict defaults; end-user friendly with --strict opt-in.
  • Vox Language Rules — Phase 5: Effect System & Workflow Determinism (2026-05-09) — Multi-quarter plan: 8 tasks. Lands the @uses(net | fs | time | random | secret) effect system on every public fn, proves @pure transitively, forbids non-deterministic builtins inside workflow bodies (cashes ADR-019’s promise), enforces @uses(fs(read: "./data/**")) glob declarations against literal paths at compile time. Symmetric error/fix pairs (vox/effect/missing-X-decl ↔ vox/effect/unjustified-X-decl) deliberately designed so LLM training picks up the inverse rule at the same time. Each effect ships warning over two minor versions, then escalates to error; partial completion is a usable improvement.

Language platform (compiler, LSP, diagnostics)

Section titled “Language platform (compiler, LSP, diagnostics)”

Cross-cutting orientation and research artifacts (not registered B-canon unless listed in contracts/documentation/canonical-map.v1.yaml):

Normative reference pages (2026 language-platform closure): operator precedence, literals, doc comments, async / concurrency, FFI, stdlib index, package manager, diagnostic ID policy — plus companion architecture notes playground target shape and editor integrations how-to.

Unknown-unknown probes (2026-05-11): five short findings tracks — diagnostic drift, LSP parity, formatter semantics, telemetry blind spots, migration friction.

Competitive & Ecosystem Research

Section titled “Competitive & Ecosystem Research”
  • Warp Terminal Research Findings (2026-04-29) — Systematic scan of warpdotdev/warp (~60 crates). Identifies AGPL-3.0-only license incompatibility blocking direct vendoring, maps Tier-S/A/B/C targets, confirms deny.toml already rejects AGPL, establishes clean-room reimplement path for command-signatures-v2 → vox-exec-grammar, and recommends Zed (Apache-2.0) as the preferred upstream for B-tree/text primitives. Produced ADR-026, crates/vox-exec-grammar scaffold, .voxindexingignore, and fuzzy-search feature wire-up.
  • Svelte 5/6 vs React Meta-Frameworks Research (2026-05-02) — Comparative analysis of Svelte 5/6 (runes, snippets, MCP), Next.js 15/16 (RSC + Cache Components), and TanStack Start v1.0 (type-safe loaders) against Vox’s React-emit baseline. After codebase verification, the baseline turns out to ship more than expected: state / derived / effect reactive members work inside component { }, on:* directive attributes parse and lower, and a vox_validate_file MCP tool is registered. Confirms Vox should NOT add Svelte as an emit target, but identifies seven mineable items (M1–M7) that extend existing surfaces: reactivity outside component { }, cross-call auto-dep inference, additional bind:/class:/style: directive families, .vox.ui reactive modules, MCP tool polish (vox_validate_source + autofix surfacing), route segment-aware overlap + typed href, and reactive-class state-machine instances. SvelteBench/vox-bench deferred (no defined consumer for the metric). Implementation plan in companion doc.
  • Svelte-Mineable Features Implementation Plan (2026-05-02) — Phased implementation plan (Phases A–G) for the M1–M7 items from the Svelte vs React research. Each phase has concrete file changes (with paths into crates/vox-compiler/), scope estimates, ADR triggers (Phases D and F only), test strategy, and explicit out-of-scope/deferred sections. Phase A (vox_validate_source MCP polish) and Phase B (bind:/class:/style: directives) sized as small (3–5 days each); Phase F (typed parametric fragments) is the largest. Sequencing diagram, cost-bounded auto-dep analysis tiers, and explicit “may-being” exclusions documented.

FableForge Implementation Files

Section titled “FableForge Implementation Files”

Ready-to-use TypeScript drop-ins in docs/src/architecture/fableforge-impl/. Verify field names against the real schema before merging.

  • panel-schema.ts — Runnable Zod schema for Panel/Scene/Background/Bubble/CharacterPlacement, aspectRatioDims(), migrateV01toV02(), checkPanelInvariants(). Implements T-021, T-022, T-025, T-031.
  • linter-engine.ts — Full LintEngine class with 9 default rules, serializable FixKind descriptors, applyFix() resolver, Convex + publish-gate hooks. Implements T-046–T-050, T-035–T-039 (collapsed).
  • cascade-delete.ts — Convex soft-delete (T-192), hard-delete cascade across 12 child tables (T-191), 30-day purge job, requireGameOwnerOrAdmin auth guard (T-193), ESLint rule stub, siloing test suite scaffold (T-205).
  • generation-orchestrator.ts — ImageOrchestrator (Vox ModelScorer pattern): ScoringWeights-driven provider ranking, circuit breaker in Convex, attempt recording for billing. Implements T-004, T-007, T-129, T-130.

GUI-Native Language Roadmap

Section titled “GUI-Native Language Roadmap”
  • Vox GUI-Native Language Roadmap (2026) — Full task specifications for Phases 0–9 of the GUI-native language roadmap: dashboard safety, HIR unification, grammar unification policy, compiler primitive expansion (state machines, effects, typed URLs, design tokens), Web IR validators, workflow/activity/actor integration, corpus migration, and route wiring.
  • GUI-Native Roadmap Execution Status (2026) — Live status overlay tracking what has been implemented versus planned, with per-task commit references and an audit log.

External Frontend Interop (Two-Way React Ecosystem Bridge)

Section titled “External Frontend Interop (Two-Way React Ecosystem Bridge)”
  • External Frontend Interop Plan (2026) — Five-phase plan: build-target split, wire-format SSOT + OpenAPI, HTTP ergonomics decorators, auth/ops stdlib + durability resolution, bidirectional Vox↔React component interop. @island retired; component/routes kept.
  • Frontend Convergence Findings (2026-05-08) — Audit of Vox’s TS/JSX/React emit, GUI primitives, parser/HIR lowering, and two-way interop seeds. Names HIR → Web IR as the frontend SSOT, proposes a new Contract IR layer to unify wire-format emit (Zod / types / client / OpenAPI / JSON Schema), specifies six concrete redundancies (R1–R6) including dead HirFn.is_component flag + codegen_ts/component.rs (Path A) + HirRoute, and shows how Phase 5’s “Vox imports React” reuses extern fn as extern component rather than introducing a new import react keyword.
  • Wire Format v1 SSOT — Versioned specification for how every Vox primitive and composite type encodes over HTTP: transport conventions, type-encoding table (Decimal/BigInt/Date as strings, _tag discriminants, absent-key for Option), error envelope, and versioning policy.
  • Phase 1: Build Target Split Spec (2026) — Design spec for vox build --target=server|fullstack|client, vox emit client, vox init --kind=backend. ~330 LOC across ~6 files; fullstack remains default.
  • Phase 3: HTTP Ergonomics Decorators Spec (2026) — Design spec for explicit method/path on @endpoint, @cors, @auth(scheme: bearer), @role, and @rate_limit decorators. Emits Tower middleware layers in generated Axum crate; OpenAPI 3.1 reflects all.
  • Phase 5: Bidirectional Vox↔React Interop Spec (2026) — Design spec for import react Name from "path" in Vox source, emitted Vox components as npm-publishable React packages, @island retirement, and vox migrate drop-island migration helper.
  • Durability & Scheduling Runtime Audit (2026) — Confirms @scheduled, @durable, workflow, activity are parse-only with zero runtime implementation. Recommends grammar removal; actor retained with documented limitations. See ADR-028.

Core SSoT

Section titled “Core SSoT”
  • V0.5 Core SSoT — Version 0.5 core architecture specifications.
  • Cryptography SSOT (2026) — AEAD policy (vox-crypto), banned stacks, Windows-friendly crypto posture.
  • MENS training SSOT — Training corpus and governance companion to reference/mens-training.md / canonical map domain mens-training.
  • Search & Retrieval SSOT (2026) — Agent-facing retrieval: vox-db contracts, vox-search execution, MCP tools, two-VoxDB distinction (vox-db Rust vs voxdb/server TS emit), policy knobs, dashboard transport. Implementation modules: hybrid memory (memory_hybrid.rs, memory_cache.rs), web tiers (web_dispatcher.rs, searxng.rs), optional backends (vector_qdrant.rs, lexical_tantivy.rs), symbol proximity (crates/vox-search/src/symbol_proximity.rs), CRAG helpers (crag.rs, research.rs).
  • Research / Scientia / telemetry channels — Maps ResearchEvent, research_metrics, and TelemetryEvent; orchestrator bridge, rolling SearchPolicyFeedback, mesh subscriber hook.
  • Terminal Exec Policy SSOT (2026) — Live SSOT for the PowerShell-first terminal exec policy. Scopes the claim to host-side allowlisting and output parsing, explicitly disclaims any codegen-fluency superiority over Bash, and documents why a separate “PowerShell spoke” in MENS is not justified.
  • Agent Shell Fluency Eval Design (2026) — Design-only A/B eval (20 tasks × 2 shells × 5 trials) for the codegen-fluency claim. Not run; not required by current policy. On-shelf until a proposal depends on the wider claim.

Data Storage

Section titled “Data Storage”
  • Data Storage SSOT (2026) — Greenfield target state for how Vox persists, represents, and governs data across libSQL/Turso, contracts/, JSONL/log spools, and Rust in-memory types; seventy-eight numbered findings (F1–F78).
  • Data Storage Migration Backlog (2026) — Ticket-sized work items (M-00 through M-78) across six phases, with owners, blockers, and acceptance criteria; cross-indexed to SSOT findings.
  • Data Storage Lint & CI Spec (2026) — Concrete vox ci data-storage-guard subcommand, clippy denies, deny.toml bans, grep rules, Cursor rule, and CI wiring that enforce the SSOT.
  • RCICD coverage and cost matrix (2026) — Workflow-to-risk mapping, shift-left vs CI boundaries, golden strict-parse alignment, and applied cost optimizations (guards-fast dedupe, WebIR single lane, mobile path filters).
  • Coolify Deployment Contract — Automated CI/CD pipeline definition for the Hetzner VPS including LLM auto-healing loops.
  • Eval sandbox deployment (Coolify) — eval.vox-lang.org MCP HTTP gateway: GHCR image, compose SSOT, DNS, vox ci coolify-eval, Gate 3 alignment.

Documentation Platform

Section titled “Documentation Platform”
  • Shiki, mdBook & Doc Platform Evaluation (2026-04-22) — Quantified feature matrix across 7 doc platforms (mdBook, Zola, VitePress, Starlight, Docusaurus, MkDocs, Nextra). Identifies Shiki ^4.0.1 as already a dependency of vox-vscode; proposes eliminating highlight-vox.js grammar drift via a mdbook-shiki-vox preprocessor and a medium-term migration to Starlight. Covers LLM-friendly documentation formats, llms.txt standard, and AI-first documentation architecture principles.

User Interface & Dashboard

Section titled “User Interface & Dashboard”

Gamification & Identity

Section titled “Gamification & Identity”

Build, Packaging & Modularity

Section titled “Build, Packaging & Modularity”
  • Toolchain Reality & Omnibus Installer Findings (2026) — Analysis of the hidden dependency gap (Node, Rust, WASI) behind the ‘single-command install’ claim and the four-part roadmap to true independence (Native Bundler Swap, Embedded WASM, voxup installer, Cloud Build).
  • Voxup Omnibus Installer Spec (2026) — Architecture and 4-phase implementation plan for voxup, a rustup-style bootstrap multiplexer to fetch hermetic toolchains into ~/.vox/toolchains/, guaranteeing a zero-dependency environment for users.
  • Vox-Populi Extraction Follow-Up Plan (2026) — Honest accounting of plugin extractions deferred after SP1–SP8 foundation landed. Five extraction units (~18,000+ LOC total): mens/tensor residual in vox-populi, vox-populi transport, vox-tensor (Burn/wgpu), vox-oratio Whisper backend, vox-browser. Plus 5 cross-cutting items including AgentSkills open standard adoption (34+ adopters: Claude Code, Codex, Gemini CLI, Copilot, Cursor, etc.) and the vox-skills full retirement path. The follow-up to ship a genuinely slim Vox core + first-class membership in the cross-vendor agent-skill ecosystem.
  • Plugin System Redesign — SP1 Implementation Plan (2026) — TDD task plan for Sub-Project 1 (Plugin Manifest, Catalog & Schemas). 18 tasks covering the vox-plugin-catalog crate (catalog.toml SSOT with 18 plugins + 8 bundles, build.rs validation, runtime accessors, extends-chain resolution, markdown generators), three hand-rolled reference docs, the vox ci generate-plugin-catalog-docs and vox ci plugin-catalog-parity CLI guards, and vox-build-meta deprecation shims. Companion to the parent design spec.
  • Plugin System Redesign — SP2 Implementation Plan (2026) — SP2 implementation complete (batches 1-8, ~9 commits, ABI v1, 11 host tests). TDD task plan for Sub-Project 2 (Host ABI & Loader). 23 tasks covering the new vox-plugin-api crate (ABI version constant, VoxPluginRoot prefix struct, VoxPlugin and VoxHost #[sabi_trait] traits, manifest discriminated union, plain-Rust skill types, seven extension-point placeholder modules), the new vox-plugin-host crate (discover, code-plugin Loader via libloading + abi_stable, dual-payload Registry, SkillRegistry, lifecycle telemetry, error model), two test-fixture plugins (vox-plugin-noop-code cdylib + vox-plugin-noop-skill directory-only) plus a vox-plugin-noop-code-bad-abi companion for the ABI-mismatch test, and vox ci plugin-abi-parity + vox ci plugin-skill-parity CI guards.
  • Plugin System Redesign — SP3 Implementation Plan (2026) — TDD task plan for Sub-Project 3 (MlBackend extension point + first real code plugin extraction). 11 tasks covering the MlBackend #[sabi_trait] definition, as_ml_backend() accessor on VoxPlugin (ABI bump 1→2), new vox-plugin-mens-candle-cuda cdylib crate owning candle-core/candle-nn/qlora-rs/peft-rs/safetensors/tokenizers/memmap2, code-motion of training/checkpoint logic out of vox-populi, deletion of mens-candle-qlora and mens-candle-qlora-cuda features, host-mediated MlBackend dispatch in vox-populi, end-to-end training smoke test, behavioral parity verification.
  • Plugin System Redesign — SP4 Implementation Plan (2026) — TDD task plan for Sub-Project 4 (skill-compiler migration — first skill plugin). 11 tasks covering the directory-only vox-plugin-skill-compiler/ plugin (verbatim port of the existing vox.compiler SKILL.md), removal from vox-skills builtins, orchestrator + runtime + integration-tests consumer migration to vox-plugin-host::SkillRegistry with fallback dispatch through the existing vox-skills registry for the 8 unmigrated skills, and end-to-end MCP behavioral-parity test. Independent of SP3; can ship in either order after SP2.
  • Plugin System Redesign (2026) — Unifies Cargo features, vox-skills, and capability registries into one runtime-loadable plugin system (vox plugin, vox bundle), vox-plugin-catalog SSOT, abi_stable host ABI, bundles (vox-base, vox-fullstack, vox-mesh, vox-server), eight-sub-project sequencing (CUDA spike in SP3). SP7 (2026-05-04, complete): ABI v6; extension traits TensorBackend, AudioCapture, CloudSync, ScriptExecutor; five stub plugin crates (TODO(SP7-followup) for code-motion). Retires vox-build-meta and vox-skills when migration completes.