A backup is often described as a copy. For a local creative project, that can be the wrong mental model.
The file may contain the work the user wants to keep, along with details that only make sense on the machine where it was created: a local storage identifier, a device-specific path, a cached authority marker, or a credential. Copying all of those fields may make the backup less portable and more dangerous.
A good backup contract starts with ownership: which values belong to the project, and which values describe this installation?
Portability requires a projection
WorldScript Studio’s canonical egress path treats export as an explicit projection. It can preserve the stored carrier where available, overlay fields owned by the application, remove local metadata, then admit the resulting portable output. This sequence is more intentional than dumping the current storage record into a file.
Why preserve the carrier? Because the application may not own every field in a project document. Why overlay modeled edits? Because changes in the editor must reach the output. Why remove local metadata? Because an export may be imported on another device, where local identifiers or authority markers could point to the wrong context.
The three actions have different purposes. Preserving every stored byte would retain local-only state. Rebuilding only from the model could drop data the application does not own. A deliberate projection balances those obligations.
Secrets need a separate boundary
The library backup service excludes API keys. That is an important rule even when the backup itself is encrypted: credentials should not accidentally become part of an ordinary project-sharing format. Backup encryption and secret exclusion solve different problems. One protects a package while stored or transferred; the other limits what the package contains in the first place.
The backup also treats snapshots as entries with their own outcomes. If a snapshot cannot be read, the service records it as unavailable rather than failing the entire operation. That makes partial evidence visible. It does not turn the backup into a guarantee that every historical snapshot will restore.
Name the storage representation
The filesystem path can retain exact source text. The IndexedDB path stores a structured value. Both can support a backup contract, but “exact” means something different in each case.
A portable format should state what it promises: which project fields survive, which metadata is removed, which secrets never enter the archive, and what the application does when part of the source cannot be read. A reader can then judge the real boundary instead of inferring it from the word backup.
Test policy, not just file creation
A test that says “an archive was produced” misses the most important questions. Better tests verify that:
- owned project changes appear in exported data;
- opaque user-owned fields remain where the carrier contract requires them;
- local metadata does not appear in portable output;
- credentials are excluded;
- a failed snapshot entry is reported without discarding unrelated backup content;
- each storage adapter preserves the representation it actually owns.
Those checks turn portability into an explicit policy. They also make future metadata additions safer: the team must decide whether a new field belongs in the project, belongs to one installation, or belongs in a separate secret store.
A backup should travel with the user’s work and leave behind the state that only the original machine can interpret. That is not a universal format rule; it is a deliberate boundary. Document it, test it, and keep it separate from claims about encryption, synchronization, or restore completeness.
Continue reading
This closes Engineering for No-Loss Data Integrity. Start with Anatomy of a No-Loss Persistence Campaign for the boundary map that connects the series.
Practical extension: test the backup as a portability boundary
An exclusion rule needs both sides: what must travel and what must stay on the original machine. Write a small inventory before defining the archive:
| Data class | Typical policy | Restore question |
|---|---|---|
| User-authored project data | Include | Can another machine open it? |
| Machine paths and device identifiers | Recompute or omit | Can they be safely rediscovered? |
| Authentication tokens and API keys | Exclude by default | Is a separate, explicit credential transfer supported? |
| Cache and derived indexes | Rebuild when practical | Is a rebuild bounded and observable? |
| Migration/version marker | Include only if meaningful to the exported format | Can an older app reject it clearly? |
Then test a round trip on a clean profile or second machine. Inspect the archive for secrets, restore it, and verify both that the creative work is present and that excluded host state was not silently resurrected. A checkbox saying “backup complete” proves only that an operation returned; it does not prove portability or secret exclusion.
For browser editions, communicate the storage model plainly. MDN's storage guidance describes best-effort storage, quotas, eviction, and the persistent-storage request. For native editions, scope filesystem access to the required app data rather than granting broad paths; see Tauri plugin permissions.
Top comments (0)