abbu 0.2.0 → 0.8.1

data/docs/CHANGELOG.md

@@ -11,6 +11,185 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-10-01
+
+### Fixed
+
+- Package verification reuses Bundler-installed dependency paths in CI while
+  loading the built ABBU gem from an isolated installation. CI now exercises
+  this check before a release tag is created.
+
+## [0.8.0] - 2026-10-01
+
+This release includes the previously unreleased 0.5.0–0.7.0 development milestones.
+
+### Added — vCard fidelity
+
+- vCard fidelity layer with raw-label-preserving grouped repeated properties,
+  public exporter RBS, and deterministic SQLite/plist-to-vCard regression tests.
+
+### Changed — vCard fidelity
+
+- vCard output now uses CRLF, escaped TEXT/structured components, UTF-8-safe
+  75-octet folding, and URI-specific encoding. Consumers must unfold and decode
+  rather than parse ungrouped literal output lines.
+- Custom labels use grouped `X-ABLABEL` rather than arbitrary TYPE parameters;
+  only standard exact ASCII labels become TYPE. Removed invented anniversary
+  preference and unlabeled-address HOME. Existing method signatures remain.
+- Invalid text/control bytes and unsafe service tokens/schemes fail before
+  output rather than emitting malformed records. Apple-specific support limits
+  and migration guidance are explicit; no Contacts import certification claimed.
+
+### Added — groups
+
+- First-class observed groups scoped by file provenance and SQLite record key,
+  with source/input enumeration, reverse membership lookup, and chainable
+  `Query#in_group` filtering without merging same-name groups.
+- Lossless `Contact#group_memberships` evidence alongside unchanged legacy group
+  labels and contact exports; immutable group snapshots and public RBS.
+- JSON-only `--groups` listing for archives and read-only live stores, preserving
+  raw names, nulls, diagnostics, and explicit unsupported empty/plist-group boundaries.
+
+### Added — sources
+
+- Read-only source containers through `Archive#sources` and `LiveStore#sources`,
+  preserving raw file provenance, unknown providers, queryable contacts, and
+  observed group membership labels without conflating source-local identifiers.
+- JSON-only `--sources` listing for archive/live inputs, including empty sources;
+  public RBS, immutable metadata and deterministic source/file ordering.
+
+### Added — timestamp queries
+
+- Chainable created/modified-since and half-open timestamp range queries with
+  timezone-explicit ISO 8601 bounds, missing-timestamp exclusion, and Query RBS.
+- Archive CLI timestamp filters with existing TSV/JSON results and exit contracts.
+
+## [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,41 @@ This runs RSpec and RuboCop automatically on file changes.
 ## Running Tests
 
 ```bash
-mise exec -- bundle exec rspec
+bin/spec
 ```
 
+Keep the [format compatibility matrix](FORMAT_COMPATIBILITY.md) passing when
+changing parsers, discovery, models or exporters. Add evidence-backed synthetic
+variations without replacing legacy fixtures. Run the focused matrix with
+`bin/spec spec/abbu/archive_compatibility_spec.rb`; the full suite remains
+authoritative for the 100% coverage gate.
+
 ## 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.
+
+Run `bundle install` through the project toolchain first. Package verification
+installs ABBU without resolving dependencies again, then loads that installed
+copy using Bundler's dependency search paths. Missing runtime dependencies still
+fail the load check. Only ABBU is isolated, not the dependency set. The CI Ruby
+matrix runs this same command with its Bundler-managed installation paths.
+
 ## 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/FORMAT_COMPATIBILITY.md

