ADR-0002: Storage and catalog separation

Context

File bytes and relational catalog data have different durability, query, authorization, and transfer needs. Putting bytes in SQL complicates streaming and storage operations; exposing object storage directly would bypass domain authorization and metadata consistency.

Decision

Store file bytes in private object storage under opaque keys. Store logical identity, versions, ownership, Root Folders, metadata, access grants, and audit facts in SQL. Authenticated service functions coordinate both systems and issue only short-lived operation-scoped transfer authorization.

Consequences

• Search and authorization operate over relational data without scanning file bytes.
• The CLI never receives permanent storage or database credentials.
• Object storage and SQL cannot share one transaction, so upload workflows need pending/complete states, idempotency, reconciliation, and orphan cleanup.
• Provider-specific storage details remain behind the vault object module.

Validation required

Accept this decision after an infrastructure proof demonstrates private upload/download, SQL coordination, recovery from failures on either side, and absence of anonymous object access.