Skip to content

feat(library): add stable book identity - #18

Merged
serabi merged 3 commits into
mainfrom
codex/stable-book-identity
Jul 14, 2026
Merged

serabi merged 3 commits into
mainfrom
codex/stable-book-identity

Conversation

@serabi

@serabi serabi commented Jul 9, 2026 •

Copy link
Copy Markdown
Contributor

What

  • add a required SHA-256 content identity to every imported book
  • store EPUBs under deterministic, content-addressed filenames
  • prevent duplicate metadata and file copies for identical EPUB bytes
  • document the content identity as the future CloudKit Book record name

Why

Local UUIDs are useful for on-device relationships, but they are not stable across devices. Hashing the EPUB bytes gives the same book a stable identity everywhere and establishes the foundation the private sync engine needs.

Impact

  • local UUIDs remain unchanged for reading state, bookmarks, and saved words
  • re-importing identical bytes returns the existing book
  • re-importing repairs a missing deterministic EPUB without replacing the book UUID or metadata
  • bundled sample books follow the same import and identity path
  • no migration is included because Piperly has no shipped users

Import safeguards

  • copy each security-scoped source into a unique private snapshot before hashing or parsing
  • stream hashing and collision comparisons off the main actor in bounded chunks
  • publish the validated same-volume snapshot atomically
  • coordinate concurrent imports by content identity so only one task can publish metadata and the final EPUB
  • preserve an existing destination unless its bytes match, preventing collision overwrites
  • remove failed snapshots immediately and clear stale snapshots at startup after a crash or termination

Tests

  • full iPad scheme: 45 tests passed on iPad (A16), iOS 26.4 Simulator
  • covers stable same/different-byte identities, lowercase hexadecimal output, chunk boundaries, duplicates, unreadable cleanup, collision protection, missing-file repair, concurrent imports, and startup snapshot cleanup

Stack


View with Codesmith Autofix with Codesmith
Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.

serabi added 2 commits July 9, 2026 18:26
Book.contentIdentity was a required non-optional field with synthesized
Codable, so any book persisted before this PR failed to decode and, via
try? decode([Book].self), wiped the entire library on upgrade. Decode now
defaults a missing contentIdentity to "" so the record survives; legacy
files still resolve through their original fileName.

Adds backfillContentIdentities() (mirrors backfillCovers) to hash each
legacy file, adopt the real identity, and migrate it to the deterministic
<hash>.epub name, dropping duplicates that already exist under that name.
# Conflicts:
#	Piperly/Services/BookStore.swift
@serabi
serabi changed the base branch from codex/profile-preferences to main July 14, 2026 15:17
@serabi
serabi marked this pull request as ready for review July 14, 2026 15:17
@serabi
serabi merged commit 4e5fd86 into main Jul 14, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant