abbu 0.2.0 → 0.4.0

data/docs/ABBU.md

@@ -9,9 +9,34 @@
 They are **not** a single file format — they are a macOS "package" (a directory bundle that Finder
 presents as a single file). This means you can inspect the contents with `ls` or `open -a Finder`.
 
+## Evidence Standard
+
+Apple does not publish a stable specification for every internal Contacts
+archive schema represented by `.abbu` bundles. This document therefore
+distinguishes observed repository-fixture behavior from documented Apple APIs
+and from hypotheses that still require verification.
+
+Never infer Apple Contacts storage semantics merely from Core Data table or
+column names. Require observed fixture evidence, Apple documentation where
+available, or reproducible verification, and record consequential discoveries
+in this document.
+
+For each new schema, relationship, source layout, image convention, or version
+variation:
+
+1. record the macOS or Contacts version when known;
+2. identify the synthetic fixture, SQLite query, plist key path, file evidence,
+   or Apple documentation supporting the conclusion;
+3. add a deterministic regression fixture and spec; and
+4. label unresolved interpretations as hypotheses rather than format guarantees.
+
+Real address-book exports contain sensitive personal data. Use them only for
+local verification, sanitize the observed behavior into deterministic synthetic
+fixtures, and never commit the original contacts, photos, or account identifiers.
+
 ## Structure
 
-Typical contents of a `.abbu` bundle:
+The supported synthetic fixtures and observed exports use layouts such as:
 
 ```text
 Contacts.abbu/
@@ -36,12 +61,16 @@ Contacts.abbu/
 
 ### 1. SQLite (modern macOS)
 
-Newer macOS versions store the address book in a single SQLite database:
+Supported modern fixtures contain one or more SQLite databases named:
 
 ```
 AddressBook-v22.abcddb
 ```
 
+The following tables and mappings are exercised by the repository's generated
+SQLite fixture and parser specs. Their names alone are not evidence that the
+same semantics apply to every macOS version.
+
 Key tables:
 
 | Table                    | Purpose                                |
@@ -77,12 +106,194 @@ Notable columns in `ZABCDRECORD`:
 | `ZPRONOUNS`              | Pronouns                 |
 | `ZRINGTONE`              | Ringtone                 |
 | `ZTEXTTONE`              | Text tone                |
+| `ZCREATIONDATE`          | Optional record creation timestamp |
+| `ZMODIFICATIONDATE`      | Optional record modification timestamp |
+
+### Timestamp and source provenance
+
+Observed Contacts databases may include `ZCREATIONDATE` and `ZMODIFICATIONDATE` on
+`ZABCDRECORD`. ABBU interprets numeric values in those columns as Apple absolute time:
+seconds since 2001-01-01 00:00:00 UTC. The columns are optional because exported schemas
+vary across macOS releases and account providers; when either column is absent or invalid,
+the corresponding `Contact` value is `nil`.
+
+These values describe timestamps stored on the record. They must not be interpreted as
+proof of a user-initiated creation or edit, because syncing and migration can also affect
+them.
+
+Every parsed contact includes source provenance with the absolute source path, its path
+relative to the `.abbu` root, and whether it came from the root bundle or a database under
+`Sources/<identifier>/`. Legacy plist contacts receive the same file-level provenance.
+
+### Opt-in live Contacts stores
+
+The CLI uses `--live` only for auto-discovery and `--live-path PATH` for an explicit
+store. These forms are mutually exclusive and accept no positional archive/path arguments.
+Option ordering does not change input selection. Synthetic WAL-mode and concurrent-writer
+validation remains a follow-up; read-only handles do not establish snapshot consistency
+across an actively changing Contacts store.
+
+`Abbu.open_live` and the CLI's live modes can read an AddressBook directory
+without first exporting an `.abbu` archive. This mode is deliberately separate from
+`Abbu.open`: archive validation and plist fallback do not apply to a live store.
+
+When no path is supplied on macOS, ABBU checks the observed per-user location at
+`~/Library/Application Support/AddressBook`. Callers may instead provide a directory,
+which keeps automation and tests independent of the host platform and user account.
+ABBU discovers databases directly under that directory and one level below
+`Sources/<identifier>/`, preserving the same root/source provenance used for archives.
+Only files matching the observed `AddressBook-v*.abcddb` shape are candidates; this
+filename pattern is discovery evidence, not a guarantee of stable Apple semantics.
+
+Every live-store database is opened using SQLite's read-only mode. ABBU has no live-store
+write API and never creates, updates, or deletes Contacts data. macOS privacy controls may
+deny access even when the path exists. In that case ABBU raises
+`Abbu::LiveStore::PermissionError` with instructions to grant the calling terminal or
+application Full Disk Access in **System Settings → Privacy & Security → Full Disk
+Access**. Missing directories and databases raise `Abbu::LiveStore::NotFoundError`, and
+automatic discovery without a caller-supplied path raises
+`Abbu::LiveStore::UnsupportedPlatformError` outside macOS.
+
+The repository verifies live-store behavior only with deterministic synthetic SQLite
+fixtures. It does not inspect or commit a developer's real Contacts store.
+### Provenance-aware identity evidence
+
+ABBU treats deduplication as a suggestion boundary rather than proof that two records are
+the same person. `Utils::Deduplicator#matches` compares normalized email, phone, name, and
+organization signals while returning both original contacts, both source records, raw
+evidence, normalized comparison values, confidence, and ambiguity status.
+
+Email comparison trims surrounding whitespace and applies Unicode-aware case folding.
+Names and organizations use Unicode NFKC normalization, case folding, and whitespace or
+punctuation normalization without transliterating distinct characters. Explicit `+` and
+`00` phone forms are compared as international numbers. The trimmed raw value must start
+with a literal ASCII `+` or contiguous `00`; punctuation removal never establishes an
+international prefix. For example, `(001) 512-555-0100` remains national-format evidence.
+National-format numbers remain
+source-local evidence because ABBU has no country or numbering-plan evidence with which
+to infer a global identity.
+
+SQLite primary keys, source identifiers, private Apple link identifiers, and image stems
+are not treated as global contact identifiers. The repository fixtures do not establish
+such semantics. Competing candidates and weak name/organization or source-local phone
+matches remain ambiguous, and no contact is merged unless the caller supplies an explicit
+merge policy.
+
+### Image resolution and extraction
+
+The synthetic SQLite fixture demonstrates a `ZIMAGEURI` value whose stem matches a file
+under an `Images/` directory. Resolution covers the root bundle and nested
+`Sources/<identifier>/Images/` directories. When duplicate stems exist, ABBU uses the
+contact's database provenance to select only an image beside that database; it does not
+guess when the available evidence remains ambiguous.
+
+`Archive#extract_images(output_dir)` and the CLI `--extract-images DIR` copy resolved
+images without changing `Contact#image_uri`, `Contact#image_path`, or `Contact#source`.
+Exported filenames combine a sanitized contact name, the original image identifier, and
+a stable provenance digest. Path separators, control characters, and reserved filename
+characters cannot create subdirectories or traverse outside the selected output directory.
+
+The selected output directory (including symlinked parents) is resolved to its canonical
+directory before copying; callers must control that directory and prevent concurrent
+directory replacement. Each image is created exclusively with owner-only permissions.
+Existing destinations are never overwritten, including regular files, hard links, and
+symlinks (even dangling ones). These collisions produce a `destination_exists` extraction
+diagnostic and no successful file record; other images continue. Repeating extraction
+into the same directory therefore reports collisions instead of replacing earlier output.
+Directory creation/resolution failures raise filesystem errors before extraction begins.
+
+Extraction diagnostics are a separate API from `archive.diagnostics`: they may contain
+contact names, raw image identifiers, source paths, and filesystem error details. Treat
+them and the CLI's image warnings as sensitive contact data, not safe-to-publish logs.
+
+ABBU recognizes JPEG, PNG, GIF, and common HEIF/HEIC-compatible brands from file
+signatures and chooses the exported extension from those bytes rather than the source
+extension. Unknown content is reported as a diagnostic instead of being relabeled. HEIC
+data is copied unchanged; ABBU does not transcode it.
+
+No repository fixture currently demonstrates a reliable Apple thumbnail-versus-full-size
+naming or selection rule. ABBU therefore exports the image resolved by the observed
+`ZIMAGEURI` relationship and does not infer size semantics from filenames or directories.
+
+### Recovery and diagnostics
+
+By default, ABBU recovers from malformed individual plist records, missing
+optional SQLite relationship tables, and unresolved image references. Each
+recovery appends an `Abbu::Diagnostic` to `archive.diagnostics` with a category,
+parser, source path, non-PII context, and a stable message. Required contact
+schema failures still raise because no evidence-backed contact record can be
+recovered safely.
+
+An absent optional SQLite table produces one diagnostic per database and table,
+regardless of contact count. ABBU does not place record identifiers or raw image
+references in these schema- and image-level diagnostic contexts.
+
+Pass `strict: true` to `Abbu.open` or `--strict` to the CLI to raise
+`Abbu::ParseError` on the first recoverable condition. The CLI prints a
+diagnostic summary to standard error so exported data on standard output remains
+pipeable.
+
+### Schema diagnostics
+
+`Archive#schema_report` and `abbu Contacts.abbu --schema` inspect every discovered
+SQLite database and return deterministic schema metadata. Reports identify recognized
+and unrecognized tables and columns, recognized items that are absent, declared SQLite
+types, primary-key and nullability metadata, source provenance, and exact owner/contact-
+style column names that may represent contact links.
+
+These reports are research evidence, not parser mappings. In particular, a
+`contact_link_candidate` flag records only an exact column-name shape such as `ZOWNER`,
+`ZCONTACT`, or `Z_CONTACT`; it does not claim a foreign-key target or assign Apple
+Contacts semantics. Unknown tables and columns must be reproduced in a sanitized fixture
+or supported by documentation before ABBU uses them to populate contacts.
+
+Missing recognized tables and columns remain visible as diagnostic observations. The
+parser tolerates absent established email, phone, and postal-address tables by returning
+empty collections, while the schema report preserves the absence for compatibility
+research. If one of those tables exists but lacks an expected column, parsing raises the
+SQLite schema error instead of silently treating the contact as having no corresponding
+data. The core `ZABCDRECORD` table remains required for contact parsing.
+
+### Labeled values
+
+The synthetic SQLite and plist fixtures include both custom labels and Apple's
+observed standard-label wrapper, such as `_$!<Work>!$_`. ABBU exposes the
+human-facing value as `label` (`Work`) and preserves the exact stored value as
+`raw_label`. Custom, blank, malformed, Unicode, and already-normalized labels
+are not otherwise rewritten. Direct plist keys such as `Birthday` have no
+stored label, so their normalized label is derived from the key and
+`raw_label` is `nil`.
+
+Normalization applies to email addresses, phone numbers, postal addresses,
+URLs, related names, date components, and instant-message handles. JSON keeps
+both values. Human-facing CSV uses normalized labels, while vCard anniversary
+labels prefer `raw_label` so Apple label wrappers and custom source values
+survive parse → model → interchange export.
 
 ### 2. Plist / `.abcdp` (legacy macOS)
 
