abbu 0.8.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71bd4536cf0e22f9bf9177d5715f4210a84a3b50bcab562266fe4d71c24d831a
-  data.tar.gz: 1bce6e9c3022f814f7ae789c232e8f0d62fe17999cca109cdba16825cea5a7f8
+  metadata.gz: 99f31bf1bbf67088eedcdca46c8a5c90835d3371a93713c7c93c15d571504e4c
+  data.tar.gz: f1bacec2990fcf1c55765377d3985a92faa2be7ea921ecb91b26565e22f8c865
 SHA512:
-  metadata.gz: 378d928ea9d82de3f5ddb54e8f4d9b61e8b14a9cea61225248394e4d665bc8a5c7263a8292af2089acb879b6a0d600dd532fa9a288c5025b36de9c000fab6107
-  data.tar.gz: 573617afdbedd7af5a415dd08f0fb1b2c330d8ccc1bc4d798f0a9febc38eb455b83e292a4c3f25dd30728770fe56a0b97cb65c1acd1e9a13e59df7be43377042
+  metadata.gz: 33b31e1dfe606f52276bc237449714d48fdd11f83c7407ac135679f5cdb928fba56f41259b968d53e1798aa13add86b1e76b1678a6b207a3bdc6637d4d20ac12
+  data.tar.gz: 7516e100a44c66fea179276a7e40cc8f48f1e70bb647f8c0ceaf55840144bf62af01bdf20b0a6e04353c7050ad97c89b4ed3f13abfc7625b3b3818c6a77a417d

data/README.md

@@ -3,8 +3,9 @@
 # abbu
 
 Read-only Apple Contacts toolkit for `.abbu` archives and opt-in live macOS stores.
-Development version 0.8.0 strengthens vCard serialization alongside source-scoped groups, timestamp
-queries, diagnostics, identity evidence, image extraction, and CSV/JSON/vCard export.
+Development version 0.18.0 adds an optional read-only MCP adapter alongside streaming,
+bounded snapshot-history observations,
+portable SQLite, merge previews, snapshot comparison, iCalendar, machine JSON, and queries.
 The public API remains pre-1.0.
 
 ## Features
