Codex / Arca compatibility boundaries

This page is the contract between application code, vox-db, and vox-pm for persisted data. It implements the boundaries implied by ADR 004: Codex over Arca over Turso.

Naming

Do not introduce a second physical store for the same logical data without a new ADR.

What application code may call

• Prefer VoxDb::connect / Codex::connect with DbConfig from vox-db.
• Prefer VoxDb::store / domain helpers in vox-db for CAS and schema-backed operations.
• Avoid new direct turso:: usage outside the direct Turso allowlist. If you must extend the allowlist, update that document in the same change.

Configuration (canonical env)

Resolution for CLIs and long-running apps:

• DbConfig::from_env — minimal parsing; with local feature, empty env may yield in-memory for tests.
• DbConfig::resolve_canonical (alias of resolve_standalone) — canonical user-global Codex: VOX_DB_* first, then legacy TURSO_URL + TURSO_AUTH_TOKEN, then a concrete file path (never silent :memory: when local is enabled). See how-to-voxdb-canonical-store.
• open_project_db — non-canonical repo-local .vox/store.db for snippets/share/cache only.

Migrations and SQL rules (Arca)

• Schema DDL is owned by vox-db under schema/domains/, ordered in manifest.rs as SCHEMA_FRAGMENTS and applied once at BASELINE_VERSION (single maintained baseline row in schema_version). Older databases with MAX(schema_version) != BASELINE_VERSION must be exported (vox codex export-legacy), moved to a new file, then imported after baseline — no in-place bridge. Capability checks in vox-db use required table sets, not numeric version thresholds (see codex-vnext-schema).
• Higher-level writes for chat/search domains should go through VoxDb helpers in codex_chat.rs where possible instead of ad-hoc SQL.
• Bodies use patterns consistent with Turso batch execution: execute_batch for non-row-returning DDL/DML; pragmas via pragma_update where applicable. Fragment v7 remains intentionally empty in the manifest (historical no-op).

Convex-like features

Subscriptions, change logs, invalidation, and HTTP streaming are Codex capabilities layered on one database — not a separate DB product (ADR 004 § Decision item 5).

Verification

• vox ci check-codex-ssot (shim: scripts/check_codex_ssot.sh) — required SSOT files exist (includes this page).
• vox ci check-docs-ssot (shim: scripts/check_docs_ssot.sh) — doc inventory and path references.
• Crate tests: cargo test -p vox-db --lib (with local feature as in CI) exercises in-memory Codex and the Codex alias.

Related

• Codex BaaS scaffolding
• Direct Turso usage allowlist
• Forward migration charter
• Doc-to-code acceptance checklist