Substratum.cloud

Appearance

Architecture Decision Record (ADR) 25: Directory Lexicons and First-Class Passports ​

Status: Proposed
Date: 2026-05-16

Context ​

In ADR 22: Drive Lexicon and Persistence, we introduced the DriveMetadata lexicon and a dual-persistence strategy (swarm and database) for Drives. However, we left directories as "second-class citizens." Empty folders and implicit parent directories were persisted solely as drive_entry rows in the database with is_directory: true, lacking an underlying AT Protocol lexicon or content-addressed passport receipt.

This omission caused significant architectural friction:

  1. Frontend Workarounds: The API had to shim "fake" PassportReceiptDto objects (with null versions and signatures) for directories so the UI could display sharing indicators.
  2. Inconsistent Provenance: While files and drives had cryptographic provenance and verifiable metadata, directories did not, breaking the "sovereign metadata" principle for the entire filesystem tree.
  3. Sharing Complexity: Sharing a directory required attaching a receipt to a node that didn't natively support one in the same way files did.

Decision ​

To unify the data model and eliminate these workarounds, we will elevate directories to first-class cryptographic objects:

  1. Directory Lexicon: Introduce a DirectoryMetadata lexicon (e.g., cloud.substratum.directory) to represent folders. This lexicon will contain standard metadata (id, owner_did, name, created_at, access_control, etc.).
  2. First-Class Passports: Every node in the tree (Drives, Directories, Files) MUST have a valid, content-addressed passport receipt (receipt_cid) stored in the swarm and referenced in the database.
  3. Explicit Creation: When a directory is created via the API, the backend must generate the DirectoryMetadata lexicon, sign it, store it in the blockstore, and write the passport and receipt_cid to the database.
  4. Implicit Parent Directories: When files are uploaded to deep paths (e.g., a/b/c/file.txt), the backend must generate and store DirectoryMetadata lexicons and receipts for all implicitly created parent directories (a, b, and c).
  5. Remove Shims: Remove the None branch in API mappers (e.g., to_tree_entry_from_model) and enforce that PassportReceiptDto is fully populated for all entries returned to the client.

Consequences ​

Positive ​

  • Unified Data Model: Eliminates the need for frontend workarounds and "fake" passports.
  • True Provenance: The entire filesystem tree, including structural nodes, now has verifiable cryptographic provenance.
  • Consistent Sharing: Sharing a directory uses the exact same AT Protocol receipt mechanism as sharing a file or a drive.

Negative ​

  • Increased Overhead: Deep-path file uploads will require generating, signing, and storing multiple lexicons for implicit parent directories, increasing the latency and complexity of the upload flow.
  • Migration Required: Existing directory rows in the database without receipt_cid values will need to be backfilled or migrated to have valid lexicons and receipts.