Persistence implementation

Use the canonical storage reference for private and published tree layouts, volume guarantees, ownership, capacity and retention. Use backup and restore for operational procedures. This page records implementation details relevant to store changes.

Private volume

Editable documents, settings, assets, themes and installed packages are the source of truth. See content, extensions and API settings for document shapes.

JSON saves use a same-directory temporary file, sync and atomic rename. Asset bytes commit before metadata, avoiding visible metadata referencing an absent file. Page mutations/branch deletes use recovery journals; startup and readiness recover pending transactions. Publication snapshots hold asset hard links under working/publish-snapshot-* until complete. Startup removes abandoned snapshots. Do not edit, prune or back up only selected private files while a writer is active.

On Linux, a close operation reporting EINTR has already released the file handle. Shared file I/O treats that specific result as completed and never retries close on the descriptor, which could otherwise refer to a different file. Write, sync and other close failures still fail their durability barriers; this exception is not permission to ignore persistence errors.

Published volume

Release directories become immutable after their completion marker. The public tree layout describes sequence, activation-intent and history files. Maintain the publisher ordering and the recovery rules when changing these records. Never reuse release IDs or mutate an already-live release to repair metadata.

Storage guarantees and capacity

Test writes, hard links, symlink swaps, directory/file sync and cleanup failures on the supported filesystem. Follow the operational storage requirements and preserve current releases and source snapshots through failures.