storage quotas and encrypted sync: budgeting bytes on someone else's machine

the account quota as contract

The quota table is the short version of the whole sync product:

Two implementation details make the numbers livable rather than merely hard. First, content is stored once per account by transport digest (loopLibraryContents is keyed by digest), and a version is an authorization row pointing at content, so retaining a version costs a row, not a copy; canonical content is deleted only after its final global version reference is gone. Second, ceilings compact rather than freeze: when a loop or the account hits a version ceiling, the backend compacts the oldest prunable version, preserving one authorization row for the current head and each retained checkpoint parent, instead of refusing every future save. The head, version, immutable content, and the loopLibraryUsage account ledger update in one atomic mutation, so a quota check can never disagree with the bytes it counts.

The write budget also fences identity, not merely volume. claimGeneration is an account-wide monotonic counter that turns a lost response into a recoverable case: a create-claim checkpoint carries the generation, an exact lost-response retry stays idempotent across unrelated deletes, and an older claim cannot bind across a delete-and-recreate because the new head is stamped with its creation generation.

The server-side analogue of this accounting is a registry, not a convention. Sponge keeps costs.json at its repository root, a checked manifest of all 166 product data surfaces with a kind (authoritative, derived, telemetry, served), a retention class (ephemeral, ttl:<ISO-8601>, account, tombstone, persistent), an owner module, and a budget on every authoritative entry. A new table, bucket, stream, dynamic route, blob, or provider meter fails check:cost-surfaces until it registers, and the checker walks the backend schema’s defineTable calls, PostHog capture literals, and dynamic routes looking for unregistered surfaces. An authoritative surface must also name its deletion path: the budget for storing a thing includes the path for removing it.

durable evidence for every remote transition

Sync fails in one characteristic way: the request succeeds remotely and the response is lost. The local library therefore writes its intent before it calls, so recovery is reconciliation against evidence rather than inference.

• Sync attempts are durable. Before an upload crosses the transport, a syncAttempts record lands in IndexedDB inside the same transaction discipline as everything else, capped at MAX_LOCAL_SYNC_ATTEMPTS_PER_LOOP = 16, with the oldest evicted when a newer proof needs the slot. On a lost response, the client reconciles only against exact recorded evidence: which loop, which expected cloud digest and revision. An ambiguous create is never rebound by inference; it is fenced remotely and forked under a fresh logical ID.
• Deletes fence before they remove. A signed-in delete writes a deletionFences record (one per loop, carrying the tab’s UUID operation token and the account) before local state is removed. Committed fences survive remote success and ambiguous unavailability alike, and a delayed cloud import is rejected while a durable fence protects that account and loop.
• Recovery fences are absent-only. A lost create may advance the claim generation only through an atomic absent-only fence: if the loop ID turns out to be occupied, the concurrent head is preserved and the local copy reconciles or forks: the fence never overwrites an existing head, and the delete mutation is never reused as a recovery mechanism.

The pattern underneath all three: the durable record is the authority on what the client believed it sent, so an ambiguous network outcome degrades into a typed branch (reconcile, fork, or fenced) instead of a guessed overwrite.

design for eviction

The platform gives you two APIs for the browser budget: navigator.storage.estimate() to read current usage and quota, and navigator.storage.persist() to request the durable, non-evictable bucket. The Soundfish codebase calls neither. That is itself the design position: persistence is a hint the platform may deny, so the model behaves as if eviction will happen.

What that looks like concretely: the crash-recovery journal in app/persistence.ts keeps MAX_REVISIONS = 24 revisions with the newest first inside a MAX_RECOVERY_JOURNAL_BYTES = 2 MiB IndexedDB cap, plus one latest snapshot in local storage, bounded so the journal itself is never the thing that exhausts the quota. Song saves cap at MAX_LOCAL_SONGS = 256 digest-keyed entries. When a quota or corruption failure does arrive, the rule is to preserve stored data: a save that cannot commit reports a typed quota or limit result rather than dropping rows to succeed. And because every document is also its own shareable #s1. URL fragment, the library is a cache of something the user can always carry out; eviction costs convenience, not the data.

The budgeting rule generalizes: cap every surface, name every refusal, write intent before crossing the network, and keep the artifact portable enough that losing the store is survivable. Quotas are only punitive when they are implicit.

sources

• sound.fish: lib/library/model.ts, lib/library/local-library.ts, lib/storage/, app/persistence.ts
• sponge: costs.json and the fenced-lease model for server-side mutation budgets