abbu 0.8.1 → 0.18.0

data/docs/CHANGELOG.md

@@ -11,6 +11,104 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Release Tooling
+
+- Browser-initiated GitHub releases accept an exact approved version and commit,
+  verify the supported Ruby matrix, and create immutable tags with the built-in
+  GitHub token before OIDC publication. Protected Sheriff approvals remain required.
+
+## [0.18.0] - 2026-10-03
+
+This release includes the previously unreleased 0.12.0–0.17.0 development milestones.
+
+### Added — optional MCP adapter
+
+- Optional `abbu-mcp` stdio executable and `require 'abbu/mcp'` adapter, using
+  the separately installed official MCP Ruby SDK. Core `abbu` has no MCP runtime
+  dependency and never loads the SDK automatically.
+- Five read-only tools for bounded contact queries, statistics, sources/groups
+  and explicit diagnostics, bound to one operator-selected archive or live path.
+  No arbitrary path tool argument, file export, Contacts mutation, default
+  contact logging, or unevidenced My Card detection.
+
+### Added — snapshot history
+
+- Streaming snapshot-history transitions with bounded absent-contact retention,
+  per-analysis timelines, explicit ambiguity breaks and observed reappearances.
+  Ruby ordered-list API and directory JSON Lines CLI do not infer edit events.
+
+### Added — streaming
+
+- `Archive#each_contact` and `LiveStore#each_contact` enumerate contacts without
+  populating the cached array; SQLite readers close on block termination/errors.
+- Incremental CSV/vCard `write_to(io)`, JSONL export, and opt-in CLI `--stream`.
+  Late failures can leave partial output. Existing buffered exports are unchanged.
+- Reproducible synthetic 10,000-contact benchmark and documented memory bounds.
+
+### Added — portable SQLite
+
+- Portable normalized SQLite exporter and `--format sqlite --output FILE`, with
+  explicit schema version, relational contact/source/group/multivalue/date data,
+  raw-label and primitive-value evidence, transactional staging, and atomic no-overwrite publication.
+  Existing exports and source stores remain unchanged; this is not an Apple writer.
+
+### Added — merge planning
+
+- Immutable merge-plan previews with explicit union, timestamp, source and
+  completeness policies. Conflicts and original provenance remain reviewable;
+  materialization requires an explicit policy and never writes source stores.
+  `--merge-preview` provides a JSON-only preview, never an apply operation.
+- Reject merge options in machine JSON, snapshot-diff, and calendar combinations
+  before input reads; machine-mode conflicts retain structured JSON errors.
+
+### Added — snapshot comparison
+
+- Identity-evidence snapshot comparison through `SnapshotDiff` and `--diff`,
+  with raw field changes, provenance, explicit ambiguity and stable JSON output.
+- Snapshot JSON uses the machine dispatcher and structured error contract;
+  conflicting machine operations and calendar metadata fail before input reads.
+
+### Added — iCalendar
+
+- Deterministic iCalendar birthday/anniversary reminders through a Ruby exporter
+  and `--format icalendar`. Explicit recurrence year, revision time, and calendar
+  namespace avoid fabricated metadata. Unknown years remain unknown; invalid and
+  alternate-calendar dates are diagnosed and omitted. Existing exports are unchanged.
+- Machine JSON rejects calendar metadata before opening inputs, rather than
+  silently ignoring export-only options.
+
+## [0.11.0] - 2026-10-02
+
+### Added — machine JSON
+
+- First-class `--json` for contacts, statistics, schema, sources/groups, duplicate
+  groups, identity matches, and image extraction. New `--diagnostics` and
+  `--matches` are JSON-only operations. Public `JsonExporter#payload` and
+  machine serializers reuse the unchanged contact JSON representation.
+- Documented machine stdout, stderr, exit codes, privacy, and SemVer contract.
+
+### Changed — machine JSON
+
+- JSON-mode errors now emit a single `{ "error": { "code", "message" } }`
+  document instead of empty stdout or a Ruby exception trace. Invalid inputs
+  and conflicting options exit 2; unavailable live inputs and filesystem errors
+  exit 1. JSON callers must check exit status before treating stdout as data.
+- Bare `--json` lists contacts. JSON combinations are validated before reading
+  or writing, rather than silently prioritizing one operation. Human modes and
+  successful existing contact/source/group/schema JSON shapes are unchanged.
+
+### Added — fuzzy matching
+
+- Opt-in bounded, explainable fuzzy name suggestions using Unicode-preserving
+  Levenshtein distance. Exact identity evidence retains precedence; fuzzy-only
+  suggestions remain ambiguous and never merge contacts automatically.
+
+### Added — embedded photos
+
+- Opt-in embedded JPEG/PNG/GIF vCard photos via `photo_mode: :embedded` and
+  `--photo-mode embedded`. URI mode remains the default. Missing, unreadable,
+  or unsupported image evidence fails before output; HEIC embedding is deferred.
+
 ## [0.8.1] - 2026-10-01
 
 ### Fixed

