data-export-and-restore

Data export and restore

In an app with no server, the export file is the only copy of a user's data that can outlive the phone, and restore is the only recovery path they can invoke themselves. Both are dangerous in opposite directions: a lossy export silently becomes someone's backup, and a half-applied restore destroys the very database it was meant to protect. This skill governs the portable artifacts; the on-device VACUUM INTO snapshot and WAL rules belong to persistence-drift.

Depth lives in references/formats-and-encoding.md (CSV/JSON/PDF mechanics) and references/restore-and-merge-policy.md (validation ladder, merge strategies).

Non-negotiable rules

1. Backup and export are two different features — never conflate them. Backup is exact, machine-read, round-trippable, and the only thing restore accepts. Export (CSV for a spreadsheet, PDF for a human) is an interop artifact, lossy by design, and must be refused as a restore source. WHY: the moment a CSV is restorable, a format built for readability becomes the file someone's records depend on.
2. Every backup carries an envelope, and restore reads it first. formatVersion, schemaVersion, appVersion, exportedAtUtc, a checksum over the payload, then the payload. Restore verifies the checksum, refuses schemaVersion greater than the app's with a plain message, and migrates an older payload through the same forward-only path as the database (run-migration). WHY: an unversioned file cannot be refused, only misread.
3. Restore is all-or-nothing and never edits the live database in place. Import into a fresh staging database, validate everything, close every handle, then publish by atomic rename with the previous file kept as a rollback until the new one opens cleanly. WHY: a partial restore is worse than a failed one — it leaves a state the user cannot describe and you cannot reproduce.
4. Machine formats carry canonical values only. Integer minor units, SI integers, ISO-8601 UTC instants, stable ids, untranslated enum codes. Never a localized numeral, a formatted date, a currency symbol, or a translated label in a file that will be parsed. Localize only in human-facing exports, which are never re-imported. WHY: ١٢٫٥ and 12.5 and 12,5 are the same quantity and three different parses.
5. Identity is content-assigned, never a rowid. Every exportable row carries a stable id (UUID/ULID) minted at creation. WHY: re-importing the same file must be idempotent — with autoincrement ids it duplicates every record instead.
6. State the merge policy and show it before it runs. Replace-all (wipe then import) and merge-by-id (last-write-wins on a stored updatedAtUtc) are different promises; the confirmation names which one is about to happen and what will be lost. WHY: "Restore" reads as "add my data back" to a user who is about to lose a week.
7. Stream to a temp file, publish by rename. Build the artifact through an IOSink into the app's own temp directory and rename it into place only when the last byte is flushed. WHY: a 100k-row export assembled in a String OOMs a cheap phone, and a half-written file must never be shareable.
8. Nothing leaves the sandbox without an explicit user action, through an injected Gateway. No auto-upload, no background sync, no "helpful" cloud copy. The share sheet and file-save picker sit behind a ShareGateway/FileExportGateway (service-boundary-and-native), faked in tests.
9. CSV is escaped twice: RFC 4180 and against formula injection. Quote any field containing the delimiter, a quote, CR or LF, doubling embedded quotes; and neutralize a leading =, +, -, @, tab or CR so a spreadsheet renders the text instead of executing it. WHY: an unescaped cell is a code-execution vector in the recipient's spreadsheet, and a lost row in yours.
10. Export and restore return typed results, never throw at the UI. Result<ExportArtifact, ExportFailure> / Result<RestoreReport, RestoreFailure> with a distinct failure per refusal reason (checksum, unsupported version, malformed payload, no space, permission denied). WHY: "Restore failed" with no reason is indistinguishable from data loss to the person reading it.
11. A failed export leaves no artifact. Delete the temp file on every failure path and never publish a partial one. WHY: a truncated file that looks like a backup is the failure mode that surfaces months later.
12. Say what an export is. Exports are plaintext and unencrypted unless you built encryption on purpose; the UI must say so at the moment of sharing, and the claim must match the code (see release-and-store-shipping for claim wording).