01 — Architecture

Summary

The whole feature hangs on one seam: every sgit action already accepts an injected api, so the static transport is a sibling class — read-only GET fan-out over any host or folder — with zero changes to any call site, proven by a running spike. Four methods carry the entire read path (including presigned_read_url, which is on the clone path for every blob over ~4 MB — a size-dependent bug waiting for anyone who skips it). Transport resolution is transparent but never silent: sniffed once, sticky, reported in vault info. Publish is a projection of the vault, not a copy, with a fixed plaintext surface recorded by hash in manifest.json.

Key concepts

• The transport seam — a sibling Vault__API class injected at the CLI boundary — not a mode flag, not a new port
• Publish as projection — byte-identical ciphertext regardless of destination; the folder is the vault, projected
• Visible ≠ silent — auto-detection is fine only because the resolved transport is reported and forceable
• The manifest contract — the listing a keyless client needs, and the recorded plaintext surface with sha256 per file

Key ideas

• A 404 is an answer (None), not an error — fail-soft per object, never per run.
• Local fan-out gets one worker: parallelism on open() is pure overhead.
• Two on-host layouts are sniffed on first read, then sticky — the same URL works live and static.

Read the document