ADR 22: Drive Lexicon and Persistence

Status: Accepted Date: 2026-05-01

Context

In Substratum, a Drive is the user-scoped storage root (see ADR 16). Initially, drives were hardcoded in the gateway for the MVP. To support user-created drives and maintain the "sovereign metadata" principle, we need a way to:

1. Define a canonical schema for drive metadata using AT Protocol lexicons.
2. Persist this metadata in a way that is both queryable (for the UI) and verifiable (via content-addressing).
3. Support the creation of empty folders (directories) within these drives.

Decision

We have implemented the following architectural changes:

1. Drive Lexicon

A new lexicon type DriveMetadata is added to substratum_lexicons. This record contains:

• version: Lexicon version (e.g., 1.0.0).
• id: The deterministic drive UUID.
• owner_did: The DID of the drive owner.
• name: The display name of the drive.
• created_at: ISO 8601 timestamp.
• updated_at: ISO 8601 timestamp.
• access_control: List of DIDs with access to the drive.
• receipt_cid: Optional CID of the latest sharing receipt.
• description: Optional drive description.

2. Dual Persistence Strategy

When a drive is created via POST /api/v1/drives:

• Content-Addressed Storage (Swarm): The DriveMetadata record is serialized and stored in the retrieval swarm. This ensures the metadata is immutable and verifiable.
• Relational Database (PostgreSQL): The drive metadata is also persisted in the drive table. This allows for efficient listing and filtering using native Postgres features like Row-Level Security (RLS).

3. Drive Listing and Sharing

• Listing: The GET /api/v1/drives endpoint queries the database using substratum_resolution::rls::list_drives_for_current_did. This ensures that users only see drives they own or have access to.
• Sharing: Drives are sharable via PATCH /api/v1/drives/{drive_id}/nodes/access_control with an empty path. This updates the access_control and receipt_cid fields in the drive table and stores a Receipt lexicon in the swarm.

4. Directory Creation and Path Handling

• Directory Creation: A new endpoint POST /api/v1/drives/{drive_id}/directories allows creating empty folders, persisted as drive_entry rows with is_directory: true.
• Root Path Handling: Path sanitization logic has been updated to support empty strings, representing the drive root, enabling sharing and other operations on the drive itself.

Consequences

• Positive:
  • Drives are now user-creatable and persistent across sessions.
  • Metadata is verifiable via CIDs while remaining efficiently queryable via SQL.
  • Native RLS ensures strict multi-tenant isolation for drive listings.
  • Support for empty directories improves the user experience in the file explorer.
• Negative:
  • Increased complexity in the drive creation flow (dual-write to swarm and DB).
  • Requires careful synchronization if drive metadata (like the name) is updated in the future.