Where Things Live
Where Things Live
Section titled “Where Things Live”Flat lookup table for “I need to add/find X — where does it go?”. Optimized for LLM tool-call efficiency: skim by left column, jump to the right column.
If your concept doesn’t appear here, add the row in the same PR — that
keeps the table accurate and prevents the next assistant from having to
guess. The full crate roster with layer assignments lives in
layers.toml.
For directory sprawl, sparse folders, and non-Rust artifact provenance, see Repository layout sprawl audit (2026).
Repository roots (navigation)
Section titled “Repository roots (navigation)”Grouped map of top-level trees — use this before inventing a new parallel folder (for example another docker/ or tools/).
| Group | Paths | Notes |
|---|---|---|
| Rust workspace | Cargo.toml, crates/ | Implementation + vox-arch-check / layers.toml. vox-arch-check does not recurse into target/, .git/, node_modules/, etc. when scanning (see [arch_check.walk_prune]). Reclaim disk from stale artifacts: cargo clean or scripts/clean-build-artifacts.vox (syntax-checked in CI via cargo run -p vox-cli -- check scripts/clean-build-artifacts.vox). For crates under workspace.exclude in root Cargo.toml, set CARGO_TARGET_DIR to the repo target/ when running cargo --manifest-path … so Cargo does not grow a second crates/.../target/. |
| Contracts | contracts/, contracts/index.yaml | SSOT bundles; path changes require index + consumer updates. |
| Docs (source) | docs/src/ under repo docs/ | Narrative SSOT; .md doctests. |
| Docs (site) | docs-astro/ | Astro build; sidebar from frontmatter. |
| Apps & editors | apps/ | GUI surfaces — registry in contracts/frontend/surface-ownership.v1.yaml. |
| Examples / fixtures | examples/, tests/fixtures/ | Non-production sandboxes and bundles. Goldens under examples/golden/ include clean_build_stdlib_reference.vox (pointer to scripts/clean-build-artifacts.vox). |
| Automation | scripts/*.vox | Prefer vox run over new shell/Python glue. |
| CI / hooks | .github/workflows/, lefthook.yml | Runner wiring; see CI docs under docs/src/ci/. |
| Deploy / compose | infra/, docker/, root docker-compose.yml | Overlap is intentional (different compose working dirs); eval SSOT called out in deploy docs. |
| Build-time Node helper | apps/build-tools/render-durable-animation/ | Invoked from scripts/render-durable-animation.vox. |
Quick reference: subsystem → crate (by layer)
Section titled “Quick reference: subsystem → crate (by layer)”L0 — pure types
Section titled “L0 — pure types”| Crate | One-line scope |
|---|---|
vox-arch-check | CI guard binary; enforces layers.toml. Walk-based rules skip artifact trees (built-in + optional [arch_check.walk_prune]); Rule 8 staleness uses one batched git log when available. |
vox-build-meta | Build-time helper emitting VOX_BUILD_NUMBER / VOX_GIT_HASH; use as [build-dependencies] only. |
vox-db-types | Pure-data L0 leaf for vox-db: row types, IDs, schema descriptors. |
vox-mesh-types | Pure-data mesh transport types. |
vox-mesh-policy | Parse/print donations.vox and mesh donation policy fragments (SSOT P4-T3). |
vox-mesh-models | Mesh model registry aggregation types (ModelRegistry) for dashboard /api/v2/mesh/models (P4-T12). |
vox-orchestrator-types | Pure-data L0 leaf for vox-orchestrator: agent/task IDs, file affinity, switch actions, provider catalogs, VCS capability tokens (WorkingTreeWrite, BranchCreate, etc.). |
workspace-hack | Cargo-hakari unification crate; do not edit by hand. |
L1 — primitives & utilities
Section titled “L1 — primitives & utilities”| Crate | One-line scope |
|---|---|
vox-foundation | Utility umbrella: cheap trace ids, exponential backoff, AgentOS mutation kinds (was vox-primitives), daemon wire-protocol types (was vox-protocol), tracing_subscriber bootstrap presets (was vox-tracing-init). Excluded from workspace-hack for fast-leaf compile. |
vox-bounded-fs | UTF-8 file reads capped by vox-scaling-policy max_file_bytes_hint. |
vox-checksum-manifest | SHA-256 release asset verification against checksums.txt manifests. |
vox-release-artifacts | Portable .tar.gz / .zip packaging + checksums.txt line helpers for vox compile and vox ci release-build. |
vox-tauri-codegen | Hint-only Tauri 2 packaging under target/generated/tauri-packaging/ (tauri.conf.json + runtime-capabilities.projection.json from contracts/capability/runtime-capabilities.v1.yaml; not a full src-tauri crate yet). |
vox-assets | [bundle.assets] manifest validation + staged copy tree for compile outputs. |
vox-crypto | Pure-Rust crypto primitives (chacha20poly1305 AEAD, ed25519, x25519); sole crypto SSOT per AGENTS.md §Cryptography Policy. |
vox-exec-grammar | AST parser and risk classifier for shell/Vox command invocations; backs exec-policy.v1.yaml enforcement. |
vox-grammar-export | Exports the Vox grammar artifact for downstream tooling. |
vox-hf-layout | SSOT: Hugging Face config.json layout parsing for MENS (vox-populi::mens::tensor::hf_load) and vox-plugin-mens-candle-cuda. |
vox-http-envelope | Wire-format v1 §6 JSON error envelope for generated Axum handlers (vox-codegen emitted apps). |
vox-identity | Identity primitives: signing keys, trust ledger entries. |
vox-jsonschema-util | Shared JSON Schema compile + validate helpers for CLI, contracts, and tooling. |
vox-openai-sse | OpenAI-compat SSE line reassembly and chat completion delta extraction. |
vox-openai | Core OpenAI integrations and abstractions. |
vox-openai-wire | OpenAI-compatible chat completions JSON types (non-streaming wire) shared across MCP and runtime. |
vox-package-types | Pure-data L1 leaf for vox-package: manifest, lockfile, package_kind, resolver types. |
vox-plugin-api | Shared API surface for Vox plugins: ABI version, traits, manifest types, error types. |
vox-plugin-types | Pure-types surface for the vox plugin system: manifests, skill types, state-backend trait. |
vox-telemetry | L1 telemetry facade: METRIC_TYPE_* constants, TelemetryRecorder trait, record_event! macro. Zero domain dependencies. |
vox-http-client | Shared HTTP client presets (user-agent, timeouts) for CLI, runtime, and AI transports. |
vox-research-events | Typed SCIENTIA research event types and PreregistrationV1. |
vox-rule-pack | Declarative YAML rule-pack loader for code-audit detector patterns and Scientia heuristics. Zero heavy deps. |
vox-scaling-policy | Compile-time and runtime accessors for scaling SSOT (contracts/scaling/policy.yaml). |
vox-secrets | Central secret resolution and compatibility adapters for Vox. |
L2 — domain libraries
Section titled “L2 — domain libraries”| Crate | One-line scope |
|---|---|
vox-capability-registry | Transport-independent capability registry (YAML SSOT) + Mens chat tool descriptors. |
vox-claim-extractor | SCIENTIA claim extraction pipeline: VeriScore, atomic decomposition, MiniCheck verification. |
vox-config | Centralized configuration and env/default resolution for Vox tooling; project_manifest parses [workspace] / [bundle] slices from Vox.toml for vox compile. |
vox-constrained-gen | Grammar-constrained inference engine — Earley/PDA backends, deadlock watchdog, stream-of-revision. |
vox-doc-inventory | Generate and verify docs/agents/doc-inventory.json (schema v3) without Python. |
vox-eval | Vox expression evaluator (interpreter for vox run —interp). |
vox-install-policy | SSOT constants for Vox install/update surfaces (source path, release targets, default GitHub coordinates). |
vox-mcp-registry | Compile-time MCP tool name/description registry from contracts YAML (SSOT). |
vox-nanopub | SCIENTIA nanopublication builder: TriG emission, Ed25519 signing. |
vox-prereg | SCIENTIA pre-registration: Trusty URI signing, analysis-plan deviation detection. |
vox-project-scaffold | Shared Vox.toml + src/main.vox + skill scaffolding for vox init and MCP. |
vox-repository | Repository discovery, stable identity, layout probes, and agent scope helpers for external and internal Vox workspaces. |
vox-ro-crate | SCIENTIA RO-Crate 1.2 JSON-LD metadata builder. |
vox-share | Public-URL tunneling for Vox apps: Cloudflare Quick Tunnels (default), localhost.run (fallback), Tailscale Funnel (explicit). |
vox-skill-runtime | Abstract sandbox runtime trait for skill execution. Implementations ship as plugins (wasm, container). |
L3 — heavy runtimes
Section titled “L3 — heavy runtimes”| Crate | One-line scope |
|---|---|
vox-actor-runtime | Process-oriented runtime: actors, mailboxes, supervision, scheduling, LLM/Mens activity primitives. |
vox-cli-core | Shared internals for the vox CLI binary (argv parsing helpers, exit-code policy). |
vox-code-audit | AI code quality stub detector — finds stubs, magic values, empty bodies, missing references, and DRY violations. |
vox-drift-check | Workspace drift and pattern-repetition linter (multi-language: Rust, TypeScript, Vox). |
vox-codegen | Codegen + WebIR + vox_ir extracted from vox-compiler. Consumes analysis types from vox-compiler. |
vox-codegen/src/projection_bundle.rs | project_bundle_from_hir — SSOT assembly of WebIR, AppContract, RuntimeProjection, ShellProjection, and RequiredRuntimeCapabilities for emitters. |
vox-compiler/src/shell_projection.rs | Typed shell/mobile primitive projection from HIR (@back_button, @deep_link, @push). |
vox-compiler/src/required_capabilities.rs | HIR-derived sorted capability id list for packaging / filtered Tauri runtime-capabilities.projection.json. |
vox-scientia-jsonschema-codegen | Offline cargo run tool: contracts/scientia/*.schema.json → vox-research-events typify bundle (schema_types.generated.rs). |
vox-compiler | Unified Vox compiler: lexer, parser, AST, HIR, typechecker, and codegen. MENS decorators @inference, @training_step, @distributed_train parse in parser/descent, effects + CUDA gate in typeck/. Orientation: vox-compiler-architecture-research-2026.md. |
vox-compiler/src/eval/shell_stdlib.rs | Interpreter (--interp) mirror of shell‑tier std.* builtins — must stay aligned with vox-actor-runtime (Cargo cycle prevents a direct dep). See vox-shell-stdlib-ssot-2026.md. |
vox-actor-runtime/src/builtins/mod.rs | SSOT Rust lowering targets for std.fs / std.process / structured formats (std.csv, std.toml, std.yaml, std.io) used by native codegen. |
vox-shell-stdlib-ssot-2026.md | Architecture SSOT: argv‑first shell‑tier stdlib vs host shells / vox_run_shell. |
vox-container | OCI container runtime abstraction — supports Docker and Podman. |
vox-corpus | Training data contracts, preflight, corpus SSOT, and Mens dataset metadata. |
vox-dashboard | Local Axum-served orchestration dashboard (SPA host). |
vox-db | Codex / VoxDb facade: schema migrations, store ops, Turso/libSQL access for the Vox workspace. |
vox-deploy-codegen | Deployment artifact codegen: Dockerfile, Compose, K8s, Fly, Coolify, systemd. Pure text generation. |
vox-doc-pipeline | Docs lint + doctest helpers for docs/src/; Starlight sidebar and RSS are built at docs-astro publish time (see root AGENTS.md). |
vox-package | Vox package manager runtime: content-addressed artifact cache, registry HTTP client, workspace discovery. |
vox-inference | MENS Mn-T2: InferenceBackend trait, capability metadata, multi-backend dispatcher (stubs until CandleMetal/CUDA wiring). |
vox-distributed-training | MENS Mn-T1/Mn-T6: TrainingSession, signed GradientShard / CheckpointBundle, OperationKind::TrainingCheckpoint mapping. |
vox-mens-eval | Mn-T12 eval harness types (CompileVerdict); CLI/CI wiring expands here. |
vox-ml-cli | ML / Oratio / Populi / telemetry CLI binary (vox-ml-cli); Mens training, GPU features, optional workflow glue. |
vox-forge | Platform-agnostic Git forge API — GitHub, GitLab, Gitea, Forgejo. |
vox-gamify | Gamification layer — companions, quests, battles, and free AI integration. |
vox-git | Pure-Rust Git bridge using gix (no C, no libgit2). |
vox-inspect-bridge | SCIENTIA Phase 5: UK AISI Inspect task adapter, atomic-NEI novelty scoring. |
vox-lsp | Vox Language Server (stdio JSON-RPC). Capability matrix: vox-lsp-capabilities-ssot-2026.md. |
vox-openclaw-runtime | OpenClaw client + ARS runtime adapter, executor, context bundles, hooks. |
vox-orchestrator | Multi-agent file-affinity router: Orchestrator struct + all impl blocks, task dispatch, dei_shim, planning, services, models, config, runtime glue. 65,560 LoC (budget 70K, 7% headroom as of 2026-05-15). queue/lock/oplog in vox-orchestrator-queue, MCP in vox-orchestrator-mcp. Extraction plan: see 2026-05-15-orchestrator-tier-d-plan.md. |
vox-orchestrator-core | Planned — not yet landed. Will hold the Orchestrator struct + orchestrator/ impl blocks (~35K LoC) once Tier D executes. Extraction blocked by 20 sibling crate:: imports in orchestrator/**/*.rs; requires co-moving Orchestrator struct + ~8 modules. See 2026-05-15-orchestrator-tier-d-plan.md §3. |
vox-orchestrator-mcp | MCP (Model Context Protocol) tool layer for vox-orchestrator. Extracted in 2026-05-08 reorg Phase 4. |
vox-orchestrator-cap-mint | Sealed-trait facade for capability minting (WorkingTreeWrite, BranchCreate). The only crate that may call the sealed::__mint_* friend hooks in vox-orchestrator-types. (P3-T6) |
vox-orchestrator-queue | Locks, oplog, and affinity tracking for vox-orchestrator. Extracted in 2026-05-08 reorg Phase 5. |
vox-orchestrator-test-helpers | Test-only fixtures and mocks for vox-orchestrator: MockBulletinBoard, load_golden_fixture. |
vox-oratio | Speech-to-text (Oratio) — Candle Whisper (Rust) STT and transcript refinement. |
vox-plugin-catalog | SSOT catalog of all first-party Vox plugins and distribution bundles. |
vox-plugin-host | Host-side plugin discovery, loading, and registry. |
vox-populi | Vox Populi: multi-node worker registry, HTTP control plane, and Mens native ML (Burn / Candle QLoRA). |
vox-publisher | Unified news syndication and publishing for Vox. SCIENTIA mesh intake from orchestrator research events: research_mesh.rs (+ contract contracts/scientia/research-mesh-intake.v1.schema.json). |
vox-scientia | SCIENTIA cluster umbrella — all Phases A–H as sub-modules: producers (Phase A signal emitters), replay (Phase B re-executor), manuscript (Phases C+3+4 IMRaD/LaTeX scaffolders), critic_gate (Phase D gate), class_routing (Phase E venue routing), findings_site (Phase G HTML builder), dashboard (Phase H JSON builders). |
vox-scientia-ingest | Scientia corpus ingestion pipeline. |
vox-search | Local-first retrieval execution: memory hybrid, repo inventory, Codex chunks, policy, and optional lexical/vector backends. |
vox-skills | Skill marketplace and plugin architecture for the Vox agent system. |
vox-ssg | Static site generator for the Vox docs surface. |
vox-tensor | Pure-CPU JSONL data loaders / training-pair types (Burn extracted 2026-05-08). |
vox-test-harness | Shared compiler/tooling test fixtures plus workspace_paths (repo_root_for_tests), env_scratch (scoped set_var/remove_var), temp_root (tempfile::TempDir). |
vox-wasm-engine | Single-source-of-truth Wasmtime engine + WASI execution for Vox programs and skill plugins. |
vox-webhook | HTTP webhook gateway for the Vox agent system. |
vox-wire-format-validator | CI guard: enforces Wire Format v1 SSOT and Contract IR implementation parity. |
vox-workflow-runtime | Interpreted workflow execution MVP (local + mens activity hooks). |
vox-mesh | Distributed service mesh models and policies. |
vox-tauri-sherpa | Tauri mobile sherpa components. |
L5 — surfaces
Section titled “L5 — surfaces”| Crate | One-line scope |
|---|---|
vox-cli | Vox command-line interface: compile, run, bundle, and workspace diagnostics. |
vox-integration-tests | Cross-crate integration test harness (test-only L5). |
vox-orchestrator-d | Vox orchestrator daemon binary. Extracted from vox-orchestrator in 2026-05-08 reorg Phase 4. |
vox-gui | Tauri desktop shell; depends on vox-cli / vox-orchestrator. |
vox-audit | CR-L gate runner binary (vox audit <thing>); implements the JSON report shape from contracts/ci/vox-audit-contract.v1.yaml. |
voxup | Desktop & CLI environment installer. |
Common tasks → exact path
Section titled “Common tasks → exact path”| I want to… | The right place |
|---|---|
| Add an MCP tool | crates/vox-orchestrator-mcp/src/<group>_tools.rs (e.g. git_tools.rs); register dispatch in mcp/dispatch.rs |
| Add an HTTP route (orchestrator) | crates/vox-orchestrator-mcp/src/services/routes/ |
| Add a CLI subcommand | crates/vox-cli/src/commands/<group>.rs + register in commands/mod.rs |
Add a CI subcommand under vox ci | crates/vox-cli/src/commands/ci/ |
| Add a new CI/db guard | crates/vox-cli/src/commands/ci/<name>.rs + register in cmd_enums.rs and run_body.rs. Mirror db_schema_coverage.rs. |
| Add a speech-to-code audit artifact | Contracts under contracts/speech-to-code/; narrative findings under docs/src/architecture/vox-speech-*-2026.md; cross-crate tests under crates/vox-integration-tests/tests/speech_*. |
| AI-first language fixtures (taxonomy + seed catalog + lifecycle) | contracts/agentos/ai-first-fixtures.v1.yaml (JSON Schema: contracts/agentos/ai-first-fixtures.v1.schema.json) + narrative SSOT ai-first-fixtures-research-2026.md. |
Local act configuration (catalog image pin, platform map) | .actrc (repo root) |
| Self-hosted CI runner image | Dockerfile.ci-runner (repo root); published via .github/workflows/publish-ci-runner.yml to GHCR |
Extend vox ci pre-push modes / timing JSON | crates/vox-cli/src/commands/ci/pre_push.rs — add Step to build_steps or extend PrePushOpts |
vox ci dev-loop-audit (AI/local compile-loop diagnostics) | crates/vox-cli/src/commands/ci/dev_loop_audit.rs |
vox ci docs-reality-audit (doc/code audit artifacts + metrics) | crates/vox-cli/src/commands/ci/docs_reality_audit.rs + contracts/reports/docs-reality-audit/ |
vox ci parse-status (golden parse matrix → examples/PARSE_STATUS.md) | crates/vox-cli/src/commands/ci/parse_status.rs |
| Find the canonical path for GUI surfaces (interop app, experimental visualizer, fixtures, VS Code host) | contracts/frontend/surface-ownership.v1.yaml — apps/interop/marquee_app, apps/experimental/visualizer, tests/fixtures/frontend/test_app_bundle, apps/editor/vox-vscode |
Add a Db<Entity>Id newtype | crates/vox-db-types/src/ids.rs (use the string_id! macro). |
| Add a DB store operation | crates/vox-db/src/<concept>.rs (impl block on VoxDb) |
| Add a pure-data DB row type | crates/vox-db-types/src/store_types/ (NOT vox-db) |
| Add a pure-data DB type | crates/vox-db-types/src/ |
| Add an orchestrator type (Agent/Task/etc.) | crates/vox-orchestrator-types/src/agent_types/ |
| Add an orchestrator policy module (D1–D10) | crates/vox-orchestrator/src/<module>.rs + register in lib.rs + add row to this table |
| Add a research-pipeline stage (claims/gate/planner/provider/types/verifier) | crates/vox-orchestrator/src/dei_shim/research/<module>.rs. web_gather delegates to vox-search (WebSearchDispatcher, CragRouter); planner/claims/verifier remain Phase 0a stubs until vox-claim-extractor. CLI: vox research run; MCP: vox_research_run. Telemetry bridge / policy feedback / mesh tap: research_event_metrics_bridge.rs, search_policy_feedback.rs, mesh_subscriber.rs; narrative research-scientia-telemetry-channels.md. |
| Orchestrator policy façade (all D1–D10) | crates/vox-orchestrator/src/orchestrator_policy.rs |
| Circuit breaker — doom-loop detection (D6) | crates/vox-orchestrator/src/circuit_breaker.rs |
| Confidence fusion — Socrates trigger (D3) | crates/vox-orchestrator/src/confidence_fusion.rs |
| Tier cascade — model routing (D1) | crates/vox-orchestrator/src/tier_cascade.rs |
| Registry-backed model resolution (Thompson arms, privacy-local filter) | crates/vox-orchestrator/src/registry_model_resolve.rs |
Inference tier/modality config for routing (InferenceConfig, TierProfile) | crates/vox-orchestrator/src/mode.rs |
| Embedded orchestration feature flags (YAML → runtime gates) | crates/vox-orchestrator/src/orchestration_feature_flags.rs |
| Plan-mode trigger — React vs. plan (D2) | crates/vox-orchestrator/src/planning/plan_mode_trigger.rs |
| Risk matrix — HITL escalation (D5+D9) | crates/vox-orchestrator/src/risk_matrix.rs |
| Privacy classifier — sensitivity detection (D8) | crates/vox-orchestrator/src/privacy_classifier.rs |
| Cache predictor — prefix cache routing (D7) | crates/vox-orchestrator/src/cache_predictor.rs |
| Budget gate — token/cost limits (D7) | crates/vox-orchestrator/src/budget_gate.rs |
| Compaction trigger — strategy selection (D7) | crates/vox-orchestrator/src/compaction_trigger.rs |
| Calibration — drift detection + bandit (D10) | crates/vox-orchestrator/src/calibration.rs |
| Sub-agent dispatch — spawn vs. inline (D4) | crates/vox-orchestrator/src/subagent_dispatch.rs |
| Orchestrator policy metric_type constants | crates/vox-telemetry/src/types.rs — METRIC_TYPE_* constants |
| Orchestrator feature flags | contracts/orchestration/feature-flags.v1.yaml |
AgentOS MCP → mutation_kind SSOT (orchestrator + std.agentos in Vox) | crates/vox-agentos-mutation/ |
| AgentOS ACI envelope + mutation classification (MCP) | crates/vox-orchestrator-mcp/src/aci/ |
| AgentOS guardrail kernel / checkpoint / intent planner | crates/vox-orchestrator/src/agentos/ |
| AgentOS policy ledger (MCP mutation_kind → orchestrator risk overlay) | crates/vox-orchestrator/src/agentos/policy_runtime.rs |
| AgentOS shell backend adapters (contract-first) | crates/vox-cli/src/commands/runtime/shell/backends/ |
| Semantic filesystem / intent retrieval bridge | crates/vox-search/src/semantic_fs/ |
| AgentOS ACI contracts | contracts/aci/agent-computer-interface.v1.yaml + agent-computer-interface.v1.schema.json |
| Add a code-audit detection rule | crates/vox-code-audit/src/detectors/<rule>.rs |
| Add a skill manifest field | crates/vox-plugin-types/src/skill_manifest.rs |
| Add a plugin manifest field | crates/vox-plugin-types/src/plugin_manifest.rs |
| Add a queue / lock / oplog method | crates/vox-orchestrator-queue/src/{locks,oplog,affinity}/ |
| Add an LLM provider adapter | crates/vox-orchestrator-mcp/src/llm_bridge/providers/<name>.rs |
| Add a code generator (Rust target) | crates/vox-codegen/src/codegen_rust/ |
| Add a code generator (TypeScript target) | crates/vox-codegen/src/codegen_ts/ |
| Add a layer rule / arch-check rule | crates/vox-arch-check/src/main.rs + extend layers.toml schema |
| Add an architectural exception (allowed inversion) | Append [[known_inversions]] block in layers.toml with a reason |
| Add a new workspace crate | Update Cargo.toml [workspace.dependencies] AND add a row to layers.toml — vox-arch-check will fail otherwise |
| BundleRef / Bundle / BundleStore (P2-T1) | crates/vox-package/src/bundle.rs |
| WorkflowDrainStarted / WorkflowDrainState (P2-T3) | crates/vox-orchestrator/src/drain_oplog/workflow_drain.rs |
| activity_result_cache — table DDL + SQL constants (P2-T5) | crates/vox-db/src/ddl/activity_result_cache.rs |
| SCIENTIA claim extraction pipeline (VeriScore, MiniCheck, T1→T2) | crates/vox-claim-extractor/ |
| SCIENTIA drift linter — workspace pattern-repetition checks | crates/vox-drift-check/ |
| SCIENTIA UK AISI Inspect adapter, atomic-NEI novelty, ChronoFact, EvidenceConflict | crates/vox-inspect-bridge/ |
| SCIENTIA nanopublication builder — TriG, Ed25519 signing, Trusty URI | crates/vox-nanopub/ |
| SCIENTIA pre-registration — signing, deviation detection, Bayesian stopping | crates/vox-prereg/ |
| SCIENTIA research event types and ResearchEventEmitter trait (L1) | crates/vox-research-events/ |
| SCIENTIA RO-Crate 1.2 JSON-LD builder — CFF, CodeMeta, TOP-Level-2, ACM badges | crates/vox-ro-crate/ |
L0/L1 split: if your consumer only needs row/param TYPES (no async, no connection), depend on
vox-db-typesdirectly — not onvox-db. The fullvox-dbcrate transitively pulls intursoand tokio.
Plugins (L4 — cdylib only; never compile-time deps for L0..L3)
Section titled “Plugins (L4 — cdylib only; never compile-time deps for L0..L3)”If you’re writing a plugin (concrete sandbox, ML backend, GPU probe, etc.),
it goes in a new crates/vox-plugin-<name>/ and depends on vox-plugin-api.
Don’t depend on vox-orchestrator or vox-cli from a plugin.
| Plugin crate | Provides |
|---|---|
vox-plugin-browser | Browser automation plugin (chromiumoxide CDP). |
vox-plugin-cloud | CloudSync plugin stub: HF Hub / S3 model artifact sync. |
vox-plugin-grammar-export | Export Vox grammar in standard formats (Lark, EBNF, JSON Schema, XGrammar-2, etc.). |
vox-plugin-mens-candle-cuda | ML training backend plugin: Candle + CUDA. Implements MlBackend. |
vox-plugin-mens-candle-metal | MENS Apple Silicon Metal execution plugin. |
vox-plugin-nvml-probe | Hardware probe plugin: NVML for NVIDIA GPU introspection. |
vox-plugin-oratio | Speech-to-text plugin: Candle Whisper backend extracted from vox-oratio. |
vox-plugin-oratio-mic | AudioCapture plugin stub: Oratio microphone device backend. |
vox-plugin-populi-mesh | Populi mesh transport plugin (composite: code + skill). |
vox-plugin-publication | Publication plugin: RSS/Atom ingest with dedup, Reddit/YouTube publish, scholarly job feeds. |
vox-plugin-runtime-container | Skill-runtime plugin: Docker + Podman backends for vox-skill-runtime. |
vox-plugin-runtime-wasm | Skill-runtime plugin: wasmtime-based WASI sandbox (default for pure-compute skills). |
vox-plugin-script-execution | ScriptExecutor plugin stub: sandboxed .vox script runner. |
vox-plugin-webhook | Webhook plugin: HTTP listener with HMAC signature verification (GitHub, GitLab, generic). |
When to NOT add a new crate
Section titled “When to NOT add a new crate”The default answer to “should this be a new crate?” is no. Add to an existing crate unless one of these is true:
Binary-only tools
Section titled “Binary-only tools”Crates with kind = "binary" in layers.toml (e.g., vox-arch-check, vox-populi, vox-orchestrator-d) don’t need a [workspace.dependencies] entry in the root Cargo.toml — they’re consumed via cargo run -p <name>, not as library dependencies. The “Add a new workspace crate” instruction below applies to libraries only.
- The new code has zero callers in any existing crate (likely a plugin)
- The new code is pure types (no async, no DB) AND will have ≥3 consumers (consider an L0 or L1 crate)
- A subsystem in an existing crate has grown past its
max_locbudget and is asking to be split (see Phase 4–5 of the reorg outcome)
vox-arch-check’s orphan detector flags new crates with no consumers. If you
add one, expect that warning to land on your PR until you wire it up — that’s
working as intended.
Skill-only plugins (no Cargo.toml — exempt from layers.toml)
Section titled “Skill-only plugins (no Cargo.toml — exempt from layers.toml)”These live under crates/ but are not Cargo crates. Each has a Plugin.toml
and one or more .skill.md files. They are loaded at runtime via the plugin
host, not compiled as Rust library crates.
| Dir | Purpose |
|---|---|
crates/vox-plugin-noop-skill/ | No-op stub skill used in plugin-host integration tests. |
crates/vox-plugin-skill-compiler/ | Compiler skill — wraps vox compile as a Vox skill. |
crates/vox-plugin-skill-git/ | Git skill — wraps common git operations as Vox skills. |
crates/vox-plugin-skill-memory/ | Memory skill — CLAUDE.md / MEMORY.md management as a Vox skill. |
crates/vox-plugin-skill-orchestrator/ | Orchestrator skill — agent lifecycle management via Vox skill API. |
crates/vox-plugin-skill-rag/ | RAG skill — retrieval-augmented generation pipeline as a Vox skill. |
crates/vox-plugin-skill-testing/ | Testing skill — test-run orchestration as a Vox skill. |
crates/vox-plugin-skill-testing-validate/ | Test-validate skill — validates test outputs against expected results. |
crates/vox-plugin-skill-v0/ | Legacy v0 skill format shim — compatibility bridge. |
Planned but not yet landed
Section titled “Planned but not yet landed”Crates documented in architecture plan docs but with no directory on disk yet.
The [planned] table in layers.toml is the canonical index;
each row there points to the plan document that owns the work.
Do not create a new crate whose name matches these before checking the linked plan document — the design context and API shape are likely already specified.
SCIENTIA pipeline phases
Section titled “SCIENTIA pipeline phases”These will be folded into vox-scientia sub-modules when implemented (Phase I onwards):
| Planned crate | Notes |
|---|---|
vox-claim-extractor | SCIENTIA claim extraction: VeriScore, MiniCheck, T1→T2. |
vox-inspect-bridge | UK AISI Inspect adapter, atomic-NEI novelty, ChronoFact. |
vox-nanopub | Nanopublication builder: TriG, Ed25519 signing, Trusty URI. |
vox-prereg | Pre-registration: Trusty URI signing, deviation detection. |
vox-ro-crate | RO-Crate 1.2 JSON-LD metadata builder. |
vox-scientia-ingest | SCIENTIA corpus ingestion pipeline. |
MENS / distributed training
Section titled “MENS / distributed training”| Planned crate | Notes |
|---|---|
vox-distributed-training | MENS Mn-T1/Mn-T6: TrainingSession, gradient shards. See mesh MENS plan. |
vox-inference | MENS Mn-T2: InferenceBackend trait + multi-backend dispatcher. |
Orchestrator extractions
Section titled “Orchestrator extractions”| Planned crate | Notes |
|---|---|
vox-cli-ci | Planned — not yet landed. vox ci subcommand extraction from vox-cli/src/commands/ci/ (22K LoC, 74 files). Blocked by 3 shared modules that must move to vox-cli-core first. See 2026-05-15-cli-ci-extraction-plan.md. |
vox-orchestrator-core | Planned — not yet landed. Extract src/orchestrator/ (12,825 LoC) + Orchestrator struct into new crate. Blocked by Rust coherence (all inherent impl blocks must co-move with the struct); minimum co-move set ~17K LoC. See 2026-05-15-orchestrator-tier-d-plan.md. |
vox-orchestrator-cap-mint | Sealed-trait façade for capability minting (P3-T6). |
Mesh / release packaging
Section titled “Mesh / release packaging”| Planned crate | Notes |
|---|---|
vox-mesh-models | Mesh model registry aggregation types. |
vox-mesh-policy | Parse/print donations.vox and mesh donation policy fragments. |
vox-agentos-mutation | AgentOS mutation-kind SSOT — code currently lives in vox-primitives::agentos_mutation. Extract when fan-in ≥ 3. |
vox-checksum-manifest | SHA-256 release asset verification. |
vox-release-artifacts | .tar.gz/.zip packaging helpers for vox compile. |
vox-assets | [bundle.assets] manifest validation + staged copy tree. |
OpenAI / HTTP surface splits
Section titled “OpenAI / HTTP surface splits”| Planned crate | Notes |
|---|---|
vox-openai-sse | OpenAI-compat SSE line reassembly. |
vox-openai-wire | OpenAI-compatible chat completions JSON types. |
vox-http-envelope | Wire-format v1 §6 JSON error envelope for generated Axum handlers. |
| Planned crate | Notes |
|---|---|
vox-share | Public-URL tunneling (Cloudflare Quick Tunnels, localhost.run, Tailscale). |
vox-ssg | Static site generator for Vox docs surface. |
vox-exec-grammar | AST parser and risk classifier for shell/Vox command invocations. |
vox-install-policy | SSOT constants for Vox install/update surfaces. |
vox-dashboard | Local Axum-served orchestration dashboard (SPA host). |
vox-mens-eval | Mn-T12 eval harness types (CompileVerdict). |