"Maintainability hotspot matrix (baseline)"

Maintainability hotspot matrix

This document is the baseline for the package and maintainability rollout. Update rows as migrations land.

Acceptance criteria (cross-cutting)

AreaCriteria
Bounded file readsSame cap source (vox_scaling_policy::ScalingPolicy::embedded().thresholds.max_file_bytes_hint); same error messages for stat/over-cap/read/UTF-8 where anyhow is used
JSON Schema (CI/MCP)Generated or shared validators match existing contract tests; MCP input_schema stays draft-07-compatible for strict clients
SSE / LLM streamingGolden tests cover data { lines split across arbitrary byte chunks; no regression on [DONE] and delta content extraction
Retry / backoffDocumented caps and multipliers; activity codegen ActivityOptions unchanged unless accompanied by compiler+fixture updates
Process supervisionManaged binary resolution order unchanged; sidecar state file format unchanged
DB row mappingturso/StoreError semantics preserved; one module at a time

Hotspot matrix

IDHotspotOwner crates / pathsTarget consolidationGating tests / notes
H1Bounded UTF-8 reads14× bounded_fs.rs, vox-cli/.../bounded_read.rsvox-bounded-fsPer-crate tests; scaling TOESTUB
H2MCP input_schema vs paramsvox-mcp/tools/input_schemas.rs, params.rsschemars-first + documented overridesinput_schemas registry tests
H3JSON Schema validate boilerplatevox-cli CI commands, vox-toestub/suppression.rsvox-jsonschema-utilContract + scorecard tests
H4AI generate schema checkvox-cli/commands/ai/generate.rsSame validator as CI or renamed lightweight APIIntegration if present
H5SSE OpenAI streamingvox-runtime/llm/stream.rs, vox-ludus/.../transport.rsvox-openai-sse (Utf8LineBuffer, sse_data_line_delta)Chunk-boundary unit tests in crate
H6OpenAI wire typesvox-runtime/llm/wire.rs, vox-mcp/llm_bridge/providers/openai.rsvox-openai-wireMCP + runtime compile
H7Retry/backoffactivity.rs, openclaw.rs, social_retry.rs, scholarlyvox-primitives backoff; backon no-go (see resilient_http, social_retry docs)Activity + publisher tests
H8Simple activity IDsactivity.rs, vox-populi, populi_clivox-primitives idCollision expectations
H9Process supervisionvox-cli/process_supervision.rssysinfo liveness; PATH via which crate (path_lookup_executable)Manual / doctor flows
H10reqwest::Client defaultsLudus, MCP, ARS, CLI, publishervox-reqwest-defaultsTimeout-sensitive integration
H11row.get mappersvox-db/store/ops_*.rsvox_db::row_cols! macro (pilot)vox-db tests per module
H12Env / config parsingvox-config, scattered env::varvox_config::env_parse + Clavis for secretsvox ci clavis-parity, doctor, clavis-ssot

Codegen and contract surfaces (do not drift silently)

  • vox-compiler — codegen_rust/emit/http.rs, with_emit.rs (ActivityOptions)
  • contracts/cli/command-registry.yaml, contracts/mcp/tool-registry.canonical.yaml
  • Scaling policy: contracts/scaling/policy.yaml (embedded via vox-scaling-policy)