@@ -0,0 +1,97 @@
+<!-- docs/FORMAT_COMPATIBILITY.md -->
+
+# ABBU Compatibility Regression Matrix
+
+Legacy support is a tested behavior, not a filename/version guess. The suite
+must keep the older supported shapes passing as newer fields and layouts are
+added. This matrix is run by ordinary `bin/spec` and therefore by every current
+CI Ruby job (3.3, 3.4, 4.0); it needs no macOS services or personal contacts.
+
+## Evidence and scope
+
+All profiles below are **synthetic**, with **unknown macOS and Contacts build**.
+Their evidence is the repository's existing XML fixture keys, SQLite fixture
+generator, and parser schema-variance tests. They are not collected exports from
+eight Apple releases. In particular, `v1` and `v99` are filename-dispatch probes
+using the known schema; they do not establish support for real schemas with
+those version numbers. Do not report the Ruby CI matrix as a macOS matrix.
+
+`spec/support/compatibility_fixtures.rb` rebuilds each profile inside a fresh
+temporary directory. It reuses only the non-destructive schema/seed methods of
+the existing fixture generator, not its bundle-reset command. No committed
+binary is regenerated or overwritten by these tests.
+
+## Always-on end-to-end profiles
+
+| Profile | Structure / variation | Expected boundary |
+| --- | --- | --- |
+| `xml_records` | XML `.abcdp` under `Records/` | Plist fallback, raw labels, absent SQLite-only timestamps/groups |
+| `xml_nested` | XML records below `Sources/Équipe/Records/` | Recursive archive discovery and source provenance |
+| `sqlite_sparse` | Synthetic `AddressBook-v1.abcddb`; absent timestamp/image/name-extension columns and most relationship tables | Preserve core contact/email; nil absent fields, empty collections, tolerant diagnostics; strict mode raises |
+| `sqlite_root` | Root `AddressBook-v22.abcddb` with all currently queried relationship tables | Strict-mode success, timestamps, original group membership |
+| `sqlite_source_only` | Database only under `Sources/Équipe/` | Root database is not required |
+| `sqlite_empty_root` | Empty root plus two source databases with colliding contact/group keys | Empty source remains listed; every source's contact/group remains distinct |
+| `sqlite_mixed_schemas` | Sparse root plus complete nested database, different filename suffixes | Optional-table state is file-local, not cached globally across schemas |
+| `mixed_formats` | Both SQLite and XML records | Preserve current SQLite-first policy; plist records are intentionally not combined |
+
+Each profile independently asserts expected record counts and file provenance,
+raw versus normalized email labels, query results, timestamp availability, group
+traversal, source enumeration, and strict/tolerant outcomes. JSON retains labels
+and provenance; CSV and vCard retain the core email/contact counts. Export tests
+compare SHA-256 of every input file before and after parsing/exporting and detect
+new or missing files as well as changed bytes. These archive tests do not claim
+byte-for-byte immutability of live WAL shared-memory state.
+
+Additional matrix regressions prevent an unknown required SQLite schema from
+silently falling back to XML, and keep valid XML siblings recoverable when one
+record is malformed. They test public `Abbu.open` behavior without parser mocks.
+The matrix does not freeze vCard whitespace or property spelling; the dedicated
+exporter tests own those contracts.
+
+## Complementary existing coverage
+
+| Variation | Regression location |
+| --- | --- |
+| Full relational fields; absent/invalid timestamps; missing tables vs missing columns | `spec/abbu/parsers/sqlite_parser_spec.rb` |
+| Rich/minimal XML; malformed records; dates; raw anniversary labels | `spec/abbu/parsers/plist_parser_spec.rb` |
+| Empty/multiple files, source collisions, SQLite-first precedence | `spec/abbu/source_spec.rb` |
+| Same-name groups, duplicate joins, null/Unicode labels | `spec/abbu/group_spec.rb` |
+| Duplicate image stems, source-local resolution, missing images | `spec/abbu/utils/image_resolver_spec.rb`, `spec/abbu/archive_spec.rb` |
+| JPEG/PNG/GIF/HEIC signatures, unknown bytes, safe extraction | `spec/abbu/image_extractor_spec.rb` |
+| WAL visibility, concurrent commits and cache limits | `spec/abbu/live_store_wal_spec.rb` |
+| Unknown tables/columns and schema drift without inferred mappings | `spec/abbu/schema_inspector_spec.rb` |
+
+## Unverified historical boundaries
+
+There is no release-attributed real-archive corpus in this repository. Binary
+plist `.abcdp`, alternate private table/column/entity mappings, and exports from
+specific historical macOS/Contacts builds are **not certified by this matrix**.
+XML support must not be generalized to every plist encoding. Existing recovery
+tests likewise do not prove all corruption forms recover safely.
+
+To add a genuine historical variation:
+
+1. Record the export's macOS version, Contacts build, export method and storage
+   encoding; mark any unavailable metadata unknown.
+2. Inspect the relevant behavior privately. Never commit a real address book,
+   photo, account identifier, or unsanitized schema/data dump.
+3. Reproduce only the necessary structure with deterministic invented data,
+   recording the observed keys/columns/relationships and source evidence.
+4. Add a named matrix profile or focused regression with explicit expected
+   fields, provenance, raw evidence, exports, diagnostics and strict behavior.
+5. Fix supported behavior only after the regression demonstrates the gap. Keep
+   older fixtures/tests; do not replace them with the newest schema. Unknown
+   formats should remain explicit gaps, not guessed adapters or silent fallback.
+6. Record the evidence and limits in [ABBU.md](ABBU.md) and this matrix, and run
+   the full suite/lint/CI before review.
+
+This test-only expansion changes neither runtime behavior nor the gem version.
+Future behavior fixes use patch bumps; newly completed features use minor bumps.
+
+Return to [README](../README.md), [format evidence](ABBU.md), or
+[contributing](CONTRIBUTING.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/RELEASING.md

@@ -0,0 +1,75 @@
+<!-- docs/RELEASING.md -->
+
+# RubyGems Trusted Publishing
+
+ABBU publishes RubyGems releases from GitHub Actions using RubyGems.org Trusted
+Publishing. The release workflow intentionally contains no long-lived RubyGems
+API key.
+
+Workflow-level permissions default to `{}`. The release job grants only
+`contents: read` for checkout/source inspection and `id-token: write` for OIDC.
+It has no GitHub repository write permission; the version tag must already exist.
+
+## One-time RubyGems.org setup
+
+As a RubyGems owner for `abbu`, configure a Trusted Publisher with:
+
+- GitHub repository owner: `scarver2`
+- GitHub repository: `abbu`
+- workflow filename: `release.yml`
+- GitHub environment: `release`
+
+Create the GitHub environment named `release` with `scarver2` as a required
+reviewer and administrator bypass disabled. Only tags matching `v*` may deploy.
+The Sheriff may approve a release they initiated; approval is still explicit.
+Verify these settings before the first automated publication. Merely naming an
+environment in YAML does not protect it.
+
+Official RubyGems guidance:
+https://guides.rubygems.org/trusted-publishing/
+
+## Release flow
+
+1. Prepare and review the release on `main`.
+2. Run the canonical spec, lint, and package gates.
+3. Obtain explicit Sheriff authorization for the specific version.
+4. Push only the authorized `vMAJOR.MINOR.PATCH` tag.
+5. GitHub Actions runs `.github/workflows/release.yml`.
+6. The Sheriff reviews the exact tag target and approves the `release` environment.
+   The workflow requires a stable version tag reachable from `origin/main`, checks
+   that it matches `Abbu::VERSION`, and reruns the package gates before publishing
+   with `rubygems/release-gem@v1` using OIDC.
+7. Verify the RubyGems release and provenance against the accepted source.
+
+The workflow does not bump versions, create tags, or grant release authority.
+
+For repeatable candidate verification, run:
+
+```bash
+SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD) bin/package
+```
+
+The workflow sets that same value for
+both verification and the action's `bundle exec rake release` build. Compare the
+published gem with the accepted source; never move a release tag or republish a
+version to recover from a failed run. A failed run after upload requires checking
+RubyGems before retrying. Do not replay the already published `v0.4.0` tag.
+
+Normal PR CI remains the Ruby 3.3/3.4/4.0 review gate; the release job repeats
+spec/lint/package checks on the Ruby 3.3 compatibility floor. Local/manual pushes
+are not the default path. No API key secret is needed, and Trusted Publisher
+registration is not itself permission to publish a new version.
+
+## Repository standard
+
+Use this pattern by default for our other GitHub-hosted RubyGems: OIDC Trusted
+Publishing, a protected `release` environment, exact version-tag verification,
+canonical repository checks, and no long-lived RubyGems publishing secret.
+
+See [AGENTS.md](../AGENTS.md), [contribution workflows](CONTRIBUTING.md), and
+[README](../README.md). This infrastructure PR does not authorize a release.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

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,82 @@ 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
+
+The [API stability gate](API_STABILITY.md) defines the evidence required below;
+its existence does not mean those checks are complete or authorize a 1.0 release.
+
+- [ ] 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

data/lib/abbu/archive.rb

@@ -2,26 +2,76 @@
 # frozen_string_literal: true
 
 require 'pathname'
-require_relative 'parsers/sqlite_parser'
+require_relative 'diagnostic'
+require_relative 'image_extractor'
+require_relative 'parse_error'
 require_relative 'parsers/plist_parser'
+require_relative 'parsers/sqlite_parser'
+require_relative 'query'
+require_relative 'schema_inspector'
+require_relative 'source_catalog'
+require_relative 'utils/image_resolver'
 
 module Abbu
   class Archive
-    attr_reader :path
+    attr_reader :diagnostics, :path
 
-    def initialize(path)
+    def initialize(path, strict: false)
       @path = Pathname.new(path)
+      @strict = strict
+      @diagnostics = []
       validate!
     end
 
     def contacts
-      parser.contacts
+      @contacts ||= parser.contacts.tap { |cs| attach_images(cs) }
+    end
+
+    def query
+      Query.new(contacts)
+    end
+
+    def where(criteria)
+      query.where(criteria)
+    end
+
+    def search(term)
+      query.search(term)
+    end
+
+    def find_by_email(email)
+      query.find_by_email(email)
+    end
+
+    def find_by_phone(phone)
+      query.find_by_phone(phone)
     end
 
     def sqlite?
       db_paths.any?
     end
 
+    def extract_images(output_dir)
+      ImageExtractor.new(contacts).extract(output_dir)
+    end
+
+    def schema_report
+      SchemaInspector.new(db_paths, root_path: @path).report
+    end
+
+    # Enumerate only the files selected by this archive's existing parser mode.
+    def sources
+      @sources ||= SourceCatalog.new(sqlite? ? db_paths : plist_paths, root_path: @path, contacts: contacts).sources
+    end
+
+    def groups
+      @groups ||= sources.flat_map(&:groups).freeze
+    end
+
+    def groups_for(contact)
+      groups.select { |group| group.include?(contact) }
+    end
+
     private
 
     def validate!
@@ -39,10 +89,34 @@ module Abbu
 
     def parser
       if sqlite?
-        Parsers::SqliteParser.new(db_paths)
+        Parsers::SqliteParser.new(db_paths, root_path: @path, diagnostics: diagnostics, strict: @strict)
       else
-        Parsers::PlistParser.new(plist_paths)
+        Parsers::PlistParser.new(plist_paths, root_path: @path, diagnostics: diagnostics, strict: @strict)
       end
     end
+
+    def attach_images(contacts)
+      return if contacts.empty?
+
+      resolver = Utils::ImageResolver.new(@path)
+      contacts.each do |contact|
+        next unless contact.image_uri
+
+        contact.image_path = resolver.resolve(contact.image_uri, source: contact.source)
+        record_missing_image(contact) unless contact.image_path
+      end
+    end
+
+    def record_missing_image(contact)
+      diagnostic = Diagnostic.new(
+        category: :missing_image,
+        message: 'Referenced contact image was not found',
+        parser: :archive,
+        source: contact.source&.fetch(:path, @path.to_s) || @path.to_s,
+        context: {}
+      )
+      diagnostics << diagnostic
+      raise ParseError, diagnostic if @strict
+    end
   end
 end