Filesystem

The server stores only opaque, content-addressed ciphertext and never holds a key. Clients hold keys, so a client stores plaintext media, signed sidecars, and rebuildable caches. The on-disk layouts are part of the contract.

Sub-doc	Concern
Server Filesystem	Blob store layout, Postgres index, required services, deletion
Client Filesystem	Library layout, local SQLite index, space recovery
Maintenance	Validation, scrubbing, repair, intra-library dedup, atomic writes

Byte transfer is the transfer protocol; metadata sync is Sync.

Shared Principles

• Recovery-first. No database is needed to interpret canonical data. Client sidecars are the source of truth; the server’s PostgreSQL index holds only key-free facts and is rebuildable from stored manifests.
• Atomic writes. Temp file + atomic rename on the same filesystem; never overwrite in place (rules).
• Ephemeral derived data. Only originals and their canonical metadata are irreplaceable.
• 4 KiB alignment. Upload chunks are 4 KiB-aligned so the staging path stays block-aligned.
• Content-addressing. Server blobs are named by their ciphertext hash.

Concern	Server	Client
Stored form	Opaque ciphertext blobs	Plaintext media + CBOR sidecars
Naming	Ciphertext hash	UUIDv7, date-bucketed
Index	PostgreSQL, authoritative, key-free	SQLite, rebuildable
Derived data	Client-generated encrypted blobs	Generated locally, evictable
Originals	Retained while referenced	Present only if synced locally