Extension Points

Audience: core contributors and Enterprise (blackrim-vox-enterprise) implementers. This document defines the stable contract surfaces the open core exposes so that the Enterprise edition can extend it without forking, patching, or carrying its own build of the core.

The open core is Apache-2.0 and complete on its own. Enterprise features (RBAC, SSO, audit, advanced plugins, reporting) live in a separate repo and load against the contracts below. Anything not listed here is internal — implementation detail the core is free to change between releases without a deprecation cycle.

If you need to extend a surface that is not listed here, the answer is to add the extension point to the open core first, in this document, with a versioned contract — not to introduce a private fork.

Versioning

Extension contracts are versioned independently of the binary:

extension/<surface>/v<MAJOR>

• v1 is stable; breaking changes ship as v2 alongside v1 until removal.
• Removal requires one minor release of overlap and a DEPRECATED notice in this file.
• Internal surfaces have no version and may change at any time.

Surface inventory

Surface	What it does	Status
capture/v1	Audio source adapters (mic, system audio, etc.)	Design-locked
asr/v1	Streaming + offline transcription backends	Design-locked
segment/v1	VAD + diarization + intent-boundary detectors	Design-locked
router/v1	Intent classifier + sink dispatch	Design-locked
sink/v1	Output destinations (LLM, S3, email, file, bd)	Design-locked
tts/v1	Text-to-speech backends (output side of the voice loop)	Design-locked
auth-source/v1	Credential providers (BYOK + subscription passthroughs from Claude Code, Codex, Cursor, Copilot)	Design-locked
identity/v1	Authentication + identity provider integration	Reserved for Enterprise (SAML / OIDC, Team Sync)
authz/v1	Fine-grained access control (RBAC) hooks	Reserved for Enterprise
audit/v1	Audit log event emission	Open hook, Enterprise sink
report/v1	Scheduled or on-demand reporting	Reserved for Enterprise
policy/v1	Per-source / per-sink consent + data policy	Implemented — internal/policy/
telemetry/v1	Optional operational telemetry export	Open
secrets/v1	Credential storage abstraction (keychain, vault)	Open

"Reserved for Enterprise" means the core defines the interface but ships either no implementation or a no-op default. The Enterprise repo provides a real implementation, registered via the same loader.

External integrations

Surfaces in the table above are Vox's own contracts. External integrations consume those contracts (most commonly sink/v1) to plug Vox into other tools' ecosystems. Each integration gets its own page in docs/integrations/ covering design, contract mapping, performance constraints, and upstream-coordination tracking.

Integration	What it does	Phase	Design
SageOx (ox)	Writes Vox envelopes as murmurs into the ox team-context ledger; ships in v1 as ox-ledger sink, in v1.1 as full ox-adapter-vox binary	v1 (sink) + v1.1 (adapter)	integrations/ox.md

External integrations are NOT extension points — they are consumers of extension points. Adding an integration does not change Vox's contracts. Each integration page tracks its own status, upstream-coordination items, and version compatibility.

Why split this way

1. No private patches. Enterprise never modifies core source. It only registers implementations against these contracts.
2. Same wire formats both editions. A transcript or intent envelope from the open core is byte-identical to one from the Enterprise edition.
3. Trust boundary is clear. Auditors can verify the core does not call home, store data remotely, or change behavior based on which edition is loaded — Enterprise additions are observable as plugin loads.
4. Community contributions stay in scope. New sink/v1 adapters, capture/v1 sources, and asr/v1 backends from the community are first-class — no core changes required to land them.

Mobile architecture

The architecture for iOS and Android clients is decided. See docs/architecture/mobile-adr.md for the full decision record: which path was chosen (server / thin client), the rejected alternatives, consequences for the boq sub-beads, and open questions. That document is the canonical reference; this file tracks the extension-point contracts the mobile architecture builds on (capture/v1 network source kind, auth-source/v1 subscription token pass-through).

Surface contracts

The detailed contract for each surface (function signatures, configuration schema, lifecycle, error model, version stability rules) will land in a sibling file per surface as the code shape solidifies:

• docs/extensions/capture-v1.md
• docs/extensions/asr-v1.md
• docs/extensions/segment-v1.md
• docs/extensions/router-v1.md
• docs/extensions/sink-v1.md
• docs/extensions/identity-v1.md
• docs/extensions/authz-v1.md
• docs/extensions/audit-v1.md
• docs/extensions/report-v1.md
• docs/extensions/auth-source-v1.md
• docs/extensions/policy-v1.md
• docs/extensions/telemetry-v1.md
• docs/extensions/secrets-v1.md

Until those exist, the rule is: don't ship code that depends on an extension surface whose contract is not written down here. Drafting the contract is part of shipping the feature, not a follow-up.

Loader

Plugins register via a single, documented entry point (binary name and exact loader mechanism TBD with the first capture-loop implementation). The loader emits a structured event for every load so audit (when present) can record which extensions are active in a given run.

What is explicitly NOT an extension point

• The internal segment pipeline orchestrator.
• The on-disk format of intermediate state.
• The CLI surface for end users.
• The dashboard / web UI (when it exists).

These can and will change. If Enterprise needs to influence any of them, the right move is to file an issue proposing a new extension point above the relevant boundary, with a versioned contract.

Change process

1. Propose a new or modified extension point as an issue in this repo, linked from bd.
2. Draft the contract here and in docs/extensions/<surface>-v<N>.md.
3. Review with at least one Enterprise implementer if the change affects a reserved surface.
4. Land in a release tagged with the new surface version.
5. Implement in Enterprise (or community) against the published contract.

This sequence keeps the core honest: every Enterprise feature is built on a public, documented contract that any community implementer could also use.