ctx.backup controls Desktop-owned backup jobs. It is available in Desktop App 0.3.0 and later. The App performs file I/O; plugin JavaScript receives bounded summaries and opaque IDs, never arbitrary filesystem write access.
ctx.backup
backup.read
backup.control
configure(eventId)
write:true
snapshot().configuring
message
command({action:'start', ruleId, eventId})
const snapshot = await ctx.backup.snapshot(); const stop = ctx.backup.subscribe(show, error => ctx.log.warn('Backup status unavailable')); ctx.on('start', ({ eventId }) => ctx.backup.command({ action: 'start', ruleId: snapshot.rules[0].id, eventId })); return stop;
Refresh the selected rule/job from current state in a real plugin. Do not automatically replay an unknown command outcome. Read the job list to determine what happened. Successful command acknowledgement does not mean the copy or verification completed.
snapshot()
subscribe(listener, onError?)
command({action:'disable-auto', ruleId, eventId})
Reads require backup.read; other operations require backup.control as well. The runtime also requires a currently dispatched write:true event that declares backup.control. Invented, expired and read-only event IDs are rejected; automatic starts are owned by the already-authorized App service. Jobs/rules are scoped to the caller's installation. Revocation or disabling interrupts that installation's active work and disables its future automatic rules. A host runtime stopping because it is hidden is not a revocation.
macOS uses recognized external physical volumes. Windows currently supports USB volumes exposed by the external-storage provider; arbitrary internal disks, network/cloud locations and unrecognized Thunderbolt/PCIe Windows storage are not supported by this provider. Setup refuses unknown physical identity and any source/target pair sharing a physical device, including separate partitions.
When the App can map a selected card root to its Dock CFexpress, SD or microSD reader, native setup can authorize future cards in that reader. Otherwise automatic mode is restricted to the selected source volume identity. Names and drive letters are display hints, not identity. Cards already present at App startup do not start automatically; interrupted jobs need explicit review/resume.
Source and target folders are identity-bound. A replaced directory requires setup again. Jobs retain their original rule snapshot even if future rules are reconfigured. A changed source file list or source metadata requires a new job rather than silently changing the scope of an interrupted job.
The scanner includes ordinary and hidden source files while excluding known OS metadata directories (.Spotlight-V100, .Trashes, .fseventsd, .TemporaryItems, System Volume Information, $RECYCLE.BIN). Symbolic links, nested mounts and special files fail the scan; they are not silently followed. Explicit limits are 50,000 files, 10,000 directories and depth 32. Exceeding a limit fails, never succeeds with a truncated file list.
.Spotlight-V100
.Trashes
.fseventsd
.TemporaryItems
System Volume Information
$RECYCLE.BIN
Copies use 4 MiB buffers into exclusive private temporary files. The final commit never replaces an existing file. The App flushes writes, preserves source access/modification timestamps where supported, and hashes the final destination by reading it back. Existing files are reused only after complete source and target hashes match. Conflicting data is never overwritten. Case collisions on a destination filesystem therefore produce an error instead of losing a file.
Hard-link-capable targets use an atomic non-replacing file commit. Other filesystems use exclusive copy plus final readback; that commit may take longer to drain on pause. An interrupted conflicting commit is retained. Retrying a failed target uses a new output directory; the previous attempt remains available on disk. Previously verified targets are rechecked and reused. Resume restarts the unfinished file, not a byte offset inside it.
Output folders use the local date, source label and unique job identity. Original paths are kept inside Files/, separate from backup metadata, so source files cannot collide with the report. Each target receives .pexar-backup-report.json (format 2 with an explicit dataDirectory) with paths, sizes, SHA-256 digests, job identity and excluded directories. The plugin can export a job summary, source file list and recorded per-target digests using the App dialog. Durable App records store rules, a fixed source plan and append-only verified-file journal. App restart turns any incomplete active phase into interrupted; reinserting the same source does not automatically replay an unresolved job. Explicit resume removes only journal-proven orphan temporary files whose directory, inode and creation time still match; planned source filenames and unrelated files are preserved. Repeated insertions after a completed job create a new dated archive; verified files are reused when resuming the same job.
Files/
.pexar-backup-report.json
dataDirectory
interrupted
verified requires all files on all required targets to pass readback and reports/job results to persist. One verified target plus one failed target is not overall success. This proves the selected bytes matched during the check, not long-term medium health or permission to erase the original. There is no source deletion, forced ejection, automatic ejection, compression or bidirectional synchronization.
verified
CLI, standalone/Studio MCP and web demos use an in-memory backup fixture. They do not open dialogs, discover storage or copy user files. Live App I/O must be checked separately with authorized disks. Automated engine tests use real temporary files (including a 24 MiB clip), corruption, conflicts, Unicode/empty files, symlinks, cancellation and journal recovery. Native chooser UX, real Dock topology, Windows filesystem behavior and physical unplug/sleep endurance require platform/device checks.