-Older macOS versions stored each contact as a separate binary plist file under `Records/`.
-Each file is a serialised `ABPerson` dictionary. The `abbu` gem currently stubs this parser
-and returns an empty array with a warning.
+Older macOS versions stored contacts as separate plist files under `Records/`.
+The repository fixtures demonstrate dictionaries that the plist parser
+normalizes into the same contact model used by the SQLite parser. Additional
+plist keys or layouts require fixture evidence before they are treated as
+supported semantics.
+
+## Repository Evidence
+
+- `spec/fixtures/TestContacts.abbu/` exercises the supported synthetic SQLite,
+  nested source, and image-resolution behavior.
+- `spec/fixtures/PlistContacts.abbu/` exercises the supported synthetic legacy
+  plist behavior.
+- `spec/fixtures/identity_cases.yml` contains deterministic synthetic cross-source and
+  Unicode near-collision identity evidence.
+- `spec/support/fixture_generator.rb` is the reproducible source for generated
+  SQLite fixture structure and data.
+- `spec/abbu/schema_inspector_spec.rb` builds deterministic temporary SQLite
+  schemas for missing tables, unknown contact-link candidates, and column drift.
+
+These fixtures prove only the variations they contain. Table names, column
+names, entity numbers, UUIDs, and directory names alone are not sufficient
+evidence for new behavior.
 
 ## Export Steps
 
@@ -96,9 +307,17 @@ The "Contacts Archive" option produces a `.abbu` bundle.
 
 ## References
 
-- [Apple Contacts Framework (private)](https://developer.apple.com/documentation/contacts)
+- [Apple Contacts framework](https://developer.apple.com/documentation/contacts)
+- [iQueryContacts forensic schema notes](https://github.com/MetadataForensics/iQueryContacts)
+- [Observed Contacts timestamp epoch](https://apple.stackexchange.com/questions/115551/how-to-sort-contacts-by-creation-date-or-modification-date-in-ios-contacts-or-os/229313)
+- [LifeOS Apple Contacts timestamp conversion](https://github.com/nbramia/LifeOS/blob/main/scripts/apple_data_export.py)
 - [SQLite3 gem](https://github.com/sparklemotion/sqlite3-ruby)
-- macOS `AddressBook.framework` private headers (reverse-engineered)
+- [macos-ts live Contacts reader](https://github.com/evantahler/macos-ts)
+- Repository fixtures and regression specs listed above
+
+Apple's public Contacts framework documents application-facing concepts, not a
+stable `.abbu` storage contract. Private framework names and Core Data names are
+not normative references.
 
 ---
 Stan Carver II

data/docs/CHANGELOG.md

@@ -11,6 +11,132 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-30
+
+### Fixed
+
+- Live CLI input uses distinct `--live` auto-discovery and `--live-path PATH` forms;
+  mixed modes and unexpected live positional arguments are rejected.
+
+- Deduplication recognizes international phone prefixes from trimmed raw input, not
+  punctuation-stripped digits, keeping national-looking `(001)` values source-local.
+
+- Image extraction exclusively creates destination files and reports `destination_exists`
+  rather than overwriting existing files, symlinks, or hard links. Output directory aliases
+  are resolved before extraction; extraction diagnostic privacy is documented.
+
+### Added
+
+- Explicit, read-only live Contacts access through `Abbu.open_live` and
+  `abbu --live` / `abbu --live-path PATH`, with root and `Sources/*` database discovery
+- Actionable live-store errors for missing databases, unsupported automatic
+  discovery, and macOS Full Disk Access restrictions
+- Platform-independent synthetic coverage for live-store discovery, source
+  provenance, SQLite read-only enforcement, and CLI behavior
+- Provenance-aware `Utils::Deduplicator#matches` suggestions with normalized email,
+  international/source-local phone, Unicode name, and organization evidence
+- Match confidence, ambiguity status, original source records, and raw evidence, plus an
+  explicit callable merge-policy boundary that never silently collapses contacts
+
+- `Archive#extract_images` and `Abbu::ImageExtractor` for copying contact photos to a
+  caller-selected directory with structured missing, unreadable, and unsupported-image
+  diagnostics
+- `--extract-images DIR` CLI support with content-aware JPEG, PNG, GIF, and HEIC extension
+  selection and safe, Unicode-preserving, collision-resistant filenames
+- Source-local resolution for duplicate image stems in nested account directories without
+  guessing when provenance cannot disambiguate candidates
+
+- Structured tolerant-parsing diagnostics with strict API/CLI mode for corrupt
+  plist records, missing optional SQLite data, and unresolved image references
+- Missing optional SQLite tables emit one non-PII diagnostic per database and
+  table instead of repeating schema-level warnings for every contact
+- Evidence-safe SQLite schema diagnostics through `Archive#schema_report` and
+  `abbu <archive> --schema`, including unknown tables/columns, absent recognized
+  schema elements, and owner/contact-style relationship candidates
+- Deterministic schema-variation coverage for missing optional tables, unknown
+  contact-linked tables, and column drift
+- Normalized Apple standard labels with the original source value preserved as
+  `raw_label` on labeled contact values
+- Chainable `Abbu::Query` and `Archive#where` APIs for contact filtering
+- Exact normalized email and phone lookup that returns all matches across sources
+- Case-insensitive partial name and email search through Ruby and tab-separated CLI output
+- Stable `--json` search output using the regular contact JSON schema
+- Contact creation and modification timestamps from optional SQLite `ZCREATIONDATE` and `ZMODIFICATIONDATE` columns
+- Provenance metadata identifying each contact's source database or plist and its location within the ABBU bundle
+- Creation, modification, and source metadata in JSON exports
+- Repository constitution and focused local skills for ABBU format evidence,
+  Ruby gem development, testing, and Sheriff-gated releases
+- Canonical `bin/spec` and `bin/package` workflows, with CI reusing project-local
+  `bin/spec` and `bin/lint` instead of duplicating their commands
+
+### Changed
+
+- CI now runs the Ruby matrix once for pull requests and on pushes to canonical `main`, avoiding duplicate feature-branch push and pull-request runs
+- SQLite parsing now tolerates absent established email, phone, and postal-address
+  tables and returns empty collections while retaining the variation in schema diagnostics;
+  unexpected column drift and other SQL errors on present tables continue to surface
+- vCard anniversary export now prefers the original `raw_label` so Apple and
+  custom source representations survive parse-and-export round trips
+- Minimum supported Ruby and RuboCop target are now 3.3; CI covers Ruby 3.3,
+  3.4, and 4.0, with Ruby 3.3 as the designated lint/tooling job
+- Agent guidance is consolidated in `AGENTS.md`; the redundant `CLAUDE.md` has
+  been removed
+- Gem packaging now includes only the public `bin/abbu` executable instead of
+  repository-only developer commands
+
+## [0.3.0] - 2026-09-29
+
+### Added
+
+- `Contact#image_uri` and `Contact#image_path` accessors
+- `Parsers::SqliteParser` extracts `ZIMAGEURI` from `ZABCDRECORD`
+- `Utils::ImageResolver` builds an index of every image file under the bundle's `**/Images/` directories (jpg, jpeg, png, heic — case-insensitive) and resolves a contact's `image_uri` to a `Pathname` within the bundle
+- `Archive#contacts` automatically resolves `image_path` for any contact that has a non-nil `image_uri`
+- CSV export: new `ImagePath` column (last column)
+- JSON export: `image_uri` and `image_path` fields (omitted via `.compact` when blank)
+- vCard export: `PHOTO;VALUE=URI:file://<absolute path>` line, emitted when `image_path` is present
+- `spec/fixtures/TestContacts.abbu/Images/stan-photo.jpg` stub image, regenerated by `spec/support/fixture_generator.rb`
+
+### Notes
+
+- PlistParser does not extract images — legacy `.abcdp` contacts typically embed image data inline, which is a separate extraction path
+- vCard `PHOTO` references the absolute bundle path; base64 embedding and the `--extract-images` CLI flag are tracked for follow-up
+
+### Fixed
+
+- vCard `PHOTO` file URIs now percent-encode spaces, reserved characters, and non-ASCII bytes in image paths
+- `abbu:export` Rake task wrote hash literals (e.g. `{:address=>"…", :label=>"…"}`) into the `Email` and `Phone` CSV columns. Now correctly extracts the first address and number from each contact's multi-value field.
+
+## [0.2.0] - 2026-05-03
+
+### Added
+
+- `Parsers::PlistParser` — full implementation of legacy `.abcdp` plist contact parsing, replacing the previous stub
+- `PlistParser::FIELD_MAP` constant for flat-field mapping
+- Multi-value field extraction for emails, phones, addresses, URLs, notes, related names, and social profiles
+- `Archive` recursively scans `**/*.abcdp` across the entire bundle tree
+- `plist` gem (~> 3.7) runtime dependency
+- Plist fixture files (`spec/fixtures/PlistContacts.abbu/`) for integration testing
+- `middle_name` attribute on `Contact`; `ZMIDDLENAME` / `Middle` plist key
+- `dates` attribute on `Contact` (array of `{ year:, month:, day:, label: }` hashes)
+- `birthday`, `anniversary`, and `lunar_birthday` accessor methods derived from the dates list
+- `instant_messages` attribute (AIM, Jabber, Skype, etc.); `ZABCDMESSAGINGADDRESS` / `InstantMessage` key
+- `verification_code` attribute on `Contact`; `ZVERIFICATIONCODE` column / `VerificationCode` plist key
+- `phonetic_middle_name` attribute; `ZPHONETICMIDDLENAME` column / `PhoneticMiddle` plist key
+- `ZABCDDATECOMPONENTS` parsing (year/month/day split columns)
+- `BDAY`, `X-LUNAR-BDAY`, `X-ABDATE`, `X-ABLABEL` vCard fields
+- `IMPP` vCard field for instant messaging
+- Birthday, anniversary, lunar birthday, instant messages, and verification code in CSV and JSON exports
+- Plist fixture for testing all the above (`spec/fixtures/PlistContacts.abbu/`)
+
+### Changed
+
+- `Contact#full_name` now includes middle name (`Honorable Stan The Man "Stretch" Carver II`)
+- vCard `N` field includes middle name component
+- `SqliteParser::RECORD_FIELD_MAP` extended with the new column → attr mappings
+- `JsonExporter#contact_hash` includes all new fields; blank fields are dropped via `.compact`
+- `CsvExporter` extended-field section now exports lunar birthday and verification code
+
 ## [0.1.2] - 2026-04-26
 
 ### Added

data/docs/CONTRIBUTING.md

@@ -23,19 +23,29 @@ This runs RSpec and RuboCop automatically on file changes.
 ## Running Tests
 
 ```bash
-mise exec -- bundle exec rspec
+bin/spec
 ```
 
 ## Linting
 
 ```bash
-mise exec -- bundle exec rubocop
+bin/lint
 mise exec -- bundle exec rubocop -a   # autocorrect
 ```
 
+## Packaging
+
+```bash
+bin/package
+```
+
+This builds the current gem, verifies its metadata, installs it into an isolated
+gem home, and loads that installed copy. A successful package check is evidence
+only; it does not authorize a release tag or RubyGems publication.
+
 ## Pull Request Guidelines
 
-- Base branch: `master`
+- Base branch: `main`
 - Commit style: [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `chore:`)
 - All specs must pass and coverage must remain at 100%
 - RuboCop must pass with no offenses

data/docs/TODO.md

@@ -52,7 +52,7 @@ Feature checklist organized by release version.
 
 ---
 
-## v0.2.0 — Plist Parser (In Progress)
+## v0.2.0 — Plist Parser (Released)
 
 - [x] `PlistParser` — parse legacy `.abcdp` plist contact files
 - [x] Full field extraction matching SqliteParser output shape
@@ -102,71 +102,79 @@ Feature checklist organized by release version.
 
 ---
 
-## v0.3.0 — Image Extraction
+## v0.3.0 — Image Resolution (Released)
 
-- [ ] Extract contact photos from `Images/` directory
-- [ ] Map image UUIDs to contacts via `ZIMAGEURI` or `ZHASIMAGE`
-- [ ] `Contact#image_path` accessor
-- [ ] CLI: `--extract-images` flag to export photos alongside contacts
-- [ ] Support JPEG, PNG, HEIC formats
-- [ ] Thumbnail vs. full-size image handling
-
----
-
-## v0.4.0 — Fuzzy Deduplication
-
-- [ ] Levenshtein distance matching for name-based deduplication
-- [ ] Phone number normalization (strip formatting, compare digits)
-- [ ] Configurable similarity thresholds
-- [ ] `Deduplicator#fuzzy_duplicates` method
-- [ ] CLI: `--dedupe --fuzzy` flag
-- [ ] Merge suggestions output (side-by-side diff)
-
----
-
-## v0.5.0 — Merge Engine
-
-- [ ] `Contact#merge(other)` — combine two contacts preserving all data
-- [ ] Conflict resolution strategies (keep-first, keep-last, keep-both)
-- [ ] `Archive#deduplicate!` — in-place merge with backup
-- [ ] CLI: `--merge` interactive mode
-- [ ] Export merged results to new `.abbu` bundle
-
----
-
-## v0.6.0 — Filtering & Querying
-
-- [ ] `Archive#where(field: value)` query API
-- [ ] Filter by region (state, city, country)
-- [ ] Filter by group membership
-- [ ] Filter by date range (created, modified)
-- [ ] CLI: `--filter` flag with key=value syntax
-- [ ] Chainable query interface
-
----
-
-## v0.7.0 — Write Support
-
-- [ ] Create new `.abbu` bundles from Contact objects
-- [ ] Write SQLite databases with correct schema
-- [ ] Write `.abcdp` plist files
-- [ ] Round-trip: read → modify → write
-- [ ] `Archive#save(path)` method
-
----
-
-## v1.0.0 — Sync Adapters & Stable API
-
-- [ ] Adapter interface for external CRM sync
-- [ ] Printavo adapter
-- [ ] HubSpot adapter
-- [ ] Generic webhook/API adapter
-- [ ] Stable public API guarantee
-- [ ] Comprehensive API documentation (YARD)
-- [ ] Performance benchmarks for large archives (10k+ contacts)
+- [x] Resolve contact photos through observed `ZIMAGEURI` relationships
+- [x] `Contact#image_uri` and `Contact#image_path` accessors
+- [x] Root and nested source image discovery
+- [x] CSV / JSON image paths and vCard PHOTO file URI references
 
 ---
 
+## v0.4.0 — Read-only Contacts Toolkit
+
+Implemented in the accepted #19–#25 tranche and earlier prerequisites; publication
+is gated by [release issue #27](https://github.com/scarver2/abbu/issues/27),
+Deputy exact-head review, and Sheriff release authority.
+
+- [x] Evidence-safe schema introspection and `--schema`
+- [x] Lossless Apple label normalization with `raw_label` and anniversary vCard fidelity
+- [x] Creation/modification timestamps and source provenance
+- [x] Tolerant structured diagnostics, per-database/table deduplication, and strict mode
+- [x] Provenance-aware identity suggestions, phone comparison, and explicit merge-policy boundary
+- [x] Source-aware duplicate image-stem resolution
+- [x] First-class image extraction with content detection, safe filenames, and no destination overwrites
+- [x] Chainable query API, exact email/phone lookup, and partial name/email search
+- [x] TSV and stable JSON CLI search output
+- [x] Explicit read-only live macOS Contacts input through `--live` / `--live-path PATH`
+- [x] Ruby 3.3 minimum and lint/tooling gate; Ruby 3.4 and 4.0 CI
+- [x] Pull-request CI plus canonical-main pushes, without duplicate feature-branch runs
+- [x] `AGENTS.md`, local skills, and canonical spec/lint/package workflows
+
+## Pre-1.0 Backlog — Not Included in 0.4.0
+
+These remain future work; no implementation is authorized by release preparation.
+Version assignments below 1.0 are intentionally deferred until scopes are accepted.
+
+- [ ] [#28](https://github.com/scarver2/abbu/issues/28): synthetic WAL, sidecar, and concurrent-writer validation
+- [ ] [#29](https://github.com/scarver2/abbu/issues/29): stronger Apple-compatible vCard fidelity and round trips
+- [ ] [#30](https://github.com/scarver2/abbu/issues/30): embedded vCard photos (currently file URI references)
+- [ ] [#31](https://github.com/scarver2/abbu/issues/31): first-class read-only source objects
+- [ ] [#32](https://github.com/scarver2/abbu/issues/32): first-class groups and membership queries
+- [ ] [#33](https://github.com/scarver2/abbu/issues/33): evidence-backed My Card identification
+- [ ] [#34](https://github.com/scarver2/abbu/issues/34): modified-since and date-range queries
+- [ ] [#35](https://github.com/scarver2/abbu/issues/35): evidence-backed save/edit history
+- [ ] [#36](https://github.com/scarver2/abbu/issues/36): alternate-calendar and lunar metadata research
+- [ ] [#37](https://github.com/scarver2/abbu/issues/37): explainable fuzzy names and configurable thresholds
+- [ ] [#38](https://github.com/scarver2/abbu/issues/38): merge plans, side-by-side evidence, and safe built-in policies
+- [ ] [#39](https://github.com/scarver2/abbu/issues/39): broader machine-readable JSON CLI contract
+- [ ] [#40](https://github.com/scarver2/abbu/issues/40): streaming contact iteration/export and large-store performance
+- [ ] [#41](https://github.com/scarver2/abbu/issues/41): portable SQLite export
+- [ ] [#42](https://github.com/scarver2/abbu/issues/42): birthday/anniversary iCalendar export
+- [ ] [#43](https://github.com/scarver2/abbu/issues/43): identity-aware snapshot diffs
+- [ ] [#44](https://github.com/scarver2/abbu/issues/44): history across snapshot directories
+- [ ] [#45](https://github.com/scarver2/abbu/issues/45): optional MCP/agent adapter over read-only interfaces
+- [ ] [#46](https://github.com/scarver2/abbu/issues/46): evidence-backed new-ABBU writer research
+- [ ] [#47](https://github.com/scarver2/abbu/issues/47): public API stability checklist
+- [ ] Thumbnail/full-size image selection after reproducible format evidence
+- [ ] Region filtering and an explicit CLI filter grammar
+
+Previous in-place `Archive#deduplicate!` / source-archive mutation proposals are
+superseded. Merge plans must preserve originals; any future writer targets a new
+output bundle and requires evidence-backed round-trip validation. Writing live
+Contacts databases is not part of the roadmap.
+
+## v1.0.0 — Future Stable API
+
+- [ ] Complete the API-stability checklist and acceptance evidence before promising stability
+- [ ] Comprehensive public API documentation
+- [ ] Benchmarks for large archives (10k+ contacts)
+- [ ] Optional external CRM adapters (Printavo, HubSpot, generic webhook/API), separately scoped
+
+See [README](../README.md) and [CHANGELOG](CHANGELOG.md) for current behavior
+and historical releases.
+
+—
 Stan Carver II
 Made in Texas 🤠
 https://stancarver.com