magnus919_agent-skills/systematic-debugging/references/macos-sandbox-debug-example.md

Worked Example: Apple Books.app Import Pipeline (macOS)

Demonstrates the "macOS App Troubleshooting" and "Research Before Guessing" patterns (Phase 1 steps 6a/6b).

The Symptom

Importing EPUBs into Apple Books fails silently. Three failure modes:

1. Silent drag-and-drop — file lands in app, nothing happens
2. Double-click in Finder — focus shifts to Books, but import never starts
3. File → Open dialog — selecting a file does nothing

No error dialogs. No crash reports. Books stays open and responsive.

Investigation Path

Phase 1 — Evidence Gathering

1. Check the database (BKLibrary)

The main library database is at:

~/Library/Containers/com.apple.iBooksX/Data/Documents/BKLibrary/BKLibrary-1-091020131601.sqlite

The ZBKLIBRARYASSET table tracks all books. Key columns:

• ZSTATE — 3=local file exists, 5=cloud-only
• ZCONTENTTYPE — 1=ebook, 5=book store, 6=audiobook/other
• ZPATH — full path to local file in BKAgentService container
• ZASSETID / ZSTOREID — Apple Store identifiers

2. Check the XPC service (BKAgentService)

File storage lives in:

~/Library/Containers/com.apple.BKAgentService/Data/Documents/iBooks/Books/

Books are stored as unzipped directory bundles (.epub extension on a directory, containing META-INF/, OEBPS/, and mimetype). Apple's Books app unzips EPUBs on import and stores the raw directory structure. This means standard EPUB tools (Calibre, etc.) cannot directly read from this storage — the files must be re-zipped with mimetype as the first entry.

3. Check the import queue

~/Library/Containers/com.apple.iBooksX/Data/Library/Caches/Inbox/

Files that have been draggged or opened but not yet processed appear here. Files can get stuck indefinitely.

4. Read the system logs

log show --predicate 'process == "Books"' --last 30m --style compact

The critical error:

BKResolveAssetForImportOperation: Unable to access url
BKResolveAssetForImportOperation: User cancelled import of cloud asset.
importBookFromURL: BKResolveAssetForImportOperation failed.

The "User cancelled" message is misleading — it's the app's internal interpretation of an NSFileCoordinator claim failure (Code=3072 "The operation was cancelled"), likely caused by a sandbox permission issue or XPC service state corruption.

5. Check for container migration artifacts

A Data.old/ directory inside the BKAgentService container indicates a failed sandbox container migration during a macOS update:

~/Library/Containers/com.apple.BKAgentService/Data.old/

This can contain old book files and plists from a previous container version, creating orphaned state.

The Root Cause

The user had deleted EPUB files from the Books local storage folder to free disk space. This broke the concordance between the CoreData database (which tracks book metadata) and the actual file store. Two layers of corruption resulted:

1. Database inconsistency — entries had ZSTATE=3 (local file exists) but the file was gone
2. Container migration ghost — Data.old/ from an OS update left orphaned files
3. XPC service degradation — BKAgentService would process exactly one import after restart, then silently stop

Solutions Tested

What worked (partially):

• Container deletion (rm -rf ~/Library/Containers/com.apple.iBooksX/ and BKAgentService/) — books re-downloaded from iCloud, but import pipeline remained fragile
• Full process kill (Books + BKAgentService + BooksThumbnail) — one successful import, then degradation

What didn't work:

• SQL-level database fixes (CoreData cached state and overwrote changes)
• TCC permission reset (tccutil reset All com.apple.iBooksX) — removed file access prompts
• BKAgentService selective kill — XPC respawns with broken state

Confirmed workaround:

• iPhone iCloud Drive workaround — upload EPUB to iCloud Drive, open on iPhone/iPad in Files app, share to Books. Syncs to Mac via iCloud, bypassing local import pipeline entirely.
• iCloud Books data reset — System Settings → Apple ID → iCloud → Manage Storage → Books → Delete All Data (forces full iCloud sync state reset)

Books.app Import Pipeline

User drags EPUB → Powerbox creates security-scoped bookmark
  → Books.app receives URL via AppleEvent
  → BKResolveAssetForImportOperation copies file to Caches/Inbox
  → BKAgentService XPC picks it up from Inbox
  → BKAgentService unzips EPUB into bundle directory under Books/
  → BKAgentService updates Books.plist with metadata
  → BKLibrary CoreData store records the asset
  → iCloud sync pushes to other devices

Where It Breaks

1. Sandbox security-scoped bookmarks fail → "Unable to access url" (TCC issue)
2. BKAgentService XPC degrades over time → silent import failures
3. Database/file concordance breaks → Books thinks it has files it doesn't
4. iCloud sync state corrupts → phantom entries, cross-device sync fails

Diagnostic Quick-Reference

Check	Command
App log	log show --predicate 'process == "Books"' --last 10m
XPC log	log show --predicate 'process == "com.apple.BKAgentService"' --last 10m
Database state	sqlite3 .../BKLibrary-*.sqlite "SELECT ZSTATE,COUNT(*) FROM ZBKLIBRARYASSET GROUP BY ZSTATE;"
Container size	du -sh ~/Library/Containers/com.apple.iBooksX/
Import queue	ls ~/Library/Containers/com.apple.iBooksX/Data/Library/Caches/Inbox/
Book files	ls ~/Library/Containers/com.apple.BKAgentService/Data/Documents/iBooks/Books/
Migration ghosts	ls -d ~/Library/Containers/com.apple.BKAgentService/Data.old 2>/dev/null