1# Export iCloud data to Snow Globe
2
3Export **9 GB of Voice Memos first** inside the dedicated macOS VM, then
4trial optimized native Photos exports of **about 1.7 TB** to Snow Globe.
5These are the only requested categories. Keep original media, edited versions, and
6metadata in ordinary Windows-readable files, organized by year with mtimes
7set from recording dates. The remote friend supplies Apple sign-in and
8two-factor approval; the iPhone never needs to hold the whole library or
9connect to Clover's Mac by cable.
10
11The storage split is confirmed by the friend's iCloud storage screenshot.
12Apple sign-in, two-factor approval, and encrypted-data authorization are complete
13in the dedicated VM. Advanced Data Protection remains on. Unrelated app sync
14is disabled in this guest. The source iPhone reports **348 All Recordings,
151 favorite, and 2 Recently Deleted**.
16
17The Mac catalog contains 358 rows. On macOS 26, the native playable predicate
18`flags != nil AND flags & 6 != 0` recognizes **348 active recordings**, matching
19the phone, plus two deleted recordings. The native favorite count is one.
20Two active recordings are shorter than 0.1 seconds; duration filtering would
21exclude them and incorrectly include two stale catalog entries. Use the native
22predicate when selecting recordings, and preserve all 358 catalog rows.
23
24The macOS 15 cache exposed 161 audio files. A fresh macOS 26 import retrieved
25350 files totaling 9,612,921,523 bytes: 161 `.m4a` and 189 `.qta`, including the
26two deleted recordings. All 348 active recordings now have audio references.
27The complete host and native checks recovered **310 active recordings** passing full
28stereo decoding and catalog-duration checks. The remaining 38 older `.m4a`
29recordings comprise five empty files, 14 headers without a readable container,
30and 19 decodable files shorter than their catalog duration. Both independent
31native downloads retrieved the same legacy bytes. Keep these originals and
32their metadata; do not claim a complete export or delete cloud data.
33
34The `.qta` files contain stereo AAC alongside newer audio tracks. Native macOS
3526 validation checked every audio track without playback. Portable stereo
36`.m4a` copies can reuse the original AAC packets without re-encoding; retain
37the byte-identical `.qta` originals to preserve spatial/layer and other metadata.
38
39Three pilot files totaling 107,836,545 bytes passed source/host/NAS SHA-256,
40full decoding, duration reconciliation, and exact recording-time mtime checks.
41The macOS 15 local-file pass found 123 files passing full decoding and catalog
42and decoded duration checks; 19 decode but are shorter than their catalog
43duration, and 14 nonempty files contain headers without a `moov` atom. The
44five zero-byte files are excluded from the portable set. Failed and incomplete
45files remain in the native archive, with private per-record validation results.
46
47The public delivery root `/srv/clover/Share/iCloud Export - 2026-11-04`
48contains only `Voice Memos/<year>/...`: **310 validated recordings**, delivered
49as 310 Windows `.m4a` files and 187 original `.qta` files, totaling
5012,163,467,515 bytes. The first 123 recordings remain included. Pilot,
51Available, native databases, manifests, and helper folders are absent.
52The original `.qta` files preserve every track and embedded field. Their stereo
53copies preserve identical AAC packets without re-encoding. Both audio tracks
54of every active `.qta` passed native macOS 26 decoding: 187 recordings,
55374 tracks. Source/host/NAS hashes and recording-time mtimes match.
56
57Native files and metadata are outside the share at
58`/srv/clover/.icloud-export-private/2026-11-04`, behind a mode-0700 parent:
59
60- `Native initial snapshot`: 232 source/support files totaling 1,746,210,872
61 bytes, including a consistent SQLite backup with all 358 rows.
62- `Native macOS 26 snapshot`: 351 files totaling 9,615,002,291 bytes,
63 including all 350 media files and a consistent 358-row SQLite backup.
64- `Portable metadata`: complete recording index, original titles, source and
65 portable inventories, native validation results, and the recovery index.
66
67Both native databases pass `quick_check` on Mac and NAS. The existing
68password-protected read-only share URL is unchanged. Live HTTP tests verify
69an initial file, a new original and stereo copy, recording-time headers,
70range requests, and denial of writes and parent access. TAR downloads preserve
71whole-second recording mtimes and the `Voice Memos/<year>` layout. The friend
72has **not yet tested Windows playback or Date modified**.
73
74A separate protected recovery share at
75`/srv/clover/Share/iCloud Export Recovery - 2026-11-04` contains instructions
76identifying the 38 exceptions and an `Uploads` inbox. Its URL is in
77`private/recovery-share.json`; it uses the same password as the delivery share.
78Instruction names are generated mechanically for the friend and never printed.
79Uploads and authenticated downloads pass; deletion and parent access are denied.
80The friend checks the originals on the iPhone, exports available recordings as
81Rendered audio, and names each upload using the checklist's `recovery-NNN`
82identifier. The private recovery index maps that identifier to the original
83recording date, catalog duration, and title for later verification and replacement.
84The recovery share now also has `Partial recordings/<year>/...`: 19 untouched
85short originals and 28 reconstructed candidates covering the other 14 nonempty
86exceptions. Both 44.1 kHz and 48 kHz headers are retained for those 14 because
87the source header is missing. All 47 files pass decoding, NAS hash, mtime, and
88live HTTP checks; every reconstructed encoded packet occurs in its untouched
89source. These 33 logical partial recordings do not count toward the 310 complete
90recordings. Candidate audio rate still needs comparison with the original source.
91Never publish incomplete files as successfully recovered recordings.
92
93The audio sync worker was restarted in this guest after the native snapshot;
94counts and bytes remained unchanged. The normal share manager rolled back because its success-text check does not
95recognize Copyparty’s current reload response. A read-only password-protected
96link was instead created through Copyparty’s native HTTP API for the dated
97export root. Unauthenticated reads return 401; authenticated media hashes and
98HTTP mtimes match; range requests work; writes and parent access return 403.
99The URL and password-file path are in `private/export-share.json`. Evidence remains in the VM's restricted
100`evidence/*-nas-validation.json`; private per-file manifests are not operator
101readable output.
102
103## Privacy boundary
104
105Expose only basic metadata and aggregate integrity results: counts, byte
106sizes, dates, durations, and opaque identifiers. Do not display or listen to
107media, inspect transcripts or thumbnails, or reveal filenames, recording
108titles, GPS coordinates, or other location information in chat or operator
109logs. Keep media apps closed during authentication and exclude profile
110images and media windows from authentication captures.
111
112Automated workers may copy, hash, and validate files without exposing their
113contents. Preserve original bytes and all metadata, including location data,
114inside the friend's restricted archive; withholding metadata from the operator
115must not strip it from the export. Names and metadata may be handled
116mechanically inside private workers and manifests without returning their
117values. The friend performs any visual or listening review on Windows.
118These constraints take precedence over manual sample inspection below.
119
120## Agreed order
121
1221. Create a fresh macOS VM on this Mac, prove its console and guest control,
123 then sign into the friend's Apple Account and enable Voice Memos only.
124 A separate host macOS account remains an alternative if the VM pilot fails.
1252. Prove a small memo export, then download and reconcile the full 9 GB,
126 preserve native sources, and share the dated portable files from Snow Globe.
127 Check the result on the friend's Windows PC.
1283. Trial native Photos exports using the VM's existing Apple session.
129 Check originals, edits, companions, counts, dates, and cache space before
130 the full run. The web downloader requires separate authentication and
131 remains an alternative when the friend is available.
132
133## Capacity and cleanup
134
135Read-only measurements on 4 November 2026, in decimal GB and TB:
136
137| Storage | Used | Available | Allocation |
138| --- | ---: | ---: | --- |
139| Project | 567.5 GB | Shared below | APFS volume on the 2 TB WD Blue SN5000 |
140| Documents | 1183.3 GB | Shared below | Same APFS container as Project |
141| Project and Documents container | About 1751 GB | **249.1 GB total** | 2000.2 GB capacity; no volume quotas or reserves |
142| Mac startup container | About 895 GB | 99.2 GB | Separate 994.7 GB APFS container |
143| Snow Globe personal storage | — | About 7.79 TB | ZFS availability for `/srv/clover` |
144
145Project and Documents already share free space. Shrinking one APFS volume
146does not give the other more space; moving or deleting verified data frees
147their common pool. Neither volume currently has APFS snapshots. These are
148volumes on a physical disk, not sparse disk images that can be compacted.
149
150The **9 GB memo run needs no disk cleanup**. For the VM route, reserve about
151100 GB of the Documents container's available 249 GB for a 64 GB guest disk,
152the restore-image download, and transfer/scratch space. This is a planning
153budget from before installation. After the macOS 26 upgrade, backups, and
154full memo export, the shared container still has about **134.3 GB free**;
155no personal files were removed. A host-account fallback
156would instead use the startup disk's available 99 GB for the memo store.
157
158The current Photos route keeps an optimized local library and sends exported
159files to Snow Globe. It reuses the existing Apple login and supplies a native
160catalog for reconciliation. Original downloads temporarily consume guest and
161host disk space; the trial must establish a workable batch size and cache
162reclamation behavior.
163
164For a full Download Originals library, budget **about 1.85 TB free** in the shared
165Project/Documents container: 1.7 TB of photos plus an initial 150 GB allowance
166for databases, caches, and temporary files. That means freeing **about 1.60 TB
167more** against the pre-VM measurement above. A retained memo VM consumes space
168in this same pool, so add its actual allocation and remeasure before cleanup.
169The iCloud size is rounded and the allowance is a planning target. Export
170directly to Snow Globe to avoid a second full local media set.
171
172Any eventual cleanup must follow the recovery requirements in
173[AGENTS.md](../AGENTS.md). NAS space must then cover both relocated Clover
174data and the friend's export, including edited versions.
175
176## Dedicated VM route
177
178Apple supports iCloud in macOS VMs created using a macOS 15 or later restore
179image on a macOS 15 or later Apple silicon host. Upgrading a VM originally
180created with an older OS does not add this support. VM identities are tied
181to the host's Secure Enclave; moving a VM or running another clone can require
182reauthentication.
183[Apple's iCloud virtualization requirements](https://developer.apple.com/documentation/virtualization/using-icloud-with-macos-virtual-machines).
184
185This host runs macOS 15.7.5 and has 256 GiB RAM. Its existing Tart guest is
186the running `gui-agent`, exposed as `m3-devbox`. The installed
187Tart 2.41.1 supports fresh IPSW installation and a specified guest disk size.
188Apple's Sequoia license, section 2B(iii), permits two additional virtual macOS
189instances for the listed purposes, including personal noncommercial use.
190[macOS Sequoia license](https://www.apple.com/legal/sla/docs/macOSSequoia.pdf).
191
192The pilot has four vCPUs and 8 GiB RAM. Its initially 64 GB sparse disk has
193been enlarged to 128 GB for the macOS 26 compatibility test. It was created
194from Apple's macOS 15.6.1 restore image, build 24G90, with verified SHA-256
195`3d87686b691ac765eb6a6b3082b2334e2af9710096a00432dd519af89ff2ea78`.
196The Apple CDN URL and installation evidence are in its private `evidence`
197directory. The initial macOS 15.8.2 guest recognized only 161 of 348 as playable.
198The guest has now booted macOS 26.7.2 for the compatibility test, matching the
199phone’s iOS 26.6.1 generation.
200
201Reuse the installed signed Tart binary and the control approach documented
202in [the devbox runbook](mac-agent-vm.md), with a separate VM state directory
203under `/Volumes/Documents/VM/macOS Code Sandbox/icloud-export`. Its existing
204ancestor ACL protects this tree on Documents, where ownership is disabled.
205Keep its disk, credentials, and transfer directory there. Keep the devbox
206guest and its active work separate. A fresh install avoids copying devbox
207accounts, credentials, and workspace mounts, and establishes the required
208installation provenance; cloning is not categorically incompatible with iCloud.
209
210[Tart's fresh-install procedure](https://tart.run/quick-start/) begins with
211`tart create --from-ipsw IMAGE --disk-size 64 icloud-export`, followed by guest
212Setup Assistant. Use the isolated state directory for every command. Keep
213only a dedicated transfer folder available to the guest, then copy verified
214portable output to the NAS from the host.
215
216Console access, input, capture, guest storage, and the transfer path have been
217proved before Apple sign-in. The existing dashboard bridge selects `m3-devbox`
218specifically; it does not automatically control another guest. A dedicated
219guest console/control connection can run while Clover stays in the existing
220host login. This avoids creating or switching to another host account.
221The friend still provides Apple authentication and two-factor approval.
222Supported iCloud sign-in is a prerequisite; the pilot must also establish
223actual Voice Memos sync, complete audio downloads, and a verified export.
224
225### Resume this pilot
226
227The guest has been upgraded to macOS 26.7.2, matching the phone's iOS 26.6.1
228generation. It was cleanly shut down first. APFS clones of the stopped
229`disk.img`, `nvram.bin`, and `config.json` remain in `private/pre-tahoe`; all
23064 GB of the old disk passed byte comparison. Never run this backup
231concurrently or alter its VM identity.
232
233The guest disk is now 128 GB. Its Recovery partition was copied to the new
234end without changing partition identifiers; all 5,368,668,160 Recovery bytes
235passed hash verification, and both GPT copies pass CRC checks. Apple's
236`diskutil apfs resizeContainer` then expanded the guest system container,
237leaving about 97.8 GB free. No host partitions or devbox disks changed. A temporary Virtualization VNC
238server was closed before input because it listens on all host interfaces;
239normal runs remain headless with no host VNC listener.
240`evidence/pre-tahoe-backup.json` and `recovery-relocation.json` record these
241checks. Apple Software Update downloaded the 26.7.2 installer, and the in-place guest
242upgrade completed and the guest has booted macOS 26.7.2. The macOS 26 desktop is open. A one-boot automatic login bypassed unreliable
243Screen Sharing password entry, then its root cleanup job removed the setting,
244`/etc/kcpassword`, and its own plist. Automatic login is disabled; the guest now reports FileVault enabled. The local
245password, keychain, and Apple Account are unchanged. The one-boot setup helper
246was removed to prevent replay; evidence is `one-boot-login-validation.json`.
247`sysadminctl`'s prompted form returned error 22, so the temporary credential was
248written to its normal root-only file over stdin; no secret appeared in argv or
249logs. Executable signatures verify; the installer intentionally
250uses legacy resource omission rules rejected by a generic Gatekeeper app
251assessment. No security policy was changed. `startosinstall` uses the guest
252local volume-owner password over stdin, never command arguments. The completed login is verified by console UID 501, the login-done flag, and
253Finder/Dock processes; a GUI launchd domain alone does not establish login. The
254lock-state guard uses pinned guest SSH because the login-session Tart agent
255is unavailable before console login.
256
257All machine-specific state is under
258`/Volumes/Documents/VM/macOS Code Sandbox/icloud-export`. `state` is its
259isolated Tart home; the VM name is `icloud-export`. A symlink in
260`~/.tart/vms/icloud-export` names this same guest. The local guest account is
261`admin`; its generated password and separate SSH key remain in `private`.
262The friend's Apple credentials belong only in `private/apple-account.json`,
263with fields `apple_account` and `password`. The guest does not
264mount that directory.
265
266`private/run-vm.py` runs only this guest. Launch it detached through the
267existing localhost SSH route so it survives the controlling shell. It mounts
268`transfer/tooling` read-only and `transfer/output` read/write. The guest sees
269these as `/Volumes/My Shared Files/tooling` and `output`. Host paths outside
270these two directories are not shared with it.
271
272`private/vm-ui.py` takes JSON on stdin for guest screenshots and input.
273It uses vncdotool 1.3.0's Apple Screen Sharing authentication over SSH, with
274a guest-specific key and pinned host key. Its Unix viewer
275socket stays inside `private`. The physical Mac can remain locked. The
276temporary Tart installer VNC listener is stopped, its credentials are removed,
277and normal pilot starts omit `--vnc-experimental`. The temporary legacy VNC
278password was also disabled and removed; the console uses the local account.
279
280Native Screen Sharing maps `super` to Command. Its `clear` operation uses
281Command–A then Backspace; individual character events are paced. A public
282test containing upper/lowercase letters, underscore, hyphen, plus, and an
283email address was reproduced exactly. The sign-in field and guest clipboard
284were cleared after the check. Guest login and console reconnection passed
285after the OS update and the final VM restart. Automatic login remains disabled. The native console
286controller is now closed; the headless guest desktop remains active and SSH
287metadata access remains available. No host VNC listener is enabled.
288
289For guest commands, use the installed Tart binary with
290`TART_HOME="/Volumes/Documents/VM/macOS Code Sandbox/icloud-export/state"`
291and `exec icloud-export COMMAND`. The guest agent runs only its command RPC;
292clipboard integration is off. SSH offers a second command route and supplies
293the private screen-sharing tunnel. Never point the existing devbox installer
294or its lifecycle commands at this pilot.
295
296The synthetic transfer fixture was removed after passing its hash and mtime
297checks. Pilot evidence is in `evidence/pilot-nas-validation.json`.
298
299The iPhone passcode file was deleted after successful authorization. Never
300reset encrypted iCloud data. Read credentials only inside the input worker;
301never print or display their files. Authentication captures use restricted
302regions and mask inputs before writing images. Never capture a media window.
303
304`private/vm-ui.py --stream` maintains one guest console connection across JSON
305lines. Do not infer the guest lock state from the VNC connection status. Verify
306it through `ioreg`; automatic login remains disabled. Controller
307capture defaults to false. A menubar-only crop can verify the active app
308without exposing recording names. Start the controller PTY with `stty -icanon -echo`; macOS canonical input
309truncates long JSON lines. Counted Up/Down steps are supported, and counted
310Backspace requires the locked-guest guard. Explicit paced Shift combinations
311handle the US keyboard layout without exposing credentials.
312
313Voice Memos' migrated local store was preserved intact at guest
314`/Users/admin/iCloudExportRecovery/Recordings-before-refetch`. A fresh
315`Recordings` store has imported all 358 catalog rows. Its first stable pass
316retrieved 103 media paths, including 18 `.qta` recordings absent from the
317macOS 15 store. This changes only the local cache, not iCloud records.
318The fresh assets require native decoding/export for formats unsupported by the
319host FFmpeg; a decode failure alone does not establish source corruption.
320Launch GUI apps through the guest agent in the completed desktop session.
321OSLaunchdErrorDomain 125 was observed before console login completed.
322Keep all credential input on stdin. The optional post-upgrade assistant was
323closed without approving extra cloud services.
324
325`private/memo-export.py` reports aggregate status without arguments; `recovered`
326copies and validates stable files from the current native store. Selection uses
327the native playable predicate, including sub-0.1-second recordings. Existing
328validation is reused only for identical hashes, recording times, and catalog
329durations. Initial `pilot` and `available` inventories are historical evidence.
330`native-audio-check.py` validates every QTA audio track with the native decoder;
331PCM scratch is discarded after checking frame counts and duration.
332`build-portable.py` preserves original media and builds packet-identical stereo
333copies. `publish-macOS26.py` has completed its sealed native snapshot publication;
334do not replay it against the existing native destination. Future updates must
335preserve the flat public layout and private recovery material. Report 310 of
336348 complete recordings until the remaining 38 reconcile.
337
338### Photos without another Apple login
339
340The friend is unavailable for another verification code. The separate web-login
341worker has stopped, its pending request was denied in the VM, and its unused
342NAS password copy and cookies were removed. No additional code was requested.
343Use Photos in the already signed-in VM with Optimize Mac Storage, exporting
344requested originals and edits in batches through native Photos/PhotoKit or
345OSXPhotos.
346Photos is now enabled in that same Apple session and has begun importing its
347catalog. Optimize Mac Storage is selected and independently verified through
348its native settings control. Keep the library on the guest's local APFS disk
349and send exported files to Snow Globe. Apple advises against putting a Photos
350library on a network share.
351
352The catalog holds 38,142 assets: 37,804 visible (1,823,889,190,154 original
353bytes; 4,544 videos, 1,348 edited, 363 Live Photos), 303 hidden burst members,
354and 35 in Recently Deleted. No shared albums exist. OSXPhotos 0.78.0 runs in the
355guest from `~/.local/bin` (installed with a checksum-verified uv 0.9.7).
356
357PhotoKit needs Photos access from a responsible app with a usage string; CLI
358processes under SSH or Terminal are refused or time out before the prompt can be
359answered. `transfer/tooling/PhotoExport.app` is an ad-hoc-signed launcher
360(`net.paperclover.icloud-export.photos`) that spawns its arguments, and holds
361full Photos access in the guest. Terminal also received access while this was
362diagnosed. Prompts are `UserNotificationCenter` alerts; answer them with
363`run_steps` by button name, never with screenshots.
364
365Guest `~/PhotoExport` holds the private inventory, 110 date-ordered UUID batches
366(about 15 GB each; `b0000` is a 30-asset pilot), and per-batch logs, reports,
367and export databases. `driver.py` (from `private/photos-driver.py`), started by
368`open -n ~/Applications/PhotoExport.app --args /bin/sh ~/PhotoExport/run.command`,
369exports each batch with `--download-missing --use-photokit`, year directories,
370`{date}_{uuid}` names, XMP sidecars, and `--touch-file`, then repeats it once
371with `--update`. It keeps at most one unshipped batch and pauses below 25 GB
372free; `~/PhotoExport/STOP` halts it between batches. On the host,
373`private/photos-ship.py` streams each finished batch to Snow Globe, verifying
374every file's size, SHA-256, and mtime. Media goes to `Photos/<year>` in the
375delivery share; sidecars, reports, and export databases go to the private
376`Photos metadata/<batch>`. Only then is guest staging deleted. Logs:
377`evidence/photos-ship.log` and guest `driver.log`.
378
379The pilot exported 223 files (30 assets and their burst members) with no
380missing or failed items, and passed mtime, year-folder, and file-signature
381checks before shipping.
382
383Downloaded originals stay in the Photos cache until space pressure. In this
384guest the per-user `deleted` (CacheDelete) agent had a stale volume object
385("unable to validate volume"), so nothing was purgeable and Photos never evicted,
386even at 3 GB free. Killing that agent, then quitting and reopening Photos, made
387the cache purgeable; pressure at about 6 GB free then evicted 9.5 GB within
388seconds. Before each batch below 40 GB free, the driver preallocates a temporary
389balloon down to 6 GB, waits 30 s, and deletes it. If purges stop freeing space,
390check `NSURLVolumeAvailableCapacityForImportantUsageKey` and the `deleted` log first.
391
392A full local download of the 1.7 TB is not a prerequisite for this optimized
393route. Originals are temporarily downloaded by Photos as exports request them;
394Photos manages eviction. Cache reclamation is asynchronous, so verify bounded
395space use in a trial, monitor free space, and pause before exhausting the guest
396or host disk. Do not use OSXPhotos `--cleanup` to evict cloud originals: it
397removes files from the export destination.
398[Apple Photos and iCloud](https://support.apple.com/en-euro/guide/photos/phtf5e48489c/mac) ·
399[OSXPhotos maintainer on optimized storage](https://github.com/RhetTbull/osxphotos/discussions/1926) ·
400[Apple library-storage requirements](https://support.apple.com/en-us/108345).
401
402The alternative web downloader remains installed privately on Snow Globe:
403upstream `icloudpd` 1.33.0 at
404`/srv/clover/.icloud-export-private/2026-11-04/tools/icloudpd-1.33.0`, pinned to
405commit `3caeae584c3d8bc6fcc51a1c9f7e5413b1422fd3`. It requires its own Apple web
406session. Keep its cookies and credentials private; leave ADP enabled. It is
407not the current route while the friend cannot supply another code.
408
409### Remaining memo recovery checks
410
411The cached CloudKit records use LZFSE/LZVN compression. After decompression,
412all 38 exception assets' recorded sizes match the local files, including the
413five empty files. Their latest cloud modification predates this export:
41424 February 2026. Each has one audio-future generation in the cached index.
415No additional Voice Memos audio was found in its app/group stores. Native Core
416Audio decoding of all 33 nonempty exceptions recovers 19 short streams but
417none of the full catalog durations; the other 14 fail native decoding too.
418Some short files contain additional `mdat`/`moof` fragments, retained for repair
419experiments. The audio was never uploaded. The 38 cloud assets hold 1,221,488 bytes
420for 9.7 catalog hours, and each record's own local duration is 0–22 seconds,
421whereas healthy recordings match their catalog duration. No Mac-side or iCloud
422copy can supply the rest; only the iPhone (or a local backup of it) can, if its
423copy is complete. A normal app export has now been attempted for all 38: all 19 short files
424remain short, 18 supply no audio, and one empty item cannot be copied through
425the UI. Repair with a pinned build of `anthwlock/untrunc` produced decodable
426fragments for all 14 header-only files (16.831 seconds across their longest
427candidates), but no full catalog durations. The original 19 short files remain
428better than their reconstructed variants and are retained untouched.
429Evidence is `recovery-cloud-metadata-validation.json`, with private atom,
430packet, and native-decoder inventories. Never display media, names, or locations.
431
432## What each person does
433
434Once the export login is controllable, the agent can configure the export,
435oversee sync and retries, read the authorized memo database, restore names
436and dates, verify files, and manage the restricted NAS delivery.
437
438Guest installation and its local account can be prepared from Clover's
439existing host session. The separate host-account alternative requires Clover
440to authenticate account creation: the host shell runs as `clo` without
441passwordless sudo.
442
443The friend keeps the subscription active, enters Apple credentials and any
444encrypted-data authentication, approves two-factor requests on the iPhone,
445checks source counts, and tests Windows playback. Remote sign-in needs both
446credentials and two-factor approval; approving a notification is insufficient
447on its own.
448
449Current Cua Driver checks pass for Accessibility, Screen Recording permission,
450AX access, and the WindowServer connection in Clover's login. The locked host
451desktop refused GUI control; the pilot's independent guest console works.
452For the host-account alternative, first login and
453the GUI controller's access must be established in that login, including any
454per-user permissions. Keep the existing Knife session available in Clover's
455account. A host account switch must not log it out.
456These setup and authentication steps can be done through a trusted remote
457connection while the Mac is powered on and reachable; they do not inherently
458require a visit to the machine.
459
460Use the restricted credential file or a private remote-control session into
461the export VM for password entry. Device-passcode entry and two-factor
462approval may still require the friend. Credentials, recovery keys, and verification codes stay out of
463chat, shell arguments, repository files, and export logs. The temporary Mac
464becomes an authorized device with access to the account; the friend should
465understand that before signing in.
466
467## Before downloading
468
4691. Confirm the friend's iOS version and whether Advanced Data Protection is
470 enabled. The requested storage split is 9 GB of memos and about 1.7 TB of
471 Photos; other account categories are outside the export.
4722. Record Photos' photo/video counts with filters cleared. Inventory Hidden,
473 personal and Shared Photo Libraries, Shared Albums, bursts, RAW pairs,
474 edited media, and anything wanted from Recently Deleted. Do the same for
475 Voice Memos, including custom folders and Recently Deleted. Do not restore
476 deleted items without the friend's choice.
4773. Confirm both Photos and Voice Memos are enabled in iCloud on the iPhone
478 and have finished uploading. Phone-only items cannot be fetched from
479 iCloud. Resolve upload errors on the source first.
4804. Agree how future photos and recordings will be protected after migration.
481 A one-time export does not upload tomorrow's recordings.
482
483## Host account alternative
484
485Use a new standard user dedicated to this export, with its normal home under
486`/Users` on the startup disk. The 9 GB memo store does not justify a custom
487home directory or another APFS volume. Clover authenticates account creation
488through the Mac's administrator prompt; do not put passwords in command
489arguments. Test first login and the account's GUI control before sign-in.
490
491Sign into the friend's Apple Account in that user, leaving Clover's normal
492account signed in separately. Review the iCloud app switches during setup and
493enable Voice Memos only. Keep Photos and Drive sync off for this phase. Leave
494Find My, Passwords and Keychain, Messages, and purchase-account sign-in out
495of this setup. Decline merging unrelated local data.
496
497Only for the native Photos fallback, create the friend's Photos library in
498a private folder on the existing Project/Documents APFS disk after freeing
499space. Make it that user's System Photo Library, enable iCloud Photos, and
500select **Download Originals to this Mac**. Keep the Mac powered, awake, and
501connected during downloads. Do not put the live `.photoslibrary` on the NAS:
502Apple requires appropriate local Mac-formatted storage and warns against
503network storage for live libraries.
504[Apple's library storage requirements](https://support.apple.com/en-us/108345).
505
506A cable import would require the iCloud originals to be downloaded onto the
507iPhone first. It is therefore unsuitable for this 1.7 TB photo library; a cable
508copy does not inherently mean all embedded camera metadata is lost.
509[Apple's PC import requirements](https://support.apple.com/en-us/120267).
510
511Layered Voice Memos require at least macOS 15.2. The initial macOS 15 guest
512proved insufficient for this catalog; the phone runs iOS 26.6.1, and a macOS 26
513compatibility test is underway.
514[Apple's Voice Memos playback requirements](https://support.apple.com/en-euro/guide/voice-memos/vma2c8c0a040/mac).
515
516## Prove a small export first
517
518For the memo pilot, test ordinary, renamed, trimmed, long, and layered
519recordings where present. Include a recording close to New Year or a timezone
520boundary.
521
522For the subsequent Photos trial, test an old and a new photo, duplicate
523original filenames, an edited picture, a Live Photo, a video, a burst, a RAW
524pair if present, a hidden item, and a date corrected in Photos.
525
526The friend opens the pilot on Windows and checks appearance, sound, edits,
527duration, filenames, and dates. An original plus its edited rendition are two
528intentional versions. A Live Photo's image and video must both survive.
529Full-resolution originals and all companions must exist; thumbnails and a
530matching item count are insufficient.
531
532## Native Photos fallback
533
534Use [OSXPhotos](https://rhettbull.github.io/osxphotos/index.html) to export the
535downloaded library. Its year and UUID templates give ordinary directories
536without filename collisions. Keep original names and album membership in
537metadata rather than duplicating media into every album.
538[Template reference](https://rhettbull.github.io/osxphotos/template_help.html).
539
540Run the export as the operator with read access to the friend's downloaded
541library and write access to the destination. Using Clover's operator account
542for this phase keeps NAS credentials outside the temporary Apple login.
543Grant access only to the agreed source tree; macOS privacy permissions may
544also be required. Always pass the explicit library path. Do not let the tool
545fall back to Clover's own Photos library.
546
547Example paths below are placeholders. Confirm the NAS mount and its backing
548host before creating the destination. Keep export state on the Mac; only
549validated portable media belongs in the public share. Keep catalog metadata
550and native recovery files in restricted staging outside it.
551
552```sh
553uv tool install 'osxphotos==0.78.0'
554
555LIBRARY='/Volumes/Documents/iCloud Export/Photos Library.photoslibrary'
556WORK="$HOME/Library/Application Support/iCloud Export"
557mkdir -p "$WORK/photo-staging"
558chmod 700 "$WORK"
559
560osxphotos info --library "$LIBRARY" --json > "$WORK/photos-info.json"
561osxphotos query --library "$LIBRARY" --json > "$WORK/photos.json"
562
563osxphotos export "$WORK/photo-staging" \
564 --library "$LIBRARY" \
565 --directory '{created.year}' \
566 --filename '{created.strftime,%Y-%m-%d_%H%M%S}_{uuid}' \
567 --touch-file \
568 --sidecar xmp \
569 --keyword-template '{folder_album(>)}' \
570 --exportdb "$WORK/photos-export.db" \
571 --update \
572 --report "$WORK/photos-export.csv"
573```
574
575Capture dry-run and tool diagnostics privately; return only aggregate progress
576and integrity results. Never display private paths or media metadata. Add
577`--limit 30` for a pilot, then remove the limit for the full export. Retain the
578export database and options for retries and the final update. Keep dated
579copies of reports before subsequent runs replace them. Defaults export
580originals, edited versions, Live Photo videos, burst members, and associated
581RAW images; edited files receive an `_edited` suffix. `--touch-file` sets the
582media mtime from the Photos date. Do not enable overwrite or cleanup options.
583[Export command reference](https://rhettbull.github.io/osxphotos/cli).
584
585Wait for full hydration and inspect missing/error reports. For exceptions,
586OSXPhotos has `--download-missing`, but its documentation says this does not
587retrieve every burst member. Resolve every missing companion explicitly.
588For network exports, a local export database avoids putting its SQLite writes
589on SMB. XMP sidecars preserve catalog metadata without rewriting original
590media bytes; the JSON inventory keeps the broader catalog information. Retain
591these sidecars and inventories outside the public media-only share.
592[Export and metadata tutorial](https://rhettbull.github.io/osxphotos/tutorial.html).
593
594Apple's built-in fallback is **File → Export → Export Unmodified Original**
595with **Export IPTC as XMP**, plus a separate export of edited versions. A Live
596Photo exports as an image and a video. This fallback still needs inventory
597matching and timestamp correction for the proposed layout.
598[Apple's export procedure](https://support.apple.com/en-gb/guide/photos/pht6e157c5f/mac).
599
600## Export Voice Memos
601
602The database contains metadata; audio lives in separate files. Enable Voice
603Memos sync in the temporary user, open the app, and reconcile its recordings
604with the iPhone. A listed recording is not proof its audio is downloaded.
605[Apple's sync procedure](https://support.apple.com/en-ie/guide/voice-memos/vma6cc4d0571/mac).
606
607The current common store is:
608
609```text
610~/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings/
611 CloudRecordings.db
612 CloudRecordings.db-wal when present
613 CloudRecordings.db-shm when present
614 media and supporting files
615```
616
617Preserve a private copy of the entire native store, including editing and
618supporting files. Use SQLite's backup API through a read-only source connection
619to obtain a consistent database snapshot including committed WAL data. Copying
620only the live `.db`, or opening it with `immutable=1`, can miss recent changes.
621Quiesce app edits during the copy and reconcile again afterward.
622[SQLite's backup API](https://www.sqlite.org/backup.html).
623
624Inspect the copied schema before implementing extraction. Published exporters
625use `ZCLOUDRECORDING`, `ZUNIQUEID`, `ZPATH`, `ZDATE`, and `ZDURATION`; one
626documents `ZEVICTIONDATE` for deleted state. These are reverse-engineered
627details, so verify their meaning against this account's app views. Titles can
628occupy different fields; preserve them mechanically in private metadata without
629displaying them. Native `.m4a` and `.qta` files both occur.
630[Exporter schema and SQLite handling](https://github.com/grapeot/voice-memos-skill/blob/master/docs/rfc.md).
631
632The extraction contract is:
633
634```text
635for each wanted logical recording in the database:
636 require a local, nonempty, decodable media file
637 reconcile duration, active/deleted state, and recording ID
638 preserve the original title privately without operator inspection
639 recording instant = ZDATE + 978307200 seconds since Unix epoch
640 copy native media without changing its bytes
641 export a rendered copy when edits/layers/effects need rendering
642 name portable output YYYY-MM-DD_HHMMSSZ_unique-id.ext
643 set mtime from the recording instant
644 record ID, full title, date, duration, folder, variant, and output path
645```
646
647The epoch conversion applies only after confirming `ZDATE` uses Apple's 2001
648epoch in this store. Use UTC for memo filenames and year folders if historical
649recording timezones are unavailable; preserve any known timezone separately.
650Opaque UUID filenames avoid Windows-invalid characters and private titles or
651locations in paths. Preserve full titles privately. Do not merge duplicate
652titles or infer dates from download times.
653
654An ordinary native M4A is suitable when its playback matches the app. Compare
655trimmed recordings too: raw file copying alone must not silently discard edits.
656For special recordings, export both the native editable source and a rendered
657M4A. Apple documents rendered sharing as mixing effects and layers into one
658file. The remote friend can select recordings on their iPhone, choose **Share
659→ Options → Rendered**, save a manageable batch locally, and upload it through
660a temporary folder-scoped HTTPS upload link. Export editable versions too when
661the source is not already preserved on the Mac. No physical proximity is
662needed; do not ask the phone to download the entire photo library.
663[Apple's multiple-recording sharing options](https://support.apple.com/en-mt/guide/iphone/iph3d6dc359/ios).
664
665Match these uploads to the database inventory before renaming or assigning
666dates; resolve duplicate titles explicitly. Export existing transcriptions as
667text when wanted, and retain their native source. Do not generate replacement
668transcripts as part of copying recordings.
669
670## Windows files and dates
671
672The agreed public layout contains media only. Photos is added after its trial:
673
674```text
675iCloud Export - 2026-11-04/
676 Voice Memos/
677 2025/
678 2025-06-12_212233Z_<id>.m4a
679 2026/
680 2026-06-12_212233Z_<id>.m4a
681 2026-06-12_212233Z_<id>.qta
682 Photos/
683 2024/
684 2024-06-12_142233_<uuid>.heic
685 2024-06-12_142233_<uuid>.mov
686 2024-06-12_142233_<uuid>_edited.jpeg
687```
688
689Native sources, catalog snapshots, names, album mappings, sidecars, validation
690manifests, and recovery tools stay outside the shared root. No Pilot, Available,
691Metadata, native-store, or tool folders belong in the public delivery.
692
693Preserve HEIC, JPEG, RAW, MOV, MP4, and native audio formats. HEIC/HEVC playback
694depends on the Windows apps and installed codecs; test the actual PC.
695[Microsoft's HEIF and HEVC guidance](https://support.microsoft.com/en-us/onedrive/upload-heif-and-hevc-photos-and-videos-to-onedrive).
696For audio and video, [VLC](https://www.videolan.org/vlc/features.html) is a
697useful pilot player. If needed, add separate JPEG or H.264 viewing copies with
698the same asset IDs and dates. Preserve the originals; JPEG, stereo mixes,
699and video transcodes do not retain every RAW, HDR, depth, or spatial property.
700Measure derivative space before converting a whole library.
701
702Use the Photos catalog's creation date and timezone for photo folders and
703mtime, including dates the friend corrected in Photos. Preserve the original
704embedded EXIF even when it disagrees; XMP and the inventory carry catalog
705corrections. Mtime is a UTC instant, while Windows displays it in the viewer's
706timezone. Windows Date created is a separate field and may reflect download
707time. Other documents retain their actual modification dates.
708
709In the restricted recovery store, create a manifest record for every delivered
710file with `relative_path`,
711`bytes`, `sha256`, and `mtime_utc` as ISO 8601 with an explicit UTC offset.
712Link media to logical IDs and variant roles in the inventories. Exclude the
713manifest itself from its own listing. Keep paths relative and check case
714collisions and Windows path limits. Generate and verify the manifest only
715after files and metadata are final.
716
717The public share’s TAR download preserves UTC recording timestamps to whole
718seconds in both archive metadata and a real extraction test. Its URL is the normal share URL
719plus `Voice%20Memos/?tar`; the archive contains `Voice Memos/<year>/...` only.
720Copyparty’s generated ZIP carries UTC DOS dates and a legacy Unix extra field
721that the tested extractor did not honor, shifting extracted mtimes. Use TAR
722for the handoff and have the friend verify the resulting Windows dates.
723Private evidence: `evidence/tar-time-validation.json`.
724
725Individual browser downloads may reset filesystem timestamps. Prefer the
726verified TAR route and check the friend's actual Windows extraction. Downloads
727should use manageable batches or individual-file range requests when necessary.
728
729## Snow Globe sharing
730
731Place portable output under `/srv/clover/Share/iCloud Export - 2026-11-04`, visible
732as `/Volumes/clover/Share/iCloud Export - 2026-11-04` on this Mac. Use the existing
733[Shares manager and Copyparty](copyparty.md), with a password and read-only
734permission scoped to that folder. Keep native app databases, credentials, and
735temporary writable uploads outside the read-only delivery link. Retain existing
736numeric owners; do not recursively change ownership of Clover's files.
737
738Create the delivery link after validation. Test its access from a signed-out
739client, including denial of parent and sibling folders, a large download,
740resume behavior, and the Windows timestamp procedure. For remote uploads of
741exceptional memos, use a separate restricted upload folder and revoke that
742access after reconciliation. This uses existing services and needs no new
743permanent iCloud container.
744
745## Direct Photos trial
746
747[The linked project](https://github.com/boredazfcuk/docker-icloudpd) wraps
748`icloudpd` in an Alpine container, adding scheduled downloads, credential and
749session storage, notifications, and optional conversions. Its scope is Photos
750and videos, including Live Photo components; it does not export Voice Memos
751or the whole account.
752
753Its README still says ADP must be disabled. In contrast, current upstream
754`icloudpd` documents `--adp-web-access`, introduced in 1.33.0, with approval
755from a trusted device and iCloud web access enabled. This is an upstream
756capability, not proof the wrapper image supports that option. Use a pinned
757version and prove the actual account flow; the plan does not require disabling
758ADP.
759[Upstream authentication documentation](https://icloud-photos-downloader.github.io/icloud_photos_downloader/authentication.html).
760
761For a direct-to-NAS pilot, run upstream in one-time copy mode with private
762authentication state. Retrieve original and adjusted assets, RAW alternatives,
763and Live Photo components from every wanted library; enumerate Shared Albums
764separately. Reconcile asset IDs and all variants. Shared Albums can contain
765reduced-resolution copies; obtain originals from their owner where needed.
766Regular album membership is not a reason to store the same original repeatedly.
767[Upstream features and modes](https://github.com/icloud-photos-downloader/icloud_photos_downloader).
768
769With upstream **1.33.0**, pass these trial options to the parser inside the
770private worker. Account fields come from the restricted file into process memory;
771keep credentials out of OS command arguments and keep all tool output private.
772The sample and sidecars stay outside the delivery share until verified.
773`--recent 30` is only for the trial; remove it for the full run and final
774reconciliation. Repeat for each library returned by `--list-libraries`, with a
775distinct destination per library.
776
777```sh
778--adp-web-access \
779 --cookie-directory '/srv/clover/.icloud-export-private/2026-11-04/photos-session' \
780 --directory '/srv/clover/.icloud-export-private/2026-11-04/Photos trial' \
781 --folder-structure '{:%Y}' \
782 --file-match-policy name-id7 \
783 --live-photo-mov-filename-policy original \
784 --size original --size adjusted --size alternative \
785 --live-photo-size original \
786 --xmp-sidecar \
787 --log-level error \
788 --recent 30
789```
790
791The repeated sizes request originals and available edits/RAW alternatives.
792The ID naming policy distinguishes repeated original filenames. Verify all
793IDs and variants, reported creation instants, mtimes, XMP contents, and year
794boundaries before accepting this route. Preserve the downloaded names unless
795the inventory supplies an unambiguous mapping to a new layout.
796[Asset sizes](https://icloud-photos-downloader.github.io/icloud_photos_downloader/size.html) ·
797[File naming](https://icloud-photos-downloader.github.io/icloud_photos_downloader/naming.html) ·
798[Command reference](https://icloud-photos-downloader.github.io/icloud_photos_downloader/reference.html).
799
800Keep cloud-deleting and local-mirroring features disabled: `auto_delete`,
801`delete_after_download`, `keep_icloud_recent_only`, and `delete_accompanying`;
802leave `keep_icloud_recent_days` unset. The wrapper configuration warns about
803filename collisions with flat or year-only download directories. Upstream
804documents automatic name de-duplication, so verify the pinned behavior with
805duplicate names instead of assuming either statement describes every build.
806Normalize to the final year/ID layout only after inventory reconciliation.
807Do not rewrite EXIF on archived originals.
808[Wrapper configuration](https://github.com/boredazfcuk/docker-icloudpd/blob/master/CONFIGURATION.md).
809
810## Finish before canceling
811
8121. Reconcile every wanted logical item and its expected files, including edits,
813 RAW pairs, bursts, Live Photos, hidden items, shared content, and special
814 recordings. Resolve all missing, empty, corrupt, and failed exports.
8152. Probe all audio/video files and decode-check images; inspect representative
816 playback on Windows, including long videos and trimmed or layered memos.
817 Have the friend compare their important items with the source app.
8183. Verify every delivered file's size and SHA-256 on Snow Globe and on the
819 friend's Windows copy. Check all media mtimes against the inventories,
820 allowing only the destination filesystem's timestamp precision.
8214. Take a final incremental pass after a short pause in new recordings and
822 edits, then reconcile new items and regenerate manifests. Keep the native
823 Mac stores until handoff succeeds.
8245. Establish independently verified copies on separate devices before cloud
825 deletion. With the native route, retain the Mac source, NAS delivery, and
826 friend's Windows copy through the deletion. ZFS redundancy is not another
827 copy, and this repository does not configure automatic snapshot retention.
828 Before destructive storage cleanup, satisfy [AGENTS.md](../AGENTS.md):
829 verify application/data recovery and any needed keys from two restricted
830 off-server copies stored separately. Apply this to relocated Clover data
831 too; do not count an unverified NAS move as permission to erase its source.
8326. The friend chooses when to stop syncing, remove cloud content, and downgrade.
833 Confirm remaining use fits the chosen plan and that future backups have a
834 destination. Never use the downloader to delete automatically during export.
835 The screenshot also shows 35.7 GB of backups; exporting the two media
836 categories does not by itself make the account fit the free 5 GB tier.
8377. Sign out inside the export VM or fallback host account. Remove the exact
838 export device from the friend's trusted devices and revoke downloader
839 sessions and temporary upload access. Remove the export VM or temporary
840 host account and native stores after the verified handoff and the recovery
841 requirements above are satisfied.
842
843**Deleting synced media can delete it on the friend's other devices.** Apple
844also warns that exceeding the downgraded capacity stops iCloud updates and
845backups. Keep cancellation and cloud cleanup after verification.
846[Synced deletion behavior](https://support.apple.com/en-us/108922) ·
847[Downgrade consequences](https://support.apple.com/en-us/108318).
848
849## Planning verification
850
851The Mac version, physical disks, APFS allocation, volume quotas/reserves,
852snapshot lists, and Snow Globe ZFS availability were read without opening
853personal content. OSXPhotos 0.78.0 was run in an isolated temporary tool
854environment for `export --help`, `query --help`, and `info --help`; the flags
855above exist in that build. Upstream icloudpd 1.33.0 was also checked with
856`--help` in isolation, including ADP, asset-size, naming, and XMP options.
857The current Cua Driver is 0.38.0; its status and read-only health checks pass
858in Clover's login. Passwordless host sudo is unavailable. The devbox was
859observed running with Tart 2.41.1; no lifecycle action was taken on it.
860Apple's iCloud requirements and license were checked for the VM route.
861The dedicated guest has passed command, screen capture/input, read-only
862tooling mount, writable transfer, AAC decode, and NAS hash/mtime checks.
863Apple sign-in, native sync, the friend's memo schema, and NAS byte/timestamp
864checks have passed. Full library reconciliation and the friend's Windows
865playback/date check remain required; Clover reports the Windows test has not
866yet been performed.