ADR 16: Drive-Centric Domain Vocabulary

Status: Accepted
Date: 2026-05-16

Context

Substratum exposes a private, content-addressed mesh behind an identity-gated gateway. Earlier docs and code used Vault as the name for the user-scoped root of a namespace (folder tree, pinning scope, and default policy boundary). That term is accurate for engineers but weak for end users, who reason in drive, folder, and file metaphors.

Per Conway’s law, the shape of the system should mirror how we describe the product. If product, support, and the file explorer speak in drive vocabulary while HTTP models and routes say vault, two mental models compete and onboarding suffers.

This ADR does not change network or PSK behavior; it fixes domain language at the application boundary (APIs, ingress DTOs, generated clients, explorer) so one vocabulary spans org and code. The full project glossary lives in Glossary (Ubiquitous Language).

Decision

1. Canonical aggregate: The user-visible root of a private namespace is a Drive. Product copy, ingress/OpenAPI models, and front-end types use Drive / drive_id (and related names), not Vault / vault_id, for new and revised public surface area.

2. Hierarchy under a drive: Folders and files remain the primary concepts inside a drive. Tree listings distinguish directories from blobs using field names that match that model (existing is_directory flags or future kind enums stay aligned with folder vs file).

3. Identity and sharing unchanged: Owner remains did:plc (AT Protocol). Permissions and content-level sharing continue to use Passport receipts and Access Control principals; user-facing labels may say “people” or “groups” without renaming those security primitives.

4. Persistence vs public language: The MVP bootstrap schema uses table drive (see Persistence migration in this ADR). Internal Rust modules should match (drive entity); the public API must not leak obsolete vault naming.

5. Documentation drift: Older ADRs and the technical specification that say “Vault” for the same aggregate should be read in light of this ADR: Drive is the preferred user- and API-facing term; vault is deprecated for new external contracts.

Consequences

Positive

• One vocabulary from UI through OpenAPI and generated clients; easier reviews and fewer translation bugs.
• Clearer bounded context: “Drive API” matches “what lives on my drive.”
• Aligns with ADR 15: Web File Explorer as the primary surface for browsing storage.

Negative

• Renaming is a breaking change for any consumer of vault-named routes or DTO fields; coordinate ingress, libs/api-client, and apps/file-explorer in one pass or version the API deliberately.
• Short-term duplication if legacy paths are kept during migration.

Neutral

• IPFS remains content-addressed under the hood; “drive” does not imply a single CID root—it names the policy and namespace aggregate the gateway resolves.

Persistence migration (operators)

Bootstrap DDL (via crates/migration) creates table drive with policy drive_isolation. If an older database still has a vault table with data you must keep, run a one-time migration before relying on the new schema—for example rename the table and recreate the policy on drive, or use dump/restore. Greenfield environments run Migrator::up on gateway boot.