abbu 0.8.1 → 0.18.0

data/docs/MERGE_PLANS.md

@@ -0,0 +1,78 @@
+<!-- docs/MERGE_PLANS.md -->
+
+# Safe Merge Plans
+
+`Abbu::MergePlan.new(left, right, policy: nil, source: nil)` creates a detached,
+frozen review artifact. A plan does not assert that the records identify the
+same person. `to_h` exposes policy, sources, both complete input snapshots,
+per-field selected values and alternatives, conflicts, reasons and a
+`materializable` flag. The caller remains responsible for identity decisions.
+
+## Explicit Policies
+
+All policies union multivalues by exact Ruby equality, retaining left order then
+unseen right values. Raw labels are never normalized or discarded. Same address
+with different raw labels remains two entries. Arrays include emails, phones,
+addresses, groups, URLs, notes, related names, social profiles, dates and IMs.
+
+- No policy: preview only; conflicting scalars remain unresolved.
+- `union_multivalues`: materialize only when scalars have no unresolved conflict.
+- `prefer_newer`: prefer the input with the later observed `modified_at` Time.
+  Missing/non-Time/equal values do not choose a winner. This is caller policy,
+  not proof of human edit history or field-level freshness.
+- `prefer_source`: `source:` must equal the file-level `relative_path` of exactly
+  one input; source directory/provider names are not identity shortcuts.
+- `prefer_more_complete`: prefer the input with more populated scalar fields
+  and nonempty multivalue collections, one point per field; timestamps and images
+  are excluded. Ties do not choose a winner. This is a heuristic, not truth.
+
+Nonconflicting scalar evidence fills missing values regardless of preferred
+record. Empty strings are considered absent; whitespace-only strings are not
+stripped. Conflicts keep both alternatives even when a policy selects a value.
+Image URI and path are one atomic selection, never a cross-record combination.
+No implicit field normalization, date conversion or image copying occurs.
+
+`materialize` requires an explicit policy and rejects unresolved conflicts. It
+returns a fresh mutable Contact, independent of the frozen plan and originals.
+Its `source` is nil and `group_memberships` is empty: a derived record cannot
+claim a single original file or merge source-local group keys. Original sources
+and full group membership evidence remain in `to_h[:inputs]`; keep the plan with
+the derived contact for provenance. Display group labels are unioned normally.
+Existing contact exporter schemas remain unchanged.
+
+Snapshots accept nil, booleans, symbols, numbers, strings, Time/Date, arrays and
+hashes; unsupported caller objects raise rather than being frozen in place.
+Plans are eager in-memory artifacts, not streaming stores.
+
+## CLI Preview And Privacy
+
+`abbu Contacts.abbu --merge-preview` emits a JSON array of plans for the existing
+exact identity engine's candidate pairs. Optional `--merge-policy POLICY` and
+`--prefer-source PATH` choose preview preferences. `--strict` and live input
+selection are supported; other operations, including `--json`, are rejected.
+JSON is intrinsic to this preview. Empty previews exit 0; argument or strict
+parse errors exit 2; existing live input errors retain exit 1. Diagnostics remain
+on stderr. Policies validate even when there are no candidates. A source selector
+that does not uniquely identify one member of a candidate pair fails explicitly.
+
+Merge options cannot accompany machine operations (`--json`, `--matches`, or
+`--diagnostics`), snapshot diff, or calendar exports/metadata. Machine-mode
+conflicts produce the existing structured `invalid_input` error with status 2;
+they never silently fall back to contact output. Operation conflicts and orphaned
+policy/source options are rejected before reading inputs.
+
+There is no CLI apply, file output or source mutation path. Exact matching is
+currently all-pairs and results/plans are buffered: scope inputs in the Ruby API
+for large datasets. A plan contains sensitive raw values, labels, image paths,
+identifiers and source paths; it is not redacted telemetry. It should be stored
+and transported with the same protection as the original address book.
+
+This feature uses existing Contact evidence only and asserts no new Apple
+storage semantics. Legacy parser and exporter contracts remain unchanged.
+
+[README](../README.md) · [Contributing](CONTRIBUTING.md)
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/MY_CARD_EVIDENCE.md

@@ -0,0 +1,92 @@
+<!-- docs/MY_CARD_EVIDENCE.md -->
+
+# My Card: Evidence Boundary
+
+Research date: 2026-10-01. Issue: [#33](https://github.com/scarver2/abbu/issues/33).
+Proposed decision, effective when merged: private-store evidence is insufficient
+for ABBU to identify My Card. No detector, `me` method or `--me` flag is added.
+
+## What Is Documented
+
+Apple's [My Card guide](https://support.apple.com/guide/contacts/set-up-your-my-card-adrb3525ca49/mac)
+describes selecting a different card as My Card and sharing/export controls.
+Designation is not equivalent to the first contact, the local account name,
+an email domain, or the most complete record.
+
+Apple's public [CNContactStore API](https://developer.apple.com/documentation/contacts/cncontactstore)
+includes `unifiedMeContactWithKeys(toFetch:)`. This is a supported framework
+surface, not documentation of an ABBU table, column, key, or archive mapping.
+Its existence prevents the stronger, incorrect conclusion that macOS has no
+supported way to retrieve My Card.
+
+The [unified contact API](https://developer.apple.com/documentation/contacts/cncontactstore/unifiedcontact%28withidentifier%3Akeystofetch%3A%29)
+also documents that unification can return a different identifier than requested.
+Do not assume framework identifiers equal file-local SQLite record keys, or
+that a unified live contact identifies one historical archive record.
+
+These primary sources were inspected on the research date. No framework call,
+permission prompt, real Contacts access, or import experiment was performed.
+
+## Repository Audit
+
+The current parser models, fixtures and documentation contain no verified
+My Card designation mapping. The existing [compatibility matrix](FORMAT_COMPATIBILITY.md)
+tests synthetic read behavior without attributed macOS/Contacts builds. It
+does not prove an archived designation is present, absent, unique or retained
+across account changes. Group/source provenance is not identity designation.
+
+Audit scope: `lib/`, `spec/` and `docs/`, including parser field mappings and
+the synthetic fixture corpus at accepted main `77eaeda`. This is an audit of
+this repository's evidence, not an exhaustive claim about every Apple schema.
+Third-party findings and suggestive column names would be hypotheses pending
+independent, sanitized reproduction.
+
+## Agent-Safe Outcome
+
+Current archive and direct read-only live-store inputs are **unsupported for
+My Card identification**, not “no My Card exists.” Consumers must not substitute
+the first record, logged-in user's name, matching email, image, or source folder.
+There is no new JSON shape or misleading always-nil API in this docs-only change.
+
+A future implementation must distinguish these states in a reviewed public
+contract before coding:
+
+| State | Required meaning |
+| --- | --- |
+| Unsupported | The input/backend has no verified designation capability. |
+| Unavailable | A capable backend could not retrieve designation, including permission errors; not proof of absence. |
+| Absent | A verified capable backend explicitly reports no designation. |
+| Found | Exactly one evidenced designation with provenance; never heuristic confidence. |
+| Ambiguous | Multiple unresolved designations; preserve candidates without selecting a winner. |
+
+State names here are design requirements, not shipped enum names. Structured
+results must be deterministic and preserve ambiguity. Do not emit contact
+names, paths, identifiers, or values in diagnostic logs by default. Returning
+the designated contact is itself sensitive and requires explicit user intent.
+
+## Reopening Gate
+
+For archive support, use disposable local accounts and invented contacts with
+known designation changes. Record macOS and Contacts builds, export settings,
+source membership, before/after evidence, and the verified relationship from
+designation to record. Test zero/one/multiple/unsupported inputs, same-name and
+same-email decoys, cross-source collisions, and legacy XML separately. Keep
+unrelated fields constant so a correlated change is not assumed causal.
+
+For a public-framework adapter, propose a separate opt-in macOS boundary with
+permission handling and no mandatory native dependency for the portable gem.
+Do not silently query the current user's Contacts while opening an unrelated
+archive. Prove any identifier mapping independently; preserve framework
+unification provenance rather than inventing one archive source.
+
+Either path needs sanitized reproducible fixtures, exact-version scope, raw
+evidence preservation, RBS/API/CLI contracts, regression coverage and review.
+This issue permits an insufficient-evidence conclusion; no runtime feature or
+version bump is claimed. Reopen with concrete evidence, not a guessed mapping.
+
+Return to [README](../README.md), [roadmap](TODO.md), or [format evidence](ABBU.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/PORTABLE_SQLITE.md

@@ -0,0 +1,142 @@
+<!-- docs/PORTABLE_SQLITE.md -->
+
+# Portable Normalized SQLite
+
+`Abbu::Exporters::SqliteExporter.new(contacts).to_file(path)` creates a separate
+SQLite artifact from an `Enumerable<Abbu::Contact>`. It returns the canonical
+destination path as a String. It has no stdout or source-writing API. The CLI is
+`abbu Contacts.abbu --format sqlite --output contacts.sqlite`; explicit live-store
+input is also supported, without adding snapshot guarantees.
+
+This is an embedded/local export, not a server database. SQLite is deliberately
+used for portability; no PostgreSQL service or Rails dependency is appropriate.
+Schema definitions use fixed ABBU-owned SQL identifiers through the existing
+sqlite3 library, and every contact value is a bound parameter. No user text is
+interpolated into SQL identifiers or expressions. No new dependency is added.
+
+## Schema Version 1
+
+`SqliteExporter::SCHEMA_VERSION`, `PRAGMA user_version`, and the single `metadata`
+row all report 1. Metadata also records `generator_version` (the gem version),
+not a wall-clock timestamp. A schema change needs explicit versioning; readers
+must reject unknown versions rather than assume compatibility. There is no
+in-place migration command; recreate derived artifacts from retained inputs.
+
+| Table | Queryable facts and relationships |
+| --- | --- |
+| `metadata` | `schema_version`, `generator_version` |
+| `contacts` | Sequential `id`, nullable `source_id`, all supported flat name/organization/phonetic/pronoun/tone/verification/image fields, `created_at`, `modified_at`, flat-field `evidence_json` |
+| `sources` | File-level observed `path`, `relative_path`, `kind`, `identifier`, complete `evidence_json` |
+| `emails` | `contact_id`, `position`, `address`, `label`, `raw_label`, `evidence_json` |
+| `phones` | Same identity/order columns, `number`, labels, evidence |
+| `addresses` | Same identity/order columns, `street`, `city`, `state`, `zip`, `country`, labels, evidence |
+| `urls` | Same identity/order columns, `url`, labels, evidence |
+| `related_names` | Same identity/order columns, `name`, labels, evidence |
+| `social_profiles` | Same identity/order columns, `service`, `username`, evidence |
+| `instant_messages` | Same identity/order columns, `address`, `service`, labels, evidence |
+| `notes`, `group_labels` | `contact_id`, `position`, nullable display `value`, original `evidence_json`, including duplicates |
+| `dates` | `contact_id`, `field`, `position`, `year`, `month`, `day`, labels, evidence |
+| `groups` | Sequential `id`, nullable `source_id`, observed `record_id`, raw `name`, evidence |
+| `group_memberships` | `contact_id`, `position`, `group_id`, retaining duplicate observations |
+
+Collection primary keys preserve contact-local order. Foreign keys link children
+to contacts, contacts/groups to source files, and memberships to groups. Indexes
+support source and reverse group lookup. Foreign keys are enabled during export;
+downstream writers must enable them on their own connections. Derived IDs are
+1-based insertion IDs, not Apple identities; collection positions are zero-based.
+
+For example, ordinary SQL clients can query `contacts JOIN emails ON
+contacts.id = emails.contact_id` without knowing any Apple table name. Contact
+name components remain separate, rather than hiding queryable facts in JSON.
+`evidence_json` duplicates each structured entry's complete public hash, including
+unknown extra keys, nulls, raw labels and nested primitive data. It distinguishes
+missing keys from explicit nulls where fixed relational columns cannot. Hash keys
+are canonically sorted; array order is preserved. Source date/calendar evidence
+is copied without interpreting it or fabricating missing years. Flat fields,
+notes and group-label values also retain original JSON primitives in evidence:
+their TEXT columns are query/display conveniences, not authoritative original
+types. For example, a plist integer name/note remains an integer in evidence
+even though its text column is a string. Pathname objects are represented by
+their path strings; arbitrary Ruby object serialization is not promised.
+
+`dates.field` distinguishes `birthday`, `anniversary`, `lunar_birthday`, and
+`dates`. Direct fields and collection entries are intentionally both retained;
+they are not deduplicated. Dates are stored as observed components, not validated
+or converted into a guessed calendar. Timestamps use ISO 8601 with nine fractional
+digits and their original offset; absent timestamps remain NULL. Image URI/path
+references are text only: no image files are read or embedded.
+
+## Sources And Groups
+
+Sources are file-provenance hashes observed on the supplied contacts, deduplicated
+by complete canonical evidence. They are not inferred account/provider identities.
+Empty sources and unreferenced groups cannot be discovered from the contact input
+and are not fabricated. For those catalogs, retain the original archive or use
+the public Source/Group listing APIs separately.
+
+Groups deduplicate only identical membership evidence within the same complete
+source descriptor. Repeated keys across sources remain separate. Conflicting names
+or extra evidence yield separate observations, not silent reconciliation. With no
+source descriptor, groups remain contact-local. `group_labels` independently keeps
+the complete `Contact#groups` array; names are not treated as group identities.
+
+## Determinism And Round-Trip Evaluation
+
+The exporter materializes the contact enumerable; it is not a constant-memory
+streaming implementation. It iterates contacts and collections in supplied order,
+and assigns IDs in first-occurrence order. Equivalent ordered input and generator
+version produce identical relational contents; tests additionally establish byte
+equality with the same SQLite library. Byte identity across SQLite versions is
+not promised. Reordering input or changing generator version changes the artifact.
+
+Regression tests reconstruct normalized collections and dates from the persisted
+rows/evidence, compare flat fields and timestamps, and preserve duplicate/null
+labels and membership observations. Both legacy XML and SQLite sources are tested.
+This evaluates the normalized interchange boundary only: no public re-import API,
+private Apple schema writer, Apple import certification, account identity mapping,
+or byte-for-byte original archive restoration is provided. JSON primitive evidence
+is preserved; arbitrary custom Ruby object graphs are outside the contact contract.
+
+## Publication And Source Safety
+
+The destination parent must already exist. A temporary SQLite file is created
+in that resolved directory with mode 0600. Data insertion uses a transaction;
+the completed database is closed before an atomic same-filesystem hard link
+publishes the final name. This operation fails if any destination already exists,
+including a dangling symlink or a file created concurrently. Temporary files are
+removed after success or failure. Empty input still creates a valid versioned
+database with no contacts.
+
+No destination is overwritten. Destinations beneath `.abbu`-suffixed directories
+are rejected even for empty input; observed source-bundle aliases are also resolved
+and rejected when the real directory has a different name. Callers must control the
+destination directory and prevent concurrent ancestor replacement; this is not an
+adversarial filesystem sandbox. Filesystems without hard-link support fail safely,
+without an unsafe overwrite fallback. No cross-filesystem atomicity or power-loss
+durability guarantee is claimed. Source parsing retains existing read-only/live
+consistency limitations; exporting does not repair or checkpoint source databases.
+
+## Security And CLI Failures
+
+This user-requested portable/queryable export is deliberately **plaintext**, an
+exception to encrypted application database storage—not an encrypted database or
+multi-tenant service. It contains confidential names, contact values, notes,
+verification-code fields, and absolute provenance/image paths. Owner-only mode is
+not encryption. Keep it on encrypted storage, protect backups separately, minimize
+retention, and do not publish it in logs, issues, analytics, or test fixtures.
+Use only synthetic data in tests. Exporting does not contact external services.
+
+CLI success produces no stdout and exits 0; omission/parser diagnostics retain
+their existing stderr behavior. `--format sqlite` requires an output file and
+rejects conflicting operations. Filesystem, SQLite, and JSON generation failures
+exit 2 with a class-only export error rather than contact payloads. Input/access
+failures retain the existing CLI contract. The Ruby API raises the underlying
+exception, which callers should treat as potentially sensitive. No release action
+is authorized by a successful package/export check.
+
+[README](../README.md) · [ABBU evidence](ABBU.md)
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/RELEASING.md

@@ -1,73 +1,81 @@
 <!-- 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.
+# GitHub-Hosted Releases
+
+[Back to README](../README.md) · [Contributing](CONTRIBUTING.md)
+
+Release automation executes Sheriff authorization; green checks do not grant it.
+Never dispatch a publication run or approve its environment without approval for
+the exact version and commit. No local personal access token or RubyGems API key
+is required for the browser-driven path.
+
+## One-Time Configuration
+
+- RubyGems Trusted Publisher: owner `scarver2`, repository `abbu`, workflow
+  `release.yml`, environment `release`.
+- GitHub `release` environment: required reviewer `scarver2`, administrator
+  bypass disabled, exact branch `main` and tags `v*` allowed. If the Sheriff
+  starts and approves the run, self-review prevention must remain unchecked.
+- Permit the workflow's job-scoped permissions. Do not broaden the repository's
+  default token permissions or add a long-lived publishing secret.
+- Any tag ruleset must permit the authorized Actions tag-creation job. If it
+  blocks creation, stop for owner review; do not bypass protection or add a PAT.
+
+## Release From The Browser
+
+1. Merge reviewed release changes and a dated changelog. Verify accepted CI.
+2. Open **Actions → Release gem → Run workflow**, selecting branch **main**.
+3. Enter the approved numeric version (without `v`) and its complete lowercase
+   40-character commit SHA. An earlier accepted commit is allowed; a branch name
+   or abbreviated SHA is not. The workflow itself must be run from `main`.
+4. The run displays the version/SHA and verifies ancestry, version, dated
+   changelog, and any existing tag. Specs, lint and package checks run on the
+   exact candidate across Ruby 3.3, 3.4 and 4.0 before a tag can be created.
+5. Approve **Authorize and tag exact candidate** in the protected environment.
+   It creates only `vVERSION`, never moves a tag, and accepts a matching existing
+   tag for recovery. Check the run's version and SHA before approving.
+6. Approve **Publish approved gem** if GitHub requests a second environment
+   review. Separate jobs intentionally isolate Contents-write from OIDC rights.
+   Publishing checks the tag again, reruns specs/lint/package, and uses RubyGems
+   Trusted Publishing. The publishing job has only Contents-read and OIDC-write.
+7. Verify the published version on RubyGems and inspect its provenance and run
+   result. The action waits for registry propagation; the run summary records
+   the version and source commit. This workflow does not create a GitHub Release.
+
+The retained external `v*` tag-push path runs the same gates when the tagged
+commit contains this workflow. Older tagged commits use their historical
+workflow; manual dispatch from current `main` can release an older accepted
+candidate without changing that candidate. Newly created Actions tags do **not**
+trigger another push workflow: this run proceeds directly to publishing.
+
+## Safe Checks And Recovery
+
+`bin/release-check VERSION FULL_COMMIT_SHA` is read-only. Run in a clean checkout
+after fetching `origin/main` and tags; it checks those local references and does
+not fetch, create tags, or publish. The workflow fetches immediately before it.
+This command checks source invariants, not tests or publication authority.
+
+For a reproducible local package comparison, use
+`SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD) bin/package` in the accepted
+checkout. The workflow uses the candidate commit timestamp for verification and
+the publishing action's build. Do not replay previously published tags, including
+`v0.4.0`.
+
+If a job fails, inspect its logs. An existing matching tag permits retry after
+fixing infrastructure, but a conflicting tag is a hard stop. Never delete or
+move a release tag. If RubyGems already has that version, verify its provenance
+before doing anything else: rerunning publication is not an idempotent no-op.
+There is no automatic yank, overwrite, version increment, or rollback.
+
+The first workflow PR must be merged before the Run workflow button appears.
+That merge does not authorize releasing its commit. Reconfirm the exact candidate
+if it differs from the Sheriff's previously approved SHA. Workflow-only tooling
+does not change the gem's public version.
+
+## References
+
+- [GitHub token event behavior](https://docs.github.com/en/actions/concepts/security/github_token)
+- [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/)
 
 —
 Stan Carver II

data/docs/SNAPSHOT_DIFF.md

@@ -0,0 +1,74 @@
+<!-- docs/SNAPSHOT_DIFF.md -->
+
+# Snapshot Comparison
+
+`Abbu::SnapshotDiff.new(before, after).to_h` compares two Archive/LiveStore
+objects or ordered contact Enumerables. `abbu Before.abbu --diff After.abbu
+--json` emits the same versioned JSON object. Omit `--json` for count summaries.
+The first CLI input may use explicit read-only live input selection; the second
+is an archive. `--strict` applies to both. The command exits 0 for a completed
+comparison even when differences or ambiguities exist, and 2 for argument/parse
+errors (live-store errors retain exit 1). Diagnostics remain on stderr.
+JSON mode follows the [machine error contract](MACHINE_JSON.md): one structured
+error document, with filesystem/access failures exiting 1. Only input selection,
+`--strict`, and optional `--json` may accompany `--diff`; other operations,
+export formats, output paths, and calendar metadata are rejected before reading
+either input. Comparison-input diagnostics are summarized on stderr.
+
+## Identity Boundary
+
+Comparison uses the existing exact/provenance-aware identity engine, not Apple
+record keys or fuzzy matching. Every cross-snapshot pair is evaluated. Only
+one-to-one candidates at the engine's probable threshold become comparisons.
+Competing candidates and weaker qualifying evidence remain `ambiguous`; their
+records are excluded from added/removed so ambiguity is not presented as loss.
+No contact is merged or modified. A probable match is still an evidence-based
+suggestion, not a declaration of identity truth.
+
+No qualifying evidence means unmatched: an email/name/phone change that removes
+all qualifying evidence may appear as removed plus added. A name alone does not
+establish continuity. Source moves remain visible through provenance changes.
+Identical nameless/no-signal records are not silently paired by array position.
+
+## JSON Contract (Schema Version 1)
+
+Top-level keys: `schema_version`, `added`, `removed`, `changed`, `unchanged`,
+`ambiguous`. Unmatched entries contain side-local `index` and a full `contact`
+snapshot. Compared/ambiguous entries contain `before_index`, `after_index`,
+`score`, exact-engine `evidence`, and full `before`/`after` snapshots. Compared
+entries additionally contain `fields`: changed field names mapped to original
+`before` and `after` values. Unchanged comparisons have empty `fields`.
+
+Snapshots cover the explicit `SnapshotDiff::FIELDS` public contact attributes,
+including raw labels, all multivalues, group membership, source, image paths and
+timestamps. Nulls are retained. Array order is significant; reordering is a
+reported change, not an inferred semantic equivalence. Paths become strings;
+times use ISO 8601 with nine fractional digits. Image bytes are not compared:
+matching paths do not prove identical photos. No unknown private columns are
+reconstructed. The detached result is deeply frozen; source contacts remain
+mutable and unchanged.
+
+Ordering follows the supplied input order and cross-product traversal. Results
+are deterministic for equivalent ordered inputs, not canonically sorted across
+permutations. Indices are positions in that comparison, not persistent IDs.
+No dates of edits, authors or events between snapshots are inferred.
+
+## Resource and Privacy Limits
+
+Both inputs are materialized. The O(before × after) candidate pass is capped at
+100,000 pairs by default; API callers can explicitly set positive `max_pairs`.
+Oversized comparisons fail before pair evaluation. This is not streaming or an
+enterprise-scale benchmark claim. Live input is read through its existing
+read-only API and consistency limitations, not an atomic historical snapshot.
+
+JSON intentionally includes full contact values, raw identity evidence, paths,
+source identifiers and verification codes already held by the supplied models.
+Treat stdout/results as sensitive; do not send them to untrusted logs or agents.
+Human summaries disclose counts only. Original source archives are never written.
+
+Return to [README](../README.md), [format evidence](ABBU.md), or [API stability](API_STABILITY.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/SNAPSHOT_HISTORY.md

@@ -0,0 +1,93 @@
+<!-- docs/SNAPSHOT_HISTORY.md -->
+
+# Snapshot History
+
+`Abbu::SnapshotHistory.new(paths, strict: false, retention: 2, limits: {}).each`
+streams one transition per supplied archive path. Explicit list order is
+authoritative. `from_directory(path)` selects only immediate directory children
+whose names end in `.abbu`, sorted lexically. Directory names are ordering
+labels, not verified capture times; choose sortable names or supply an ordered
+list. Duplicate expanded paths are rejected; symlink aliases are not resolved.
+
+History uses the public [SnapshotDiff](SNAPSHOT_DIFF.md) contract. Only unique
+probable exact-evidence matches connect observations. Raw labels, source paths,
+all modeled field changes and ambiguity are retained; fuzzy matching is not
+identity. Each connected timeline records first/last observed snapshot references
+and a numeric ID local to this analysis. Re-enumeration starts a fresh analysis.
+
+## Continuity And Gaps
+
+- `first_seen`: first observation in this analysis or after previous evidence
+  was forgotten. It does **not** prove that the contact was newly created.
+- `observed`: an adjacent unique probable comparison. `changes` may be empty.
+- `absent`: previously observed contact has no qualifying candidate in this
+  snapshot. Reported once per absence, not proof of deletion from Apple Contacts.
+- `reappeared`: unique probable match after an observed gap within retention.
+  This means observed again; it does not prove deletion/recreation between files.
+- `ambiguous_start`: competing/weak evidence breaks prior continuity and starts
+  explicitly flagged new timelines. The ambiguous pairs identify prior timeline
+  IDs. Broken old timelines are not kept in the dormant pool for later reconnection.
+
+`retention` is the nonnegative maximum number of absent snapshots to retain a
+contact for possible reappearance matching. Default 2 permits up to two empty
+observations between appearances; 0 discards an absent record immediately.
+After expiry, a return receives a new ID and `first_seen`. The analysis cannot
+distinguish a genuinely new record from forgotten identity evidence. A later
+unambiguous link from an ambiguous-start timeline never repairs its earlier break.
+
+Matching includes current and retained dormant candidates together. Competing
+evidence cannot silently select the active or most recent one. This is an
+observation stream, not a complete contact-index database; consumers can group
+observations by ID to build a per-contact index. Do not coalesce IDs by names.
+
+## JSON Lines Contract
+
+`abbu snapshots-directory --history [--strict]` emits one JSON object per line,
+with `schema_version: 1`, `snapshot`, `observations`, `absent`, `ambiguous` and
+`diagnostics`. `snapshot` has zero-based `index` and expanded `path`.
+Observations expose `timeline_id`, `first_seen`, `last_seen`, `event`, full
+`contact`, field `changes`, `compared_with` (previous observed snapshot or null)
+and `match` (score/evidence or null). Absences carry timeline metadata and
+`observed_at`. Ambiguous pairs retain SnapshotDiff before/after payloads plus
+`before_timeline_id`; their indices refer to that transition's comparison pool,
+not permanent contact identifiers. Observation order follows parser order.
+
+Other CLI modes (including `--json` and live input) are rejected. No snapshots
+emits no lines and exits 0. Argument/parse failures exit 2 through existing CLI
+handling. Diagnostics are included in each transition, not hidden or printed as
+non-JSON stdout. A later failure may leave earlier valid JSON lines: consumers
+must check exit status and must not label a partial stream complete.
+
+Combining history with machine selectors (`--json`, `--matches`, or
+`--diagnostics`) returns the machine contract's structured `invalid_input` error
+before opening inputs. History already emits JSON Lines; these selectors do not
+convert it to a single JSON document. Export and other operation options are
+also rejected before opening snapshots or creating output files.
+
+## Bounded Strategy And Privacy
+
+Default `limits: { snapshots: 100, contacts: 10_000, pairs: 100_000 }` bounds path
+count, current-plus-retained contact count and each comparison's cross-product.
+Unknown keys, nonpositive limits and overflows raise explicitly, never truncate.
+The snapshot count is checked before loading; contact/pool bounds are checked
+after the parser has materialized a single archive. Thus this is not a bound on
+individual archive parsing, contact field sizes or directory listing size.
+
+The reader holds the current archive, bounded current/dormant records and one
+detached transition, not all archives. Consuming `each` incrementally avoids
+accumulating all results; calling `to_a` intentionally retains them. Large sets
+can raise configured limits explicitly, accepting the resulting memory/work cost.
+Synthetic tests cover deterministic order, expiry, reappearance, ambiguity and
+bound failures; no real-world performance or historical completeness is claimed.
+
+Output includes complete personal contact data, labels, source identifiers,
+image paths, verification codes and diagnostic locations. Treat streams as
+sensitive backups, not telemetry. Source archives remain read-only. No edit
+authors, real event timestamps or events between snapshots are reconstructed.
+
+[README](../README.md) · [Snapshot Diff](SNAPSHOT_DIFF.md)
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com