data/docs/CONTRIBUTING.md

@@ -57,6 +57,9 @@ matrix runs this same command with its Bundler-managed installation paths.
 
 ## Pull Request Guidelines
 
+For authorized publication, use the [GitHub-hosted release runbook](RELEASING.md).
+It documents exact-commit dispatch, environment approvals, and safe recovery.
+
 - 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%

data/docs/FUZZY_MATCHING.md

@@ -0,0 +1,72 @@
+<!-- docs/FUZZY_MATCHING.md -->
+
+# Explainable Fuzzy Name Matching
+
+`Abbu::Utils::FuzzyMatcher.new(contact, candidates, threshold: 0.85).matches`
+returns existing `Deduplicator::Match` objects in candidate order. The original
+anchor object is skipped. Existing `Deduplicator#matches` remains unchanged.
+Callers should supply distinct candidate objects. This API suggests comparisons;
+it never selects a winner, collapses records or modifies source evidence.
+
+## Algorithm And Evidence Boundary
+
+ABBU uses normalized Levenshtein edit distance over Unicode codepoints:
+`similarity = 1 - distance / maximum_name_length`. This local, dependency-free
+algorithm exposes an integer edit count. Unlike prefix-boosted metrics, it adds
+no assumption that a matching prefix is more identifying. It is an ABBU
+convention, not an Apple Contacts storage or identity rule.
+
+Names use NFC, downcasing, trimming and whitespace collapse only. Accents,
+punctuation, scripts and compatibility characters remain distinct; no ASCII
+transliteration, nickname expansion, initial expansion or token reordering is
+performed. Canonically equivalent Unicode spellings compare equally. Original
+names remain in evidence and in the contacts. Empty names supply no fuzzy signal.
+
+Thresholds are inclusive, finite numeric values in `[0, 1]`. Comparison uses the
+unrounded similarity. Each qualifying fuzzy signal exposes `algorithm`,
+`distance`, `similarity`, both normalized names, both raw names and `contribution`.
+Threshold 1 requires equality after the documented normalization, not raw equality.
+Even exact normalized names alone remain ambiguous.
+
+## Exact Evidence And Scores
+
+Each pair is also checked by the existing provenance-aware exact matcher. Its
+qualifying score and status take precedence; fuzzy evidence then contributes
+zero, so similarity cannot inflate exact confidence. Exact signal contributions
+follow existing weights, counted once per type and capped in evidence order at
+the total score. Otherwise the fuzzy-only score is `0.15 * similarity`, rounded
+to four decimals, with low confidence and ambiguous status. Scores are ranking
+heuristics, never probabilities. Names are not global identifiers.
+
+Two or more qualifying exact candidates for the anchor make every returned
+suggestion ambiguous. Fuzzy suggestions alone do not demote a single exact
+candidate. Candidate-to-candidate relationships are not evaluated; scope and
+candidate selection remain the caller's responsibility. `Match#merge` still
+requires an explicit caller-provided policy; review remains necessary.
+
+## Resource And Privacy Boundaries
+
+Defaults are 10,000 candidates and 128 normalized codepoints per name. Both
+`max_candidates:` and `max_name_length:` require positive integers. Exceeding a
+bound raises `ArgumentError`, never silent truncation. Candidate enumeration
+reads at most limit+1 elements; names are validated during `matches`. Results
+are buffered. Callers raising limits accept the additional cost.
+
+For N candidates and bounded name length L, edit-distance work is O(N × L²)
+with O(L) distance-row memory. Exact comparison also traverses contact identifier
+collections, so these bounds do not bound arbitrary email/phone arrays. The
+deterministic 1,000-candidate synthetic spec exercises this baseline without a
+flaky wall-clock assertion or personal Contacts data. This is not a benchmark
+claim for arbitrary archive sizes or real-world identity accuracy.
+
+Returned contacts, raw names, exact evidence and source paths are sensitive;
+do not publish match results as sanitized diagnostics. Parsing, exporters and
+existing JSON contracts are unchanged. No private Apple schema assumptions or
+new runtime dependencies are introduced.
+
+[README](../README.md) · [Contributing](CONTRIBUTING.md)
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/HISTORY_EVIDENCE.md

