ADR-002: iCloud source of truth

Status: accepted · Date: 2026-09-10

Context

The existing library and curriculum already live in iCloud and may grow after MVP. Generated indexes must not become a second authority or overwrite handwritten work.

Decision

The iCloud Hacking directory is authoritative for original sources. Hacking/Deadwire is a dedicated canonical subtree for approved notes, review decisions, goals, and learning evidence. Ingestion excludes that subtree plus generated curriculum/output, archives, caches, hidden files, and unsupported media.

Mechanics and tests

Inventory stores path and content hash separately. A renamed file reuses its content artifact; changed bytes create a source revision. Publication uses an expected-content hash; a mismatch creates a conflict. Tests cover symlinks, placeholders, renames, duplicate hashes, and conflicts.

Consequences

iCloud availability becomes an explicit state and cannot be silently treated as empty content. Docker volumes are disposable projections. Obsidian mobile can review canonical notes while heavy processing remains local. Revisit if multi-user editing or a transactional document store becomes necessary.

Alternatives considered

Using GitHub as the authority was rejected because the library is private and iCloud is where handwritten decisions already live. Treating the generated graph or SQLite projection as authoritative was rejected because either can be rebuilt and neither captures the owner’s intent. Copying all sources into Hacking/Deadwire was rejected because it duplicates large and licensed material.

Implementation detail and example

Books/Windows/guide.pdf is identified by its bytes (sha256:<digest>) and separately records its current relative path. If it is renamed to Books/AD/guide.pdf, the path changes but the extraction artifact is reused. If one byte changes, a new source revision is created and downstream inference is invalidated. An approved note in Hacking/Deadwire/notes/<concept-id>.md carries its stable ID, aliases, reviewer, and expected-content hash.

Configuration and failure behavior

DEADWIRE_SOURCE_ROOT selects the iCloud root and DEADWIRE_CANONICAL_SUBDIR defaults to Deadwire. Hidden files, generated output, caches, archives, symlinks, and unsupported extensions are excluded. A zero-byte iCloud placeholder is placeholder, never empty text. A publication hash mismatch produces a conflict file and leaves the handwritten note untouched; a missing historical source remains in provenance with availability=missing.

Verification and revisit trigger

Fixtures exercise duplicate content at two paths, rename, changed bytes, placeholder, missing path, symlink, and handwritten-edit conflict. The inventory report must show file counts separately from unique hashes. Revisit only if the owner explicitly chooses a transactional multi-user document store or changes the canonical vault.