abbu 0.4.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e93fb2c992d75b467a430083bd474aef632c6f759ae858653e9b3ed44e261cc9
-  data.tar.gz: f346d67e1789116120ec804881b0f9660d6853c55102557e084d8be78184a0cf
+  metadata.gz: 71bd4536cf0e22f9bf9177d5715f4210a84a3b50bcab562266fe4d71c24d831a
+  data.tar.gz: 1bce6e9c3022f814f7ae789c232e8f0d62fe17999cca109cdba16825cea5a7f8
 SHA512:
-  metadata.gz: ae3d1565ac2203067a1e2da4cb304eba8b112bfbd94b78f65c0a39a58f6a007835da1929fcfbc58cea13fdde43ac23eae1338b77fcf4466b31a2a2f40f31a3a6
-  data.tar.gz: 6a904be665a31a2254c139aced555dfcfd92af6612bec463ad776e5e99f939210954625c5141b17ee095518b0bd85d29f9dbfa795ec0f0ac34a9b8dd8231c6b0
+  metadata.gz: 378d928ea9d82de3f5ddb54e8f4d9b61e8b14a9cea61225248394e4d665bc8a5c7263a8292af2089acb879b6a0d600dd532fa9a288c5025b36de9c000fab6107
+  data.tar.gz: 573617afdbedd7af5a415dd08f0fb1b2c330d8ccc1bc4d798f0a9febc38eb455b83e292a4c3f25dd30728770fe56a0b97cb65c1acd1e9a13e59df7be43377042

data/README.md

@@ -3,8 +3,9 @@
 # abbu
 
 Read-only Apple Contacts toolkit for `.abbu` archives and opt-in live macOS stores.
-Version 0.4.0 adds querying, diagnostics, identity evidence, and safe image extraction
-alongside CSV, JSON, and vCard export. The public API remains pre-1.0.
+Development version 0.8.0 strengthens vCard serialization alongside source-scoped groups, timestamp
+queries, diagnostics, identity evidence, image extraction, and CSV/JSON/vCard export.
+The public API remains pre-1.0.
 
 ## Features
 
@@ -77,11 +78,14 @@ live_contacts = Abbu.open_live("/path/to/AddressBook").contacts
 Live databases are opened with SQLite's read-only mode. The process may require
 Full Disk Access under **System Settings → Privacy & Security → Full Disk Access**.
 Live inputs expose parser `diagnostics` and accept `strict: true` (CLI `--strict`).
-The live CLI supports stats, deduplication, and exports; archive-only search, schema,
+The live CLI supports source/group listing, stats, deduplication, and exports; archive-only search, schema,
 and image-extraction options are rejected explicitly.
 
-Live access does not write Contacts databases. WAL/concurrent-writer consistency
-remains unverified ([#28](https://github.com/scarver2/abbu/issues/28)).
+Live access does not write Contacts databases. Synthetic WAL tests verify committed
+data visibility and read-only access, but a read is **not an atomic snapshot**:
+separate contact/relationship queries can observe different commits, and databases
+are read independently. A LiveStore caches its first contact result; reopen it to
+refresh. See [live-store consistency evidence](docs/ABBU.md#wal-and-concurrent-writer-evidence).
 
 Labeled values expose a normalized `label` for display and retain the source
 value in `raw_label`. For example, `_$!<Mobile>!$_` becomes `Mobile` while the
@@ -104,6 +108,129 @@ Lookup methods return every match as an `Abbu::Query`; they never silently pick
 one contact when the same identifier appears in multiple sources. Returned
 contacts retain their parser-provided source provenance.
 
+### Timestamp queries
+
+```ruby
+archive.query.modified_since('2026-09-01T00:00:00Z').search('stan')
+archive.query.date_range(:created_at, since: '2026-09-01T00:00:00Z',
+                         before: '2026-10-01T00:00:00Z')
+# Also works with explicitly opened live data:
+Abbu::Query.new(Abbu.open_live.contacts).created_since(Time.utc(2026, 9, 1))
+```
+
+Bounds accept `Time` or full ISO 8601 strings with seconds and an explicit `Z`
+or numeric offset. Start (`since`) is inclusive; end (`before`) is exclusive.
+At least one bound is required, and start must precede end. Invalid bounds raise
+`ArgumentError`, including on empty queries. Missing timestamps never match.
+Filters preserve source records and compose with other Query criteria. These are
+observed storage timestamps, not proof of human edits or a complete change feed;
+deletions and changes without timestamps cannot be discovered this way.
+
+```bash
+abbu Contacts.abbu --modified-since 2026-09-01T00:00:00Z --json
+abbu Contacts.abbu --created-since 2026-09-01T00:00:00Z --created-before 2026-10-01T00:00:00Z --search stan --json
+```
+
+All four `--created-since`, `--created-before`, `--modified-since`, and
+`--modified-before` filters can be combined (AND). They use existing search
+TSV/JSON output: status 0 for matches, 1 for no matches, and 2 for invalid bounds
+or incompatible output options. Diagnostics stay on stderr. CLI timestamp queries
+are archive-only, like existing search; use the Ruby Query API for live inputs.
+Do not combine timestamp queries with export, stats, schema, dedupe, or extraction.
+
+### Sources
+
+```ruby
+sources = archive.sources # Frozen Array<Abbu::Source>, sorted by relative_path
+source = sources.first
+source.relative_path # "." for root, or "Sources/<observed identifier>"
+source.identifier    # Raw directory identifier, or nil for root
+source.provider      # nil: never inferred from paths or identifier spelling
+source.files         # Frozen file-level provenance descriptors
+source.contacts.search('stan') # Query over original contacts, no automatic deduplication
+source.group_names   # Sorted unique observed membership labels, not group identities
+source.to_h          # Metadata, files, contact_count, group_names; no contact payload
+
+Abbu.open_live('/path/to/AddressBook').sources # Same API, read-only connections
+```
+
+Sources are observed input containers, not verified Apple account identities.
+Existing `contact.source` hashes are unchanged. Membership is based on the exact
+file provenance path; repeated contact IDs and filenames in different sources
+never merge. Files from the same observed source directory form one container.
+An empty discovered database still appears; an empty archive returns `[]`.
+Plist records outside `Sources/` form the root container. Archives retain their
+existing SQLite-first parser selection: ignored plist files are not listed.
+
+Source metadata, file descriptors, membership arrays, and group-name strings are
+frozen snapshots. Contacts remain the original mutable objects. `sources` eagerly
+parses contacts, honors diagnostics/strict mode, and is cached; reopen the input to
+refresh. It does not add live-store atomic snapshot guarantees. Group names cover
+observed contact memberships only, not empty groups or same-name group identity.
+
+```bash
+abbu Contacts.abbu --sources
+abbu --live-path /path/to/AddressBook --sources --json
+```
+
+`--sources` always emits a JSON array to stdout; `--json` is optional. Each object
+has `path`, `relative_path`, `kind`, `identifier`, `provider`, `files`,
+`contact_count`, and `group_names`; unknown `provider` and root `identifier` are
+explicit JSON nulls. `files` uses the existing four-key contact provenance schema.
+Source/file ordering is by relative path; contact order is parser order within
+those sorted files. Listings exit 0 even when empty. Conflicting operations or
+strict parse failures exit 2, live input/access failures exit 1, and diagnostics
+stay on stderr. Only `--strict` and `--json` may accompany this operation besides
+input selection. Paths, raw identifiers, and group names may be sensitive;
+do not publish source listings as sanitized logs.
+
+### Groups
+
+```ruby
+group = archive.groups.first # Frozen Array<Abbu::Group>
+group.record_id              # Observed SQLite group key, local to group.source[:path]
+group.name                   # Original name, including whitespace/Unicode; may be nil
+group.source                 # Frozen file-level provenance, including source identifier
+group.contacts.search('stan') # Query over the original mutable contacts
+archive.groups_for(archive.contacts.first) # Reverse lookup, without changing Contact#groups
+archive.sources.first.groups # Same objects, scoped to that source
+archive.query.where(company: 'Acme Corp').in_group(group)
+Abbu.open_live('/path/to/AddressBook').groups # Same API, read-only
+```
+
+Groups are identified by database path plus observed record key, never by name.
+Same-name groups within a file and repeated keys across files/sources remain
+distinct. `Contact#groups` remains the original array of labels (including duplicate
+or null names); `Contact#group_memberships` additionally retains `{ record_id:, name: }`
+for each observed join row, including duplicates. Group contacts list each original
+contact once. Existing contact JSON/CSV/vCard output is unchanged.
+
+Only groups reached by supported contact membership joins are listed. Empty or
+unreferenced groups, dangling joins, and legacy plist group relationships are not
+enumerated; no semantics are inferred for them. Missing optional membership tables
+retain tolerant diagnostics and strict-mode errors. Ordering is source relative
+path, file relative path, then numeric record key; contacts retain parser order.
+
+Metadata and membership snapshots are frozen when sources/groups are first built;
+contacts themselves remain mutable. Later edits to contact labels/evidence do not
+rewrite these snapshots. `groups_for` and `Query#in_group` use original contact
+object identity: a contact freshly parsed by another input instance does not
+belong to this snapshot, even for the same path. Reopen to refresh; live reads
+retain the consistency limitations described above.
+
+```bash
+abbu Contacts.abbu --groups
+abbu --live-path /path/to/AddressBook --groups --json
+```
+
+`--groups` emits a JSON array of `record_id` (integer), `name` (string or null),
+`source` (the four-key file provenance hash), and `contact_count` (integer).
+`Group#to_h` uses the same schema. Names are never normalized. Empty results exit 0;
+strict failures and conflicting operations exit 2; live access failures exit 1.
+Only input selection, `--strict`, and optional `--json` may accompany this mode;
+`--sources` and `--groups` cannot be combined. Diagnostics stay on stderr.
+Group names, IDs and source paths may be sensitive; this is not sanitized logging.
+
 ### Export
 
 ```ruby
@@ -117,6 +244,34 @@ Abbu::Exporters::JsonExporter.new(archive.contacts).to_file("contacts.json")
 Abbu::Exporters::VcardExporter.new(archive.contacts).to_file("contacts.vcf")
 ```
 
+vCard output uses UTF-8, CRLF endings (including the final line), escaped TEXT
+values, and folding at no more than 75 bytes without splitting UTF-8 characters.
+Repeated fields retain order. `N` and `ADR` escape each component independently.
+Text newline variants become vCard `\\n`; URL/IM URI values use percent encoding
+instead of TEXT escaping. Empty contact input emits no bytes.
+
+Labeled emails, phones, addresses, URLs, IM handles, and anniversaries pair with
+`itemN.X-ABLABEL` using the same per-card `itemN` group. The original `raw_label`
+wins over the display `label`, including empty strings. Custom labels no longer
+become arbitrary `TYPE` parameters. Only exact ASCII standard type names are
+recognized, case-insensitively; email/phone defaults are `INTERNET`/`VOICE`.
+For example, `Mobile` is preserved as a label, not guessed to mean `CELL`.
+No preference is invented for anniversaries. Existing photo file URIs remain;
+embedded photos are separate work.
+
+Migration from 0.7: consumers must unfold CRLF continuations before parsing,
+decode TEXT escapes, and accept grouped property names rather than matching
+literal lines such as `EMAIL;TYPE=Work`. The exporter signatures are unchanged.
+Unsupported controls, invalid UTF-8, unsafe social-service parameter tokens,
+or invalid IM service schemes fail explicitly before writing output; export
+does not sanitize or mutate Contact evidence. Other encoding conversions may
+raise Ruby encoding errors. Existing files are overwritten on a successful
+`to_file`, as before; this is not an atomic/no-clobber writer.
+
+See [vCard evidence and compatibility limits](docs/ABBU.md#vcard-serialization-evidence)
+for the standards basis and Apple-specific audit. Synthetic round-trip tests
+are not proof of import fidelity in every Apple Contacts release.
+
 ### Duplicate Detection
 
 ```ruby
@@ -209,9 +364,15 @@ rake abbu:stats[Contacts.abbu]
 See [`docs/ABBU.md`](docs/ABBU.md) for a full explanation of the archive structure,
 SQLite table schema, and format history.
 
+The [compatibility regression matrix](docs/FORMAT_COMPATIBILITY.md) protects
+legacy XML and varied SQLite layouts in every CI run, and distinguishes tested
+synthetic shapes from unverified macOS/Contacts releases.
+
 ## Roadmap
 
 See [`docs/TODO.md`](docs/TODO.md) for the full release schedule and feature checklist.
+The [pre-1.0 API stability gate](docs/API_STABILITY.md) inventories supported
+surfaces, evidence gaps, compatibility policy, and required release-readiness checks.
 
 ## Ruby Compatibility
 

data/bin/abbu

@@ -59,6 +59,14 @@ parser.on('--schema', 'Print SQLite schema diagnostics as JSON') do
   options[:schema] = true
 end
 
+parser.on('--sources', 'List observed source containers as JSON (archive or live)') do
+  options[:sources] = true
+end
+
+parser.on('--groups', 'List observed groups with memberships as JSON (archive or live)') do
+  options[:groups] = true
+end
+
 parser.on('--email ADDRESS', 'Find contacts by exact normalized email') do |address|
   options[:email] = address
 end
@@ -67,10 +75,21 @@ parser.on('--phone NUMBER', 'Find contacts by exact normalized phone number') do
   options[:phone] = number
 end
 
-parser.on('--json', 'Emit search results as structured JSON instead of TSV') do
+parser.on('--json', 'Emit search results as JSON (optional for --sources or --groups)') do
   options[:json] = true
 end
 
+timestamp_bounds = %w[since before]
+%w[created modified].each do |kind|
+  timestamp_bounds.each do |bound|
+    parser.on("--#{kind}-#{bound} TIMESTAMP", "Filter #{kind} timestamp (ISO 8601 with timezone)") do |value|
+      options[:date_filters] ||= {}
+      options[:date_filters][:"#{kind}_at"] ||= {}
+      options[:date_filters][:"#{kind}_at"][bound.to_sym] = value
+    end
+  end
+end
+
 parser.on('-v', '--version', 'Print version') do
   puts "abbu #{Abbu::VERSION}"
   exit
@@ -123,12 +142,33 @@ at_exit do
 end
 
 begin
-  if live_mode && options.values_at(:extract_images, :schema, :search, :email, :phone, :json).any?
-    warn '--live supports --stats, --dedupe, --format, and --strict; archive-only options are not supported.'
+  listing = %i[sources groups].select { |key| options[key] }
+  if listing.any? && (listing.length > 1 || options.values_at(:extract_images, :schema, :search, :email, :phone,
+                                                              :date_filters, :stats, :dedupe, :format, :output).any?)
+    raise ArgumentError,
+          "--#{listing.first} cannot be combined with other operations; only --json and --strict are supported"
+  end
+
+  if live_mode && listing.empty? &&
+     options.values_at(:extract_images, :schema, :search, :email, :phone, :json, :date_filters).any?
+    warn '--live supports --sources, --groups, --stats, --dedupe, --format, and --strict; ' \
+         'archive-only options are not supported.'
     exit 1
   end
+  if options[:date_filters]
+    if options.values_at(:extract_images, :schema, :stats, :dedupe, :format, :output).any?
+      raise ArgumentError, 'timestamp filters cannot be combined with export, stats, schema, dedupe, or extraction'
+    end
+
+    options[:date_filters].each { |field, bounds| Abbu::TimestampRange.new(field, **bounds) }
+  end
   archive = live_mode ? Abbu.open_live(live_path, strict: options[:strict]) : Abbu.open(file, strict: options[:strict])
 
+  if listing.any?
+    puts JSON.pretty_generate(archive.public_send(listing.first).map(&:to_h))
+    exit 0
+  end
+
   if options[:extract_images]
     result = archive.extract_images(options[:extract_images])
     puts "Extracted #{result.files.count} image(s) to #{File.expand_path(options[:extract_images])}"
@@ -149,20 +189,26 @@ begin
     exit 1
   end
 
-  if options[:json] && search_options.empty?
-    warn '--json requires --search, --email, or --phone.'
+  if options[:json] && search_options.empty? && !options[:date_filters]
+    warn '--json requires --search, --email, or --phone (or a timestamp filter).'
     exit 1
   end
 
-  if search_options.any?
+  if search_options.any? || options[:date_filters]
     results = if options[:search]
                 archive.search(options[:search])
               elsif options[:email]
                 archive.find_by_email(options[:email])
-              else
+              elsif options[:phone]
                 archive.find_by_phone(options[:phone])
+              else
+                archive.query
               end
 
+    options.fetch(:date_filters, {}).each do |field, bounds|
+      results = results.date_range(field, **bounds)
+    end
+
     if options[:json]
       Abbu::Exporters::JsonExporter.new(results).to_stdout
     else
@@ -218,7 +264,7 @@ begin
 rescue Abbu::LiveStore::Error => e
   warn "abbu: #{e.message}"
   exit 1
-rescue Abbu::ParseError => e
+rescue Abbu::ParseError, ArgumentError => e
   warn "abbu: #{e.message}"
   exit 2
 end

data/docs/ABBU.md

@@ -125,13 +125,66 @@ Every parsed contact includes source provenance with the absolute source path, i
 relative to the `.abbu` root, and whether it came from the root bundle or a database under
 `Sources/<identifier>/`. Legacy plist contacts receive the same file-level provenance.
 
+### Source container evidence
+
+`Archive#sources` and `LiveStore#sources` group the existing `SourceDescriptor`
+file evidence into root (`.`) and observed `Sources/<identifier>` containers.
+This is ABBU's grouping convention over input paths, not discovery of Apple's
+private account/container tables. It introduces no new storage-column inference.
+Every selected input file appears, including databases with no contacts; files
+in the same observed container are retained individually. Legacy plist files
+outside `Sources/` belong to root. Parser selection and discovery scope are unchanged.
+
+`Source#identifier` preserves the observed directory spelling, while `provider`
+remains nil even for a directory named `iCloud`. Container paths are local identities
+within that opened input, not globally stable IDs across moved archives or snapshots.
+Contacts link through their original file-level `source[:path]`; the source hash
+is neither replaced nor enriched with speculative provider metadata. `group_names`
+reports distinct membership strings only; the group API below preserves identity.
+
+`spec/abbu/source_spec.rb` copies the existing deterministic root database into
+root, `Sources/iCloud`, and `Sources/Équipe`, including two database filenames in
+one container and colliding contact IDs across containers. These fixtures verify
+grouping, provenance preservation and unknown-provider behavior, not an Apple
+account schema. Source listing parses/caches contacts and retains the existing
+strict/tolerant diagnostics and live consistency limitations below.
+
+### Group membership evidence
+
+The existing synthetic fixture joins `Z_ABCDCONTACTGROUP.Z_GROUP` to
+`ZABCDRECORD.Z_PK` and filters memberships by `Z_CONTACT`. The group parser now
+retains that joined key alongside the exact `ZFIRSTNAME` value instead of discarding
+the key. `Contact#group_memberships` preserves every returned join row; the existing
+`Contact#groups` label array and exporters are unchanged. No label normalization
+or inference from other column names is introduced.
+
+`Archive#groups`, `LiveStore#groups`, and `Source#groups` aggregate this evidence by
+absolute database path and record key. Keys are file-local, not global Apple IDs.
+`Group#source` is file provenance; its `identifier` connects to the observed source
+container. Group contacts retain original object identities with repeated joins
+collapsed only in the navigable contact set, not in raw membership evidence.
+Reverse lookup uses `groups_for(contact)` on the input or source; `Query#in_group`
+intersects the caller's contacts with that snapshot without name-based matching.
+
+`spec/abbu/group_spec.rb` extends the deterministic fixture with duplicate joins,
+same-name/different-key groups, null and Unicode names, and repeated keys in root
+and multiple files under `Sources/Équipe`. These establish collision boundaries
+and name preservation through model and JSON output, not a new Apple schema.
+No Apple version is asserted for this synthetic variation.
+
+Only joined groups with parsed contacts are represented. Empty/unreferenced rows,
+dangling joins, and plist group relationships remain unsupported; their semantics
+need separate evidence. Missing membership tables retain existing diagnostics and
+strict-mode behavior. Building groups adds no database reads beyond contact parsing
+and makes no stronger live snapshot guarantee. JSON listings expose raw names and
+file paths and must be treated as sensitive.
+
 ### Opt-in live Contacts stores
 
 The CLI uses `--live` only for auto-discovery and `--live-path PATH` for an explicit
 store. These forms are mutually exclusive and accept no positional archive/path arguments.
-Option ordering does not change input selection. Synthetic WAL-mode and concurrent-writer
-validation remains a follow-up; read-only handles do not establish snapshot consistency
-across an actively changing Contacts store.
+Option ordering does not change input selection. Read-only handles do not establish
+snapshot consistency across an actively changing Contacts store.
 
 `Abbu.open_live` and the CLI's live modes can read an AddressBook directory
 without first exporting an `.abbu` archive. This mode is deliberately separate from
@@ -156,6 +209,41 @@ automatic discovery without a caller-supplied path raises
 
 The repository verifies live-store behavior only with deterministic synthetic SQLite
 fixtures. It does not inspect or commit a developer's real Contacts store.
+
+### WAL and concurrent-writer evidence
+
+`spec/abbu/live_store_wal_spec.rb` copies the existing synthetic root database into
+a temporary directory and opens a separate writer connection in WAL mode. No
+real Contacts data or macOS privacy permission is required. The tests deliberately
+keep the writer open, disable its automatic checkpoint, and interleave operations
+at known boundaries instead of using sleeps or timing races.
+
+The fixture demonstrates that ABBU reads committed WAL changes while the writer
+remains connected. Its database and WAL bytes stay unchanged across the read,
+all ABBU connections use `readonly: true`, and traced statements contain no writes
+or checkpoint requests. An uncommitted writer transaction is not visible. After
+commit, a new LiveStore sees the new value; an existing store retains its cached
+contacts.
+
+There is an important consistency limit: the parser does not enclose all queries
+in a read transaction. A commit between the contact-row SELECT and an email SELECT
+can produce an old name with a new email from the same database. SQLite's snapshot
+isolation applies within a read transaction, not across ABBU's independent
+statements. Multiple database files are also read independently; there is no
+cross-database snapshot guarantee. These tests characterize existing behavior,
+not a new snapshot API or a guarantee for every Contacts/SQLite version.
+
+SQLite uses `-wal` and `-shm` sidecars for WAL operation. Read-only database access
+does not promise that shared-memory lock/index state is byte-for-byte unchanged;
+the tests intentionally do not make that claim. Do not remove sidecars, checkpoint
+a live Contacts database, or copy only its main file to try to obtain a snapshot.
+Use an independently verified consistent export/backup for snapshot-sensitive work.
+Missing/inaccessible sidecar and filesystem-lock behavior remain deployment-specific
+limitations, not behavior established by the writable temporary fixture.
+
+References: [SQLite WAL](https://www.sqlite.org/wal.html) and
+[SQLite isolation](https://www.sqlite.org/isolation.html).
+
 ### Provenance-aware identity evidence
 
 ABBU treats deduplication as a suggestion boundary rather than proof that two records are
@@ -278,8 +366,63 @@ normalizes into the same contact model used by the SQLite parser. Additional
 plist keys or layouts require fixture evidence before they are treated as
 supported semantics.
 
+### vCard serialization evidence
+
+The 0.8.0 exporter implements TEXT escaping and structured components from
+[RFC 2426 §§2.3–2.6](https://www.rfc-editor.org/rfc/rfc2426), and CRLF/grouping
+and unfolding from [RFC 2425 §5.8.1](https://www.rfc-editor.org/rfc/rfc2425).
+ABBU folds conservatively at 75 **octets**, including the continuation space,
+without splitting a UTF-8 code point. Escaping happens before folding; decoding
+must unfold first. Commas, semicolons and backslashes are escaped in TEXT;
+CRLF, bare CR and LF become the logical newline escape. This preserves logical
+text, not the original newline byte convention. Input Contact values are unchanged.
+URI properties use percent encoding, preserving existing escapes and URI
+delimiters rather than applying TEXT rules. This is not a general URI validator.
+
+`spec/abbu/exporters/vcard_exporter_fidelity_spec.rb` contains deterministic
+inline wire fixtures and an independent fixture-only decoder. It exercises
+repeated properties, injection-shaped input, structured names/addresses,
+multiline notes, UTF-8 folding boundaries, per-card group numbering, and both
+SQLite/plist → Contact → vCard label preservation. The temporary SQLite fixture
+only varies an already supported `ZLABEL`; the plist fixture uses the existing
+`Email.values[].label` mapping. Neither adds guessed Apple storage semantics.
+
+The reviewed extension audit is deliberately bounded:
+
+| Surface | Implemented rule / evidence limit |
+| --- | --- |
+| `itemN`, `X-ABLABEL` | Standard group syntax pairs repeated properties with ABBU's existing raw-label extension. Labels remain exact after TEXT decoding; numbering is local to each card, not a stored Apple ID. No Apple import validation is claimed. |
+| `X-ABDATE` | Existing anniversary mapping retained, now grouped with its label. Removed the fabricated `type=pref`. Other date collections remain unsupported by this exporter. |
+| `TYPE`, `PREF` | Only exact ASCII names from RFC 2426's EMAIL/TEL/ADR lists and RFC 4770's IMPP list are recognized from display labels. No whitespace trimming, Unicode folding, custom-label tokenization, or Mobile→CELL guess. Raw labels remain separately available. Explicit `PREF` is recognized; no priority is inferred from row order. |
+| `UID` | Not generated: SQLite keys and source paths are not demonstrated global contact identifiers. |
+| `IMPP` | URI-valued property per [RFC 4770](https://www.rfc-editor.org/rfc/rfc4770). Existing service-to-scheme convention retained with scheme syntax checks and address encoding. A syntactically valid scheme does not prove service interoperability; absent service retains legacy `unknown:`. |
+| `X-SOCIALPROFILE` | Existing service/username extension retained; parameter service must be an ASCII token and username is escaped TEXT. No provider URL or Apple import semantics are inferred. |
+| `ADR` | Seven components, each independently escaped. No new PO box/extended-address storage mapping. Missing label no longer fabricates HOME. |
+| Partial/lunar dates, phonetic names, verification code | Existing extensions retained, not certified as standard vCard 3.0 date forms or Apple alternate-calendar semantics. |
+| `PHOTO` | Existing local file URI retained; portable embedding belongs to #30. |
+
+Unsafe parameter values and control characters fail rather than create extra
+properties or silently discard evidence. Serialization completes before file
+opening/stdout emission, so validation failures produce no partial export and
+leave an existing output file untouched. Filesystem failures after opening can
+still leave partial files. Exports contain sensitive contact values and photo
+paths; callers must choose appropriate destinations and permissions.
+
+Email preference uses `TYPE=INTERNET,PREF`, retaining the default address type
+as required by RFC 2426's email parameter grammar; TEL includes the standard
+`PCS` token. Unknown extension/registered type names are preserved as labels,
+not asserted to be registered by ABBU's deliberately bounded built-in list.
+
+These are standards-backed serialization guarantees and synthetic regression
+observations, not a full-fidelity ABBU backup or certification against a specific
+macOS/Contacts build. A sanitized real Apple export/import corpus remains a
+separate compatibility gate before broader claims.
+
 ## Repository Evidence
 
+- [Compatibility regression matrix](FORMAT_COMPATIBILITY.md): always-on XML,
+  sparse/complete SQLite, root/source/mixed layout profiles and their explicit
+  historical evidence gaps. Filename suffixes are not macOS version guarantees.
 - `spec/fixtures/TestContacts.abbu/` exercises the supported synthetic SQLite,
   nested source, and image-resolution behavior.
 - `spec/fixtures/PlistContacts.abbu/` exercises the supported synthetic legacy