@@ -0,0 +1,98 @@
+<!-- docs/HISTORY_EVIDENCE.md -->
+
+# Contacts History: Evidence Before Events
+
+Research date: 2026-10-01. Issue [#35](https://github.com/scarver2/abbu/issues/35).
+Decision proposed for review: do not expose private save/edit-history fields
+without reproducible storage evidence. This is a research boundary, not a
+completed history parser or a claim that such records cannot exist.
+
+## Three Different Questions
+
+1. What timestamp does a record expose? ABBU already reads observed optional
+   creation/modification fields; these are not a sequence of edits.
+2. What changed between two observed snapshots? Future snapshot comparison can
+   describe differences, not infer actions or exact times between observations.
+3. What events does a supported history provider report? This requires its own
+   evidence and semantics; it must not replace the original record timestamps.
+
+No timestamp alone proves a human edit, an author, or an interaction with the
+Contacts UI. Sync, migration and normalization are alternative hypotheses to
+test, not asserted explanations for a given record.
+
+## Primary Evidence
+
+Apple documents [CNChangeHistoryFetchRequest](https://developer.apple.com/documentation/contacts/cnchangehistoryfetchrequest)
+as a framework query for change history. Its overview says changes are coalesced
+to eliminate redundant adds, updates and deletes. Therefore even this documented
+surface must not be described as a complete keystroke or immutable audit log.
+
+The documented [starting token](https://developer.apple.com/documentation/contacts/cnchangehistoryfetchrequest/startingtoken)
+is opaque. A nil starting token requests a reset event and then add events for
+current contacts/groups; those add events are not proof of original creation
+times. Tokens are not dates, monotonically meaningful integers, or archive keys.
+
+Apple's [unification option](https://developer.apple.com/documentation/contacts/cnchangehistoryfetchrequest/shouldunifyresults)
+distinguishes unified from individual history. A future adapter must preserve
+which mode it requested rather than silently treating the outputs identically.
+
+Sources inspected on the research date. These documents do not specify private
+SQLite history table layouts or mappings into an exported ABBU. No native API
+calls, private live-store reads or personal database experiments were performed.
+
+## Repository Evidence Audit
+
+At accepted main `77eaeda`, the SQLite parser reads `ZCREATIONDATE` and
+`ZMODIFICATIONDATE` as optional record timestamps. Synthetic fixture generation
+and timestamp regressions exercise those fields. The schema inspector reports
+unknown structure without interpreting it. The repository has no verified
+save-history mapping with attributed macOS/Contacts build and controlled event
+sequence. See [format evidence](ABBU.md) and the [compatibility matrix](FORMAT_COMPATIBILITY.md).
+
+A table named like history, transaction, save or change does not establish
+event semantics. Neither file modification times nor WAL page changes identify
+the person who edited a contact. Third-party reverse engineering may supply
+candidate observations, but is not an accepted mapping without reproduction.
+
+## Required Experiment Before Implementation
+
+- Use disposable, unsynced accounts and invented contacts, with explicit
+  experiment approval. Record exact OS/Contacts builds and capture method.
+- Establish a known initial state, then perform one controlled operation per
+  observation: add, scalar edit, labeled-value edit, group membership change,
+  delete, no-op save, and reopen. Separately test sync/migration if in scope.
+- Capture original bytes and compare candidate records without modifying the
+  source store. Record ordering, clock/time-zone assumptions, transaction
+  grouping, retention/reset behavior and missing events. Do not guess epochs.
+- Confirm relationships under duplicate names, source-local ID collisions,
+  linked/unified contacts, and deletion of the referenced record. Keep old
+  schema cases. Unknown layouts must remain unsupported, not empty history.
+- Independently reproduce any external observation. Preserve raw values beside
+  proposed interpretation and document counterexamples and alternative causes.
+
+## Future Public Contract
+
+History would be optional provenance evidence, never replacement `created_at`
+or `modified_at`. Require explicit source/snapshot attribution, raw event data,
+evidenced timestamp interpretation, ordering limits and unknown fields.
+Distinguish unsupported backend, unavailable/permission failure, reset/truncated
+history, and genuinely empty results from a capable provider. Never imply a
+human actor without independent evidence. Define stable JSON and RBS only after
+the source model is justified; no speculative API is shipped here.
+
+Do not log contact values, identifiers, tokens or filesystem paths by default.
+Archived evidence and tokens remain sensitive. A framework adapter would be a
+separately reviewed, opt-in macOS boundary, not a mandatory portable-gem
+dependency or a query against the current user's store when opening an archive.
+
+The research outcome is insufficient evidence for a private parser. #35 can
+close on this scoped boundary under the development-train directive; reopen
+with a reproducible fixture/event sequence. #43/#44 snapshot work remains
+independently useful but must not advertise unseen historical events.
+
+Return to [README](../README.md), [roadmap](TODO.md), or [format evidence](ABBU.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/ICALENDAR.md

@@ -0,0 +1,101 @@
+<!-- docs/ICALENDAR.md -->
+
+# iCalendar Reminders
+
+`Abbu::Exporters::IcalendarExporter` consumes the public `Contact#birthday` and
+`Contact#anniversary` fields, not private Apple tables. It emits one all-day,
+transparent yearly reminder per supported field. Arbitrary `Contact#dates`
+entries are not classified as birthdays or anniversaries by this exporter.
+It does not create alarms, calculate ages, change contacts, or write source stores.
+
+## Explicit Metadata
+
+The constructor requires `year:` (Integer 1–9996), `generated_at:` (Time whose UTC
+year is 1–9999), and a nonempty `calendar_id:` String. The latter is a caller-owned
+unique namespace: choose a unique UUID or identifier under a domain you control,
+and reuse it only for the same logical ordered input. The timestamp is the real
+export revision time, converted to UTC seconds; subsecond precision is omitted.
+No wall clock, random identifier, source timestamp, or fabricated epoch is used.
+
+`to_ical` returns UTF-8 text; `to_file(path)` writes identical bytes;
+`to_stdout` prints those bytes. Same ordered contacts and metadata produce the
+same output. Every call rebuilds `diagnostics`, a frozen array of frozen hashes
+with `category`, zero-based `contact_index`, and `field`. Categories are
+`invalid_date` and `unsupported_calendar`. These omit names, paths and date values.
+
+## Date Policy
+
+An absent year (`nil`) or integer zero is unknown. Other year/month/day values
+must be integers and form a valid proleptic Gregorian date, with known years in
+1–9999. Unknown years use a leap-year validation reference internally; that
+reference is never exported as a birth year. Invalid values are diagnosed and
+omitted, not repaired. No private Apple sentinel year is guessed.
+
+`DTSTART` is the first valid occurrence at or after the caller's year and, when
+known, the source year. February 29 advances to the next leap year if needed;
+yearly recurrence skips non-leap years, never silently shifts to February 28 or
+March 1. `DURATION:P1D` avoids cross-year end-date overflow. All events contain
+an explanatory DESCRIPTION and `X-ABBU-YEAR-UNKNOWN:TRUE` or `FALSE`. Known source
+years appear in DESCRIPTION; unknown source years never gain an asserted age or
+original year. Calendar software may display recurrence starts as dates; these
+are reminders, not birthday-field synchronization or Apple round-trip backups.
+
+`lunar_birthday` is always diagnosed and omitted. A supplied `calendar` key on a
+date permits only absent/nil, `'gregorian'`, or `:gregorian`; anything else is
+diagnosed and omitted. Existing parsers do not expose every private calendar
+attribute, so absence of an attribute is not proof of original Apple calendar
+semantics. This is an explicit Gregorian convention over the current public
+normalized fields, not alternate-calendar conversion or expanded parse support.
+
+SUMMARY preserves `raw_label` when present (including blank), otherwise `label`,
+otherwise Birthday/Anniversary. Custom and wrapped labels remain exact after
+TEXT decoding; the Contact and its evidence are never rewritten.
+
+## Wire And Identity Contract
+
+The standards basis is [RFC 5545](https://www.rfc-editor.org/rfc/rfc5545):
+content lines and UTF-8 in §3.1, TEXT escaping in §3.3.11, DATE in §3.3.4,
+yearly recurrence in §3.3.10, all-day VEVENT in §3.6.1, UID in §3.8.4.7, and
+DTSTAMP in §3.8.7.2. Output uses CRLF, escaped backslashes/commas/semicolons and
+newlines, and UTF-8-safe folding at 75 octets including continuation whitespace.
+Invalid text/control characters raise before opening an output file.
+
+UIDs hash the namespace, zero-based input position, field kind, source-relative
+path, and full name. Duplicate contacts remain separate. These are generated
+reminder identifiers, not Apple IDs or proof of contact identity. Reordering,
+inserting contacts, changing names/provenance, or changing namespace changes
+UIDs; this is not a persistent synchronization feed. Hashes are not anonymization.
+No source paths or contact identifiers are exported in clear text, but names,
+labels, source years, dates and correlatable identifiers are sensitive.
+
+With no supported events, output is the empty string, not an invalid componentless
+VCALENDAR. Tolerant omissions can therefore produce no bytes. Inspect diagnostics.
+`strict:`/`--strict` belongs to parsing only; it does not alter exporter omissions.
+Existing output files are overwritten on successful export, even empty output;
+file writing is buffered but not atomic/no-clobber. Use a separate destination
+outside the source bundle. Filesystem failures can leave partial output.
+
+## CLI
+
+Use `--format icalendar`, `--calendar-year`, `--calendar-stamp` (full ISO 8601
+timestamp with timezone), and `--calendar-id`. Archive and explicit live-store
+input are supported. Only output selection and parser strictness accompany
+calendar export; conflicting operations are rejected. Stdout contains only
+calendar bytes (or none); omission diagnostics go to stderr. Success including
+omissions exits 0, invalid metadata/conflicts exit 2. Existing input/access
+failure behavior is unchanged. The exporter adds no runtime dependency.
+
+## Evidence And Limits
+
+`spec/support/calendar_fixtures.rb` reproduces previously supported plist keys
+and SQLite date columns using synthetic data, not a particular macOS build.
+API and CLI specs exercise byte preservation, unknown-year/leap policies,
+Unicode folding, raw labels, malformed input, and deterministic output. No live
+personal store is inspected. No calendar-client import certification is claimed.
+
+[README](../README.md) · [ABBU evidence](ABBU.md)
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/MACHINE_JSON.md

@@ -0,0 +1,128 @@
+<!-- docs/MACHINE_JSON.md -->
+
+# Machine JSON Contract
+
+`--json` selects one structured operation with no human chatter on stdout.
+Every handled success, no-match, validation, or input/output failure emits one
+UTF-8 JSON document followed by a newline. This is buffered JSON, not streaming
+JSON Lines. Consumers must inspect exit status before interpreting the document.
+Broken output pipes and unexpected programmer errors are not guaranteed a JSON
+response. Human CLI modes and `--format json` without `--json` remain unchanged.
+
+## Operations
+
+| Options | Success document | Empty result |
+| --- | --- | --- |
+| `--json` (optionally `--format json`) | Existing contact JSON array | `[]`, status 0 |
+| `--search TERM --json`, `--email ADDRESS --json`, `--phone NUMBER --json` | Existing contact JSON array | `[]`, status 1 |
+| Timestamp bounds plus `--json` | Existing contact JSON array | `[]`, status 1 |
+| `--stats --json` | Integer `total_contacts`, `with_email`, `with_phone` | All zero, status 0 |
+| `--schema --json` | Existing `schema_report` object | Empty `databases`, status 0 |
+| `--sources --json` | Existing source metadata array | `[]`, status 0 |
+| `--groups --json` | Existing group metadata array | `[]`, status 0 |
+| `--dedupe --json` | Array of `{email, contacts}` | `[]`, status 0 |
+| `--matches` (optional `--json`) | Identity suggestion array | `[]`, status 0 |
+| `--diagnostics` (optional `--json`) | Parser diagnostic array after parsing | `[]`, status 0 |
+| `--extract-images DIR --json` | `{files, diagnostics}` | Two empty arrays, status 0 |
+| `--diff PATH --json` | [Snapshot comparison](SNAPSHOT_DIFF.md), schema version 1 | Empty category arrays, status 0 |
+| `--version --json`, `--help --json` | `{version}` or `{help}` strings | Not applicable |
+
+Only one operation is allowed, except timestamp bounds can accompany one search.
+`--output`, photo mode, or a non-JSON export format conflict with machine mode.
+`--format json` may accompany bare `--json`, but not another operation. Validation
+precedes input reads and image copying. Help/version terminate immediately as
+before. Supply exactly one archive path, or `--live`/`--live-path PATH` with no
+positional arguments. Live schema/search/extraction remain unsupported; live
+stats, contacts, sources/groups, diagnostics, duplicates and matches are supported.
+No live-store snapshot guarantee is added. `--strict` retains fail-fast parsing.
+
+## Schemas And Meaning
+
+Contact objects are exactly `JsonExporter#payload`: absent optional scalar
+fields are omitted, existing empty collections remain arrays, provenance and
+raw labels survive, and timestamps use the existing ISO 8601 representation.
+This method is now public for callers needing Ruby hashes without serializing
+and reparsing JSON. Source/group metadata and schema reports retain their
+previous shapes. Do not depend on whitespace or JSON object key ordering.
+
+Duplicate `email` is the existing first-email hash used by `Deduplicator#duplicates`,
+not a newly normalized string. `contacts` contains the full contact objects.
+`--matches` instead uses `Deduplicator#matches`: each object has full `left` and
+`right` contacts, two `sources` (possibly null), `evidence` containing `type`,
+`normalized`, `left_raw`, `right_raw`, numeric `score`, string `confidence`, and
+string `status`. These are suggestions, not identity truth; no merge is performed.
+Weak or competing candidates retain the existing ambiguity status.
+
+Parser diagnostics contain `category`, `message`, `parser`, `source`, `context`.
+With `--diagnostics` they appear on stdout only. For other machine operations,
+nonfatal parser diagnostics stay on stderr as text and never corrupt stdout.
+Schema inspection alone does not parse contacts or force parser diagnostics.
+
+Image results contain `files` and extraction `diagnostics`. Each file includes
+the full `contact`, raw `image_uri`, absolute string `source_path` and output
+`path`, and `media_type`. Extraction diagnostics use the existing `code`,
+`contact_name`, `image_uri`, and optional `source_path`/`detail`. Partial copies
+and collisions are reported in that array with status 0, as in existing
+extraction; callers must inspect diagnostics to require complete extraction.
+Directory creation failures instead produce an error and status 1. Source
+archives remain read-only; extraction creates separate files without overwriting.
+
+## Errors And Exit Codes
+
+| Status | Meaning in machine mode |
+| --- | --- |
+| 0 | Operation completed (possibly with nonfatal diagnostics) |
+| 1 | Search had no matches (`[]`), or live input/filesystem failure (`error` object) |
+| 2 | Invalid options/input, conflicting operations, invalid timestamp, or parse failure |
+
+Errors have exactly the shape `{"error":{"code":"invalid_input","message":"..."}}`.
+Codes are `invalid_option` for option parsing, `invalid_input` for validation or
+parse failures, and `input_output_error` for live access/filesystem errors.
+Messages aid humans; branch on the code and exit status, not message wording.
+Parser diagnostics can still appear on stderr after a strict failure.
+
+Migration from 0.9: JSON failures now produce this document rather than empty
+stdout; previously ignored operation combinations are rejected. Bare `--json`
+now lists contacts. Search no-match status and successful legacy JSON shapes are
+unchanged. Human CLI error behavior is not normalized by this change.
+
+## Automation And Privacy
+
+```bash
+abbu Contacts.abbu --stats --json >stats.json 2>diagnostics.log
+abbu Contacts.abbu --diagnostics >parser-diagnostics.json
+abbu Contacts.abbu --matches >identity-suggestions.json 2>diagnostics.log
+abbu Contacts.abbu --sources --json | jq '.[].contact_count'
+
+# Do not let jq's status hide ABBU's failure; inspect the producer first.
+if abbu Contacts.abbu --email person@example.test --json >result.json 2>diagnostics.log; then
+  jq '.[].name' result.json
+else
+  status=$?
+  printf 'ABBU status: %s\n' "$status" >&2
+  jq . result.json
+fi
+```
+
+All outputs are sensitive. Full contact/identity/image payloads expose contact
+values, raw labels, identifiers, photo paths and provenance; image extraction
+also writes photos. Parser diagnostics deliberately retain the existing limited
+contexts, but paths and messages can identify local accounts. Schema/source/group
+reports are not sanitized logs. Error messages may contain caller paths or input.
+JSON does not grant permission to send any of this to a remote agent, store it in
+public CI artifacts, or publish logs. Use controlled destinations and permissions.
+No Apple-private semantics are inferred by these serializers.
+
+JSON schemas are public API under the repository's pre-1.0 SemVer policy.
+Breaking shape/type/meaning changes require explicit migration notes and a minor
+version; compatible bug fixes use a patch. Future diff/history or optional MCP
+adapters should consume these public representations without changing established
+operations or imposing an MCP runtime dependency on ABBU core.
+
+See [README](../README.md), [API stability](API_STABILITY.md), and
+[format evidence](ABBU.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/MCP.md

@@ -0,0 +1,148 @@
+<!-- docs/MCP.md -->
+
+# Optional Read-Only MCP Adapter
+
+The adapter connects a trusted local MCP host to one explicitly selected ABBU
+archive or live-store directory. It consumes public ABBU APIs and the
+[machine JSON contract](MACHINE_JSON.md); it never reads parser internals or
+defines new Apple storage semantics.
+
+## Dependency And Execution Boundary
+
+The adapter ships as an opt-in executable/require path inside ABBU rather than a
+second companion gem. This keeps its version, public payloads and tests together
+without a second release pipeline. The official `mcp` gem is **not** a runtime
+dependency of `abbu`, and `require 'abbu'` does not load it. Only adapter users
+install/declare it. Repository development/test uses the SDK for real protocol
+integration tests, not a mock protocol implementation.
+
+```ruby
+# Application Gemfile (once this ABBU development version is released)
+gem 'abbu', '~> 0.18.0'
+gem 'mcp', '~> 1.6.1'
+```
+
+```bash
+abbu-mcp --help
+abbu-mcp /absolute/path/Contacts.abbu
+abbu-mcp --live-path /absolute/path/AddressBook --strict
+```
+
+Use the same Ruby/Bundler environment for both gems. From this repository:
+`mise exec -- bundle exec ruby bin/abbu-mcp /absolute/path/Contacts.abbu`.
+The executable uses Ruby directly, as does packaged `abbu`; it does not source
+development-only shell helpers that are absent from the installed gem.
+Configure an MCP host's stdio subprocess with that command/argument array.
+Do not put shell expansion or credentials in arguments. There is no HTTP server,
+network listener, remote transport or automatically discovered live store.
+
+Missing SDK, invalid startup configuration or unavailable input exits 2 with a
+generic stderr message, no path/exception dump. `--help` prints usage and exits
+without opening input. Once serving, stdout is exclusively SDK JSON-RPC frames.
+
+## Tools
+
+| Tool | Arguments | `structuredContent.data` |
+| --- | --- | --- |
+| `abbu_query` | `mode`, `value`, optional `offset`, `limit` | `{contacts, offset, limit, has_more}` |
+| `abbu_stats` | None | `{total_contacts, with_email, with_phone}` |
+| `abbu_sources` | None | Existing source metadata array |
+| `abbu_groups` | None | Existing group metadata array |
+| `abbu_diagnostics` | None | Existing parser diagnostic array |
+
+Query modes are `search` (partial name/email), `email` and `phone` (existing exact
+normalized lookup), and `modified_since` (timezone-explicit ISO 8601 lower bound).
+Every query requires a string `value`. Empty search retains public Query semantics:
+no matches. Results keep parser ordering and are never automatically deduplicated.
+Offset defaults to 0, limit to 100; maximum limit is 500. `has_more` explicitly
+indicates remaining matches. These are payload bounds, not streaming parsing or
+an archive size limit: the input and query still eagerly materialize contacts.
+
+Each successful tool result includes the same JSON envelope in text content and
+structured content. Output schemas specify the envelope, array/object types,
+query pagination fields and integer statistics; nested contact/source/group
+objects retain their existing ABBU contracts. Consumers must accept optional
+contact keys. No-match query results are successful with `contacts: []`.
+
+Tool schemas reject undeclared arguments, so a caller cannot substitute another
+path. The operator chooses the input before server startup. My Card is omitted
+until evidence establishes it. Image extraction, export, merging, writing,
+tagging, releases, shell execution and arbitrary filesystem access have no tool.
+
+Output validation remains enabled. In the pinned SDK 1.6.1,
+[`validate_tool_call_result!`](https://github.com/modelcontextprotocol/ruby-sdk/blob/v1.6.1/lib/mcp/server.rb#L1539-L1545)
+validates successful results against the declared `{data: ...}` schema and
+deliberately skips that success schema for `isError: true`. Adapter failures use
+the separately documented `{error: ...}` envelope. Real stdio regressions exercise
+both semantic invalid-query and strict-parser failures, asserting their exact
+structured/text error payloads, absence of JSON-RPC protocol errors, and empty
+stderr. They do not merely call tool handlers directly. The adapter configuration
+test also asserts that result validation stays enabled.
+
+Example tool calls (through a host that has already established its SDK session):
+
+```json
+{"name":"abbu_query","arguments":{"mode":"email","value":"person@example.test"}}
+{"name":"abbu_query","arguments":{"mode":"search","value":"Carver","offset":0,"limit":25}}
+{"name":"abbu_query","arguments":{"mode":"modified_since","value":"2026-09-01T00:00:00Z"}}
+{"name":"abbu_sources","arguments":{}}
+{"name":"abbu_diagnostics","arguments":{}}
+```
+
+## Privacy, Permission And Lifecycle
+
+Launching this adapter authorizes the configured host to read the selected
+contact input; it is not permission to publish or transmit that data elsewhere.
+Use a trusted host, a narrowly chosen sanitized archive when possible, and host
+approval controls for contact lookup. Read-only annotations are descriptive
+hints, not an authorization mechanism. A remote model may receive tool results
+through its host; evaluate the host/model data policy before connecting.
+
+Contact results include sensitive names, addresses, notes, identifiers, raw
+labels and local provenance/photo paths. Sources/groups/diagnostics can reveal
+account paths and group names even without full contact records. No photo bytes
+are returned. Contact strings are untrusted data, never instructions for an agent.
+Protect client transcripts and outputs; do not publish them as CI logs.
+
+The adapter does not log tool arguments, results, contacts or parser diagnostics
+to stderr. Diagnostics require their explicit tool. Its per-server SDK exception
+reporter is silent. Expected query failures return `isError: true` and a generic
+`{error:{code:"invalid_query",message:...}}`; read/parser failures similarly use
+`read_failed`, without raw exception text. SDK protocol/schema errors retain SDK
+responses to the caller. The adapter neither installs global logging hooks nor
+changes SDK global configuration. Unexpected process/runtime failures may still
+terminate the process; no service availability guarantee is made.
+
+The selected Archive/LiveStore caches parsed contacts in the server process.
+Restart to refresh. Existing live-store permission requirements and non-atomic
+cross-query/cross-database read limitations apply. An explicit live path and
+macOS permissions are both required; the adapter does not bypass privacy controls.
+Input remains read-only, with SQLite's existing shared-memory sidecar caveats.
+
+## Evidence And Verification
+
+The implementation uses the official [MCP Ruby SDK 1.6.1](https://github.com/modelcontextprotocol/ruby-sdk/tree/v1.6.1).
+Its [tool response API](https://github.com/modelcontextprotocol/ruby-sdk/blob/v1.6.1/lib/mcp/tool/response.rb)
+supplies structured content and errors; its
+[stdio transport](https://github.com/modelcontextprotocol/ruby-sdk/blob/v1.6.1/lib/mcp/server/transports/stdio_transport.rb)
+owns framing and protocol lifecycle. ABBU does not implement JSON-RPC itself.
+The [MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+informs the explicit input/output schemas and duplicate text/structured content.
+
+Synthetic tests cover direct public APIs and a real SDK stdio subprocess:
+2025-11-25 initialization, tools listing, structured stats, and rejection of
+undeclared arguments. SDK-supported newer/older protocol versions remain SDK
+capabilities, not independent ABBU conformance certification. No real address
+books or live user account are read by these tests. Run canonical `bin/spec`,
+`bin/lint`, `bin/package`, and `mise exec -- rbs -I sig validate`.
+
+The adapter is pre-1.0 public API and follows ABBU SemVer. Publication remains
+Sheriff-gated; installing a development branch is not a published release.
+
+See [README](../README.md), [format evidence](ABBU.md), and
+[API stability](API_STABILITY.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com