"VoxDB connection policy (SSOT)"

VoxDB connection policy (SSOT)

Surfaces must pick an explicit policy so Codex is never silently dropped on critical paths while optional tools can degrade with clear remediation.

Policy types

PolicyWhenBehavior
StrictRuntime, most CLI commandsVoxDb::connect / connect_canonical_strict; propagate StoreError.
Degraded optionalMCP stdio, optional cloud throughputvox_db::connect_canonical_optional with DbConnectSurface; None + structured tracing::warn.
Legacy primary (training)Mens training DB thread onlyVoxDb::connect_default; LegacySchemaChain until primary is migrated (no automatic vox_training_telemetry.db attach).

Telemetry availability: surfaces using degraded optional connect (None when Codex is absent) do not append Codex rows (research_metrics, populi_control_event, completion ingest, and similar). That is expected; it is not silent misconfiguration. Operator-oriented telemetry SSOT: telemetry-trust-ssot.

Remediation string: vox_db::REMEDIATION_CANONICAL_DB (crates/vox-db/src/connect_policy.rs).

Callsites (inventory)

SurfaceCrate / entryPolicyNotes
MCP servervox-mcp/src/main.rsDegraded optionalPersistence off when DB missing; agent keeps running.
Populi cloud resolvervox-populi/.../cloud/resolver.rsDegraded optionalThroughput profiles empty when DB absent; providers still work.
Mens training DB threadvox-populi/.../candle_qlora_train/db_thread.rsCanonical connect_defaultFails closed on legacy primary until voxdb cutover runbook.
vox-runtimevox-populi / vox-runtime/src/db.rsStrictFails fast on connect errors.
CLI research / DB / publicationvox-cli (many connect_default)StrictErrors bubble to user.
Orchestratorvox-orchestratorOptional Arc<VoxDb>Features skip when db missing.

Adding new callsites

  1. Choose policy from the table above.
  2. Use connect_canonical_optional or [connect_canonical_strict]; avoid ad-hoc .ok() on connect_default unless the surface is explicitly optional and logs remediation.

Which store should I use? (decision tree)

flowchart TD
  start[Need_durable_Codex_rows]
  start --> q1{Repo_backed_MCP_or_daemon}
  q1 -->|yes| q2{Want_clone_local_only}
  q2 -->|yes| proj[Default_VOX_WORKSPACE_JOURNEY_STORE_project]
  q2 -->|no_org_wide| canon[Set_VOX_WORKSPACE_JOURNEY_STORE_canonical]
  q1 -->|no_single_user_or_global| user[Canonical_vox.db_VOX_DB_PATH_or_remote]
  proj --> file[".vox/store.db_under_repo_root"]
  canon --> turso[User_global_or_VOX_DB_URL]
  user --> turso
  • Default (project): interactive journeys write to .vox/store.db under the discovered repo root — good for per-clone isolation.
  • canonical: same env resolution as user-global Codex (VOX_DB_*); use when operators want one remote Turso / one vox.db across many working copies.
  • vox codex verify prints workspace journey mode, a redacted summary of the canonical config used by that command, baseline schema_version digest, and a pointer to the voxdb cutover runbook for legacy primaries.
  • Canonical store env: docs/src/reference/env-vars.md — VOX_DB_PATH, Turso URL/token.
  • Mens training: docs/src/reference/mens-training.md — canonical connect_default + legacy migration.
  • Cutover: docs/src/operations/voxdb-cutover-runbook.md.