@@ -272,6 +273,50 @@ See [vCard evidence and compatibility limits](docs/ABBU.md#vcard-serialization-e
 for the standards basis and Apple-specific audit. Synthetic round-trip tests
 are not proof of import fidelity in every Apple Contacts release.
 
+### Portable SQLite
+
+```ruby
+Abbu::Exporters::SqliteExporter.new(archive.contacts).to_file('contacts.sqlite')
+```
+
+```bash
+abbu Contacts.abbu --format sqlite --output contacts.sqlite
+```
+
+This creates a separate, queryable ABBU-owned relational database with schema
+version metadata, source provenance, timestamps, multivalues, groups, and raw
+labels. It does not copy Apple tables or create an Apple-importable backup.
+Existing destinations (including symlinks) are never replaced. Output is a
+sensitive **unencrypted** artifact with owner-only file permissions, not a secure
+storage service; place it on appropriately encrypted storage and limit retention.
+See the [portable SQLite contract](docs/PORTABLE_SQLITE.md) for the schema,
+round-trip evaluation, deterministic-order boundary, and publication safeguards.
+
+### Birthday And Anniversary Calendars
+
+```ruby
+calendar = Abbu::Exporters::IcalendarExporter.new(
+  archive.contacts, year: 2026, generated_at: Time.utc(2026, 10, 1),
+  calendar_id: 'your-unique-calendar-namespace'
+)
+calendar.to_file('reminders.ics')
+calendar.diagnostics # Non-PII omission categories and zero-based contact indexes
+```
+
+```bash
+abbu Contacts.abbu --format icalendar --calendar-year 2026 \
+  --calendar-stamp 2026-10-01T00:00:00Z --calendar-id your-unique-calendar-namespace \
+  --output reminders.ics
+```
+
+The three metadata arguments are explicit so the same ordered input and metadata
+produce identical bytes without inventing a birth year, revision time, or Apple
+identity. Choose your own unique calendar namespace and actual export revision
+time. `year` is the first reminder year, not an original year. Unknown years stay
+unknown, and February 29 reminders recur only in leap years. Lunar/alternate
+calendar dates are diagnosed and omitted, not converted. See the
+[iCalendar contract](docs/ICALENDAR.md) for identity, privacy, and import limits.
+
 ### Duplicate Detection
 
 ```ruby
@@ -299,8 +344,53 @@ merged = matches.first.merge(policy: ->(left, right, evidence:) {
 })
 ```
 
+### Fuzzy Name Suggestions (Ruby)
+
+```ruby
+suggestions = Abbu::Utils::FuzzyMatcher.new(
+  archive.contacts.first, archive.contacts, threshold: 0.85
+).matches
+suggestions.each { |match| pp [match.status, match.score, match.evidence] }
+```
+
+This opt-in API compares one anchor against candidates, not all candidate pairs.
+It preserves parser evidence and existing exact deduplication behavior. See
+[fuzzy matching](docs/FUZZY_MATCHING.md) for score contributions, Unicode rules,
+resource bounds and ambiguity limits. Similarity is not identity.
+
 ## CLI
 
+An opt-in [MCP adapter](docs/MCP.md) exposes public read APIs to a trusted local
+agent host. It requires a separately installed SDK; ordinary ABBU use does not.
+
+### Snapshot History
+
+```ruby
+Abbu::SnapshotHistory.new(['01.abbu', '02.abbu'], retention: 2).each do |transition|
+  pp transition # current observations, absences and ambiguous continuity
+end
+```
+
+`abbu snapshots-directory --history` streams one JSON object per snapshot in
+lexical directory order. See [history semantics and bounds](docs/SNAPSHOT_HISTORY.md).
+Timeline IDs describe this analysis only, never universal contact identities.
+
+### Safe Merge Plans
+
+```ruby
+plan = Abbu::MergePlan.new(left, right, policy: :prefer_newer)
+pp plan.to_h # detached inputs, selected fields, alternatives, conflicts and reasons
+merged = plan.materialize # raises without a policy or with unresolved conflicts
+```
+
+`abbu Contacts.abbu --merge-preview` emits exact-evidence candidate plans as JSON
+without applying them. Optional `--merge-policy prefer_source --prefer-source
+Sources/Example/AddressBook-v22.abcddb` previews an explicit preference. See
+[merge-plan boundaries](docs/MERGE_PLANS.md) before materializing derived contacts.
+
+For shell and agent integrations, see the [machine JSON contract](docs/MACHINE_JSON.md),
+including structured diagnostics, identity suggestions, exit codes, and privacy.
+
 ```bash
 # Export to CSV
 abbu Contacts.abbu -f csv -o contacts.csv
@@ -370,10 +460,47 @@ synthetic shapes from unverified macOS/Contacts releases.
 
 ## Roadmap
 
+Compare archives with `abbu Before.abbu --diff After.abbu --json` or
+`Abbu::SnapshotDiff.new(before, after).to_h`. See the
+[snapshot comparison contract](docs/SNAPSHOT_DIFF.md) for ambiguity, privacy,
+resource limits and field-level evidence.
+
+ABBU remains read-only for source archives and live stores. The
+[writer research decision](docs/WRITER_DECISION.md) explains why generating
+Apple-private bundles is not supported and what evidence could change that.
+
+### Portable vCard Photos
+
+Use `abbu Contacts.abbu --format vcard --photo-mode embedded --output contacts.vcf`
+or `Abbu::Exporters::VcardExporter.new(contacts, photo_mode: :embedded)` to embed
+JPEG, PNG or GIF bytes. The default `:uri` mode is unchanged. Embedded mode uses
+content signatures, not filename extensions, and preserves original bytes and
+contact provenance. It does not decode, validate image integrity, or transcode.
+HEIC and unknown formats are rejected until import compatibility is evidenced.
+Missing/unreadable/unsupported photos raise `ArgumentError` (CLI exit 2) before
+writing output; contacts with no photo evidence omit PHOTO. Export is buffered
+in memory, including base64 expansion. Do not embed untrusted or oversized files.
+
+
 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.
 
+### Streaming Large Archives
+
+Use `archive.each_contact` (also available on live stores) for uncached iteration.
+CSV and vCard exporters accept this enumerable through `write_to(io)`; the new
+`JsonlExporter` writes one existing JSON contact representation per line.
+
+```ruby
+Abbu::Exporters::JsonlExporter.new(Abbu.open('Contacts.abbu').each_contact).write_to($stdout)
+```
+
+CLI: `abbu Contacts.abbu --stream --format csv --output contacts.csv`.
+CSV, JSONL and vCard support streaming; JSONL always streams. Existing buffered
+CSV/JSON/vCard defaults remain unchanged. Streaming can leave partial output on
+late errors, including embedded-photo failures. See [streaming limits and benchmark](docs/STREAMING.md).
+
 ## Ruby Compatibility
 
 `abbu` supports Ruby 3.3 and newer. CI exercises Ruby 3.3, 3.4, and 4.0;

data/bin/abbu

@@ -4,10 +4,14 @@
 
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 
+require 'date'
 require 'json'
 require 'optparse'
+require 'time'
 require 'abbu'
 
+machine_requested = ARGV.include?('--json') || ARGV.include?('--matches') || ARGV.include?('--diagnostics')
+
 options = {
   format: nil,
   output: nil,
@@ -27,14 +31,27 @@ options = {
 parser = OptionParser.new
 parser.banner = 'Usage: abbu <file.abbu> [options] | abbu --live [options] | abbu --live-path PATH [options]'
 
-parser.on('-f', '--format FORMAT', %w[csv json vcard], 'Export format (csv, json, vcard)') do |f|
+parser.on('-f', '--format FORMAT', %w[csv json jsonl sqlite vcard icalendar],
+          'Export format (csv, json, jsonl, sqlite, vcard, icalendar)') do |f|
   options[:format] = f
 end
 
+parser.on('--stream', 'Stream CSV/JSONL/vCard; errors may leave partial output') { options[:stream] = true }
+
+parser.on('--calendar-year YEAR', Integer, 'First reminder year (not a birth year)') { |v| options[:calendar_year] = v }
+parser.on('--calendar-stamp TIME', 'Export revision time in ISO 8601 with timezone') do |v|
+  options[:calendar_stamp] = v
+end
+parser.on('--calendar-id ID', 'Unique caller-owned calendar namespace') { |v| options[:calendar_id] = v }
+
 parser.on('-o', '--output FILE', 'Output file (default: stdout)') do |o|
   options[:output] = o
 end
 
+parser.on('--photo-mode MODE', %w[uri embedded], 'vCard photos: uri (default) or embedded') do |mode|
+  options[:photo_mode] = mode.to_sym
+end
+
 parser.on('--extract-images DIR', 'Copy contact images to DIR') do |dir|
   options[:extract_images] = dir
 end
@@ -43,10 +60,28 @@ parser.on('--stats', 'Print contact statistics') do
   options[:stats] = true
 end
 
+parser.on('--diff PATH', 'Compare this input with another archive; optional --json') do |path|
+  options[:diff] = path
+end
+
+parser.on('--history', 'Analyze a directory of .abbu snapshots as JSON Lines') do
+  options[:history] = true
+end
+
 parser.on('--dedupe', 'Find and print duplicate contacts') do
   options[:dedupe] = true
 end
 
+parser.on('--merge-preview', 'Preview exact-evidence merge plans as JSON; never apply') do
+  options[:merge_preview] = true
+end
+parser.on('--merge-policy POLICY', 'Explicit merge policy for the preview') do |policy|
+  options[:merge_policy] = policy.to_sym
+end
+parser.on('--prefer-source PATH', 'Exact source relative_path for prefer_source policy') do |path|
+  options[:prefer_source] = path
+end
+
 parser.on('--search TERM', 'Find contacts by partial name or email') do |term|
   options[:search] = term
 end
@@ -75,10 +110,18 @@ parser.on('--phone NUMBER', 'Find contacts by exact normalized phone number') do
   options[:phone] = number
 end
 
-parser.on('--json', 'Emit search results as JSON (optional for --sources or --groups)') do
+parser.on('--json', 'Emit a single JSON document for the selected operation (default: contacts)') do
   options[:json] = true
 end
 
+parser.on('--matches', 'Emit provenance-aware identity suggestions as JSON; never merges') do
+  options[:matches] = true
+end
+
+parser.on('--diagnostics', 'Parse contacts and emit parser diagnostics as JSON') do
+  options[:diagnostics] = true
+end
+
 timestamp_bounds = %w[since before]
 %w[created modified].each do |kind|
   timestamp_bounds.each do |bound|
@@ -91,12 +134,12 @@ timestamp_bounds = %w[since before]
 end
 
 parser.on('-v', '--version', 'Print version') do
-  puts "abbu #{Abbu::VERSION}"
+  puts(machine_requested ? JSON.generate(version: Abbu::VERSION) : "abbu #{Abbu::VERSION}")
   exit
 end
 
 parser.on('-h', '--help', 'Print this help') do
-  puts parser
+  puts(machine_requested ? JSON.generate(help: parser.to_s) : parser)
   exit
 end
 
@@ -108,7 +151,16 @@ parser.on('--live-path PATH', 'Read the specified live AddressBook directory') d
   options[:live_path] = path
 end
 
-parser.parse!
+begin
+  parser.parse!
+rescue OptionParser::ParseError => e
+  raise unless machine_requested
+
+  puts JSON.generate(error: { code: 'invalid_option', message: e.message })
+  exit 2
+end
+
+exit Abbu::MachineCommand.new(options, ARGV).run if machine_requested
 
 live_mode = options[:live] || !options[:live_path].nil?
 live_path = options[:live_path]
@@ -142,6 +194,69 @@ at_exit do
 end
 
 begin
+  if options[:history]
+    allowed = %i[history strict]
+    raise ArgumentError, '--history supports only directory input and --strict' if
+      options.any? { |key, value| value && !allowed.include?(key) } || ARGV.any?
+
+    Abbu::SnapshotHistory.from_directory(file, strict: options[:strict]).each do |transition|
+      puts JSON.generate(transition)
+    end
+    exit 0
+  end
+
+  if options[:stream] && (!%w[csv jsonl vcard].include?(options[:format]) ||
+     options.values_at(:extract_images, :schema, :search, :email, :phone, :json, :date_filters,
+                       :sources, :groups, :stats, :dedupe, :diff, :merge_preview, :merge_policy,
+                       :prefer_source, :calendar_year, :calendar_stamp, :calendar_id).any?)
+    raise ArgumentError, '--stream requires only CSV, JSONL or vCard export options'
+  end
+
+  if options[:format] == 'sqlite'
+    conflicts = options.values_at(:stats, :dedupe, :search, :email, :phone, :schema, :extract_images,
+                                  :date_filters, :sources, :groups, :json, :photo_mode).any?
+    if options[:output].nil? || conflicts
+      raise ArgumentError, 'standalone --format sqlite requires --output FILE and no other operation'
+    end
+  end
+  Abbu::MergePreview.validate!(options)
+  if options[:diff]
+    unless options.values_at(:format, :output, :photo_mode, :extract_images, :stats, :dedupe, :schema,
+                             :sources, :groups, :search, :email, :phone, :date_filters,
+                             :calendar_year, :calendar_stamp, :calendar_id).compact.none? { |v| v }
+      raise ArgumentError, '--diff supports only --json, --strict and input selection'
+    end
+
+    archive = if live_mode
+                Abbu.open_live(live_path, strict: options[:strict])
+              else
+                Abbu.open(file, strict: options[:strict])
+              end
+    after = Abbu.open(options[:diff], strict: options[:strict])
+    comparison = Abbu::SnapshotDiff.new(archive, after).to_h
+    %i[added removed changed unchanged ambiguous].each { |kind| puts "#{kind}: #{comparison.fetch(kind).length}" }
+    warn "Comparison input diagnostics: #{after.diagnostics.length}" unless after.diagnostics.empty?
+    exit 0
+  end
+
+  calendar_options = options.values_at(:calendar_year, :calendar_stamp, :calendar_id)
+  if options[:format] == 'icalendar' || calendar_options.any?
+    conflicts = options.values_at(:stats, :dedupe, :search, :email, :phone, :schema, :extract_images,
+                                  :date_filters, :sources, :groups, :json, :photo_mode).any?
+    if options[:format] != 'icalendar' || calendar_options.any?(&:nil?) || conflicts
+      raise ArgumentError, 'standalone --format icalendar requires --calendar-year, --calendar-stamp, and --calendar-id'
+    end
+    unless options[:calendar_stamp].match?(/\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:Z|[+-]\d{2}:\d{2})\z/)
+      raise ArgumentError, '--calendar-stamp requires full ISO 8601 with timezone'
+    end
+
+    Date.iso8601(options[:calendar_stamp].split('T').first)
+  end
+  if options[:photo_mode] && (options[:format] != 'vcard' ||
+     options.values_at(:stats, :dedupe, :search, :email, :phone, :schema, :extract_images, :date_filters).any?)
+    raise ArgumentError, '--photo-mode requires a standalone --format vcard export'
+  end
+
   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?)
@@ -164,6 +279,12 @@ begin
   end
   archive = live_mode ? Abbu.open_live(live_path, strict: options[:strict]) : Abbu.open(file, strict: options[:strict])
 
+  if options[:merge_preview]
+    plans = Abbu::MergePreview.plans(archive.contacts, policy: options[:merge_policy], source: options[:prefer_source])
+    puts JSON.pretty_generate(plans)
+    exit 0
+  end
+
   if listing.any?
     puts JSON.pretty_generate(archive.public_send(listing.first).map(&:to_h))
     exit 0
@@ -247,6 +368,22 @@ begin
     exit
   end
 
+  if options[:stream]
+    contacts = archive.each_contact
+    exporter = case options[:format]
+               when 'csv' then Abbu::Exporters::CsvExporter.new(contacts)
+               when 'jsonl' then Abbu::Exporters::JsonlExporter.new(contacts)
+               when 'vcard'
+                 Abbu::Exporters::VcardExporter.new(contacts, photo_mode: options.fetch(:photo_mode, :uri))
+               end
+    if options[:output]
+      File.open(options[:output], 'wb') { |io| exporter.write_to(io) }
+    else
+      exporter.write_to($stdout)
+    end
+    exit 0
+  end
+
   case options[:format]
   when 'csv'
     exporter = Abbu::Exporters::CsvExporter.new(archive.contacts)
@@ -254,9 +391,24 @@ begin
   when 'json'
     exporter = Abbu::Exporters::JsonExporter.new(archive.contacts)
     options[:output] ? exporter.to_file(options[:output]) : exporter.to_stdout
+  when 'jsonl'
+    exporter = Abbu::Exporters::JsonlExporter.new(archive.each_contact)
+    options[:output] ? exporter.to_file(options[:output]) : exporter.to_stdout
+  when 'sqlite'
+    begin
+      Abbu::Exporters::SqliteExporter.new(archive.contacts).to_file(options[:output])
+    rescue SystemCallError, SQLite3::Exception, JSON::GeneratorError => e
+      raise ArgumentError, "SQLite export failed (#{e.class}); no destination was replaced"
+    end
   when 'vcard'
-    exporter = Abbu::Exporters::VcardExporter.new(archive.contacts)
+    exporter = Abbu::Exporters::VcardExporter.new(archive.contacts, photo_mode: options.fetch(:photo_mode, :uri))
+    options[:output] ? exporter.to_file(options[:output]) : exporter.to_stdout
+  when 'icalendar'
+    metadata = { year: options[:calendar_year], generated_at: Time.iso8601(options[:calendar_stamp]),
+                 calendar_id: options[:calendar_id] }
+    exporter = Abbu::Exporters::IcalendarExporter.new(archive.contacts, **metadata)
     options[:output] ? exporter.to_file(options[:output]) : exporter.to_stdout
+    exporter.diagnostics.each { |d| warn "Calendar #{d[:category]}: contact #{d[:contact_index]}, #{d[:field]}" }
   else
     puts parser
     exit 1

data/bin/abbu-mcp

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# bin/abbu-mcp
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'optparse'
+require 'abbu'
+
+options = {}
+parser = OptionParser.new do |config|
+  config.banner = 'Usage: abbu-mcp ARCHIVE | abbu-mcp --live-path DIRECTORY [--strict]'
+  config.on('--live-path PATH', 'Explicit opt-in live store (read-only)') { |path| options[:live_path] = path }
+  config.on('--strict', 'Fail on unsupported or corrupt optional input') { options[:strict] = true }
+  config.on('-h', '--help', 'Show help, without opening Contacts data') do
+    puts config
+    exit
+  end
+end
+
+begin
+  parser.parse!
+  if options[:live_path] ? ARGV.any? : ARGV.length != 1
+    raise ArgumentError, 'Select exactly one archive or explicit live path'
+  end
+
+  require 'abbu/mcp'
+  Abbu::Mcp::Server.new(path: options[:live_path] || ARGV.first,
+                        live: !options[:live_path].nil?, strict: options[:strict] || false).open
+rescue LoadError
+  warn 'abbu-mcp: install the optional mcp SDK (~> 1.6.1) in the same Ruby environment.'
+  exit 2
+rescue OptionParser::ParseError, ArgumentError, Abbu::LiveStore::Error, SystemCallError
+  warn 'abbu-mcp: invalid configuration or unavailable input; check --help and local permissions.'
+  exit 2
+end

data/docs/ABBU.md

@@ -420,6 +420,34 @@ separate compatibility gate before broader claims.
 
 ## Repository Evidence
 
+- [Portable normalized SQLite](PORTABLE_SQLITE.md) writes an ABBU-owned derived
+  schema from public contacts, preserving source and raw multivalue evidence.
+  It does not copy private tables, infer Apple IDs, convert calendar semantics,
+  or claim Apple import compatibility. XML and SQLite source immutability is tested.
+
+- [iCalendar export](ICALENDAR.md) consumes existing normalized birthday and
+  anniversary fields. Synthetic SQLite and plist regressions preserve raw labels
+  and source bytes; they introduce no private-calendar mapping or Apple import
+  certification. Explicit lunar/alternate values are diagnosed and omitted.
+
+- [Alternate-calendar evidence boundary](ALTERNATE_CALENDAR_EVIDENCE.md): legacy
+  lunar labels/components do not establish a calendar, leap month or year cycle.
+
+- [History evidence boundary](HISTORY_EVIDENCE.md): record timestamps, snapshot
+  differences and documented framework change events are not interchangeable.
+
+- [My Card evidence boundary](MY_CARD_EVIDENCE.md): a public framework query is
+  not an archive schema mapping; no designation is inferred from contact values.
+
+- [Writer decision](WRITER_DECISION.md): current evidence does not justify
+  constructing Apple-private archives. Read compatibility is not import proof;
+  future proposals require isolated, version-attributed import evidence.
+- Embedded vCard PHOTO follows [RFC 2426 §3.1.4](https://www.rfc-editor.org/rfc/rfc2426#section-3.1.4)
+  binary/base64 serialization with existing CRLF folding. Synthetic signature
+  regressions prove byte preservation, not image decodability or Apple import
+  certification. JPEG/PNG/GIF are supported; HEIC embedding is explicitly rejected.
+  This introduces no new Apple image lookup or private-schema assumptions.
+
 - [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.

data/docs/ALTERNATE_CALENDAR_EVIDENCE.md

@@ -0,0 +1,82 @@
+<!-- docs/ALTERNATE_CALENDAR_EVIDENCE.md -->
+
+# Alternate Calendars: Preserve Uncertainty
+
+Research date: 2026-10-01. Issue [#36](https://github.com/scarver2/abbu/issues/36).
+Proposed outcome: insufficient private-format evidence for new calendar,
+leap-month or year-cycle decoding. Existing Gregorian and legacy lunar accessors
+remain unchanged; this is documentation, not a conversion feature.
+
+## What Apple Documents
+
+Apple's public [birthday property](https://developer.apple.com/documentation/contacts/cncontact/birthday)
+uses Gregorian date components with required month/day and optional year.
+The [non-Gregorian birthday property](https://developer.apple.com/documentation/contacts/cncontact/nongregorianbirthday)
+requires a non-Gregorian calendar and month/day, with optional year and leap-month
+information. These are framework contracts, not a private SQLite/plist mapping.
+
+The distinction matters: a label containing “LunarBirthday” and three numeric
+components do not establish which calendar, leap-month state, cycle, era or
+conversion rule applies. Do not default an unknown calendar to Chinese, treat
+absence of a leap marker as false, or interpret a year as Gregorian merely
+because its numeric range looks familiar.
+
+Sources were inspected on the research date. No native framework calls,
+real-address-book reads, or Apple import/export experiments were performed.
+Third-party observations would remain hypotheses until independently reproduced.
+
+## Repository Audit at Main `77eaeda`
+
+- `SqliteParser` exposes rows from the known date-component table and selects
+  `lunar_birthday` by the normalized `LunarBirthday` label. Existing tests use a
+  synthetic `_$!<LunarBirthday>!$_` label with year/month/day and retain raw label.
+- `PlistParser#extract_lunar_birthday` accepts a date-like `LunarBirthday` value
+  and reads year/month/day. Its synthetic fixture is not an attributed Apple
+  alternate-calendar export.
+- Neither mapping establishes calendar identifier, leap month, era or year
+  cycle. No reproducible version-attributed mapping for those components is in
+  the [compatibility corpus](FORMAT_COMPATIBILITY.md).
+- Current vCard/CSV/JSON exposure is legacy behavior, not evidence that a target
+  app interprets alternate calendars correctly. Existing tests must remain; do
+  not silently reinterpret or convert those numbers to improve presentation.
+
+The normalized Contact model is not a complete raw database or plist copy.
+Unknown columns/keys are not guaranteed to survive it. Keep original archives
+as evidence; do not claim this docs-only decision makes current parsing lossless
+for unmodeled metadata. Any future recognized representation must preserve its
+original components alongside derived display values before conversion ships.
+
+## Reproduction Gate
+
+1. Use an explicitly approved disposable, unsynced test account with invented
+   contacts. Record exact macOS and Contacts builds, calendar configuration,
+   locale, export method and the UI value entered.
+2. Vary one component at a time: calendar, optional year, leap month, ordinary
+   month, era/cycle where supported, and missing versus false. Include Gregorian
+   controls and dates sharing the same numeric components across calendars.
+3. Observe exports without changing source stores. Capture raw representation,
+   candidate links and original bytes. Record unavailable components as unknown;
+   do not invent keys or table schemas for synthetic fixtures.
+4. Reproduce the mapping independently, then create sanitized minimal fixtures
+   retaining exact observed representation and version provenance. Test custom
+   labels, malformed near-matches, Unicode, sparse/legacy schemas and duplicate
+   records across sources. Keep every existing Gregorian regression passing.
+5. Design raw and interpreted RBS/API fields together. Require explicit calendar
+   identity and supported conversion rules before generating Gregorian dates or
+   recurrences. A future exporter must diagnose or omit unsupported calendar
+   data explicitly, never fabricate an age, date or leap state.
+6. Validate any interchange claim by isolated export/import/re-export testing
+   on each claimed target build; serialization alone is not import evidence.
+
+No additional storage representation is accepted by this research. The outcome
+is to defer decoding until concrete evidence meets these gates, not to remove
+legacy data or declare all lunar support complete. Under the development-train
+directive this evidence boundary resolves the research scope; a new proposal
+must supply the missing reproducible corpus before implementation.
+
+Return to [README](../README.md), [roadmap](TODO.md), or [format evidence](ABBU.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com