abbu 0.8.1 → 0.18.0

data/docs/STREAMING.md

@@ -0,0 +1,73 @@
+<!-- docs/STREAMING.md -->
+
+# Streaming Contacts
+
+[README](../README.md) · [Format evidence](ABBU.md)
+
+`Archive#each_contact` and `LiveStore#each_contact` return an Enumerator without
+a block, or yield contacts and return the input object with a block. They do not
+read or populate `@contacts`. Existing `contacts`, queries, groups, and sources
+retain their buffered behavior. SQLite rows are consumed through a read-only
+cursor; legacy plist files are parsed one file at a time. Normalization, raw
+labels, provenance, image resolution, and diagnostics use the existing parser
+rules. This is not a new interpretation of Apple's storage schema.
+
+Use block iteration, `first`, or `take` for early termination: unwinding the block
+closes the statement and database, also on consumer exceptions. An externally
+suspended Enumerator (`next`) retains its reader until resumed/unwound or garbage
+collected; do not abandon suspended enumerators expecting immediate closure.
+Live readers are not a cross-source atomic snapshot. A slow consumer retains an
+active SQLite read cursor and may delay WAL checkpoint progress. Repeated calls
+read again and can see newer source state; diagnostics accumulate on the input.
+
+## Export And Safety
+
+CSV and vCard exporters expose `write_to(io)` for any contact Enumerable.
+`JsonlExporter` adds `write_to(io)`, `to_file(path)`, and `to_stdout` using the
+existing JSON contact fields. Caller-owned IO remains open. CLI `--stream`
+accepts standalone CSV, JSONL, or vCard export, including explicit live paths;
+JSONL always streams. Aggregate/search modes are not streaming modes.
+`--stream` also rejects machine JSON modes, snapshot diff, merge options,
+SQLite/iCalendar exports and calendar metadata before reading inputs or opening
+output files. Machine-mode conflicts use the existing structured JSON error contract.
+
+Writes are incremental and **not atomic**: a malformed later record, consumer IO
+failure, or unsupported embedded photo can leave a partial file/stdout stream.
+Use a caller-managed temporary file and rename after success if atomic delivery
+is required. Buffered vCard's pre-output validation guarantee does not extend to
+`write_to`. Protect output as sensitive personal data: JSONL has the same privacy
+surface as JSON, including contact details, local provenance, and stored codes.
+No encryption or anonymization is implied.
+
+Contact retention is bounded when the consumer does not collect results. Total
+memory is not constant: file paths and image indexes scale with the bundle,
+diagnostics can grow, and one contact's values/photo can be large. `to_a`, grouping,
+or buffering output in StringIO forfeits the retention benefit.
+
+## Synthetic Benchmark
+
+Run from a development checkout with mise available on PATH:
+
+```sh
+/usr/bin/time -l bin/benchmark-streaming stream 10000
+/usr/bin/time -l bin/benchmark-streaming buffered 10000
+```
+
+The temporary fixture uses the existing synthetic SQLite schema and 10,000
+name-only contacts, no photos. Six missing-optional-schema diagnostics occur in
+both modes. Timing excludes fixture construction but includes periodic explicit
+GC. Process peak RSS includes setup/runtime; contact counts are sampled after GC
+every 1,000 contacts, not a continuous heap maximum. These are local observations,
+not performance guarantees for real archives.
+
+Observed on macOS with Ruby 3.3.11, 2026-10-01:
+
+| Mode | Iteration seconds | Peak RSS bytes | Sampled live contacts |
+| --- | ---: | ---: | ---: |
+| Streaming | 1.873 | 30,384,128 | 1 |
+| Buffered | 2.681 | 48,254,976 | 10,000 |
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/TODO.md

@@ -141,10 +141,10 @@ Version assignments below 1.0 are intentionally deferred until scopes are accept
 - [ ] [#30](https://github.com/scarver2/abbu/issues/30): embedded vCard photos (currently file URI references)
 - [ ] [#31](https://github.com/scarver2/abbu/issues/31): first-class read-only source objects
 - [ ] [#32](https://github.com/scarver2/abbu/issues/32): first-class groups and membership queries
-- [ ] [#33](https://github.com/scarver2/abbu/issues/33): evidence-backed My Card identification
+- [x] [#33](https://github.com/scarver2/abbu/issues/33): [My Card research — private mapping remains unsupported](MY_CARD_EVIDENCE.md)
 - [ ] [#34](https://github.com/scarver2/abbu/issues/34): modified-since and date-range queries
-- [ ] [#35](https://github.com/scarver2/abbu/issues/35): evidence-backed save/edit history
-- [ ] [#36](https://github.com/scarver2/abbu/issues/36): alternate-calendar and lunar metadata research
+- [x] [#35](https://github.com/scarver2/abbu/issues/35): [history research — no verified private event mapping](HISTORY_EVIDENCE.md)
+- [x] [#36](https://github.com/scarver2/abbu/issues/36): [alternate-calendar research — richer decoding awaits evidence](ALTERNATE_CALENDAR_EVIDENCE.md)
 - [ ] [#37](https://github.com/scarver2/abbu/issues/37): explainable fuzzy names and configurable thresholds
 - [ ] [#38](https://github.com/scarver2/abbu/issues/38): merge plans, side-by-side evidence, and safe built-in policies
 - [ ] [#39](https://github.com/scarver2/abbu/issues/39): broader machine-readable JSON CLI contract
@@ -154,7 +154,7 @@ Version assignments below 1.0 are intentionally deferred until scopes are accept
 - [ ] [#43](https://github.com/scarver2/abbu/issues/43): identity-aware snapshot diffs
 - [ ] [#44](https://github.com/scarver2/abbu/issues/44): history across snapshot directories
 - [ ] [#45](https://github.com/scarver2/abbu/issues/45): optional MCP/agent adapter over read-only interfaces
-- [ ] [#46](https://github.com/scarver2/abbu/issues/46): evidence-backed new-ABBU writer research
+- [x] [#46](https://github.com/scarver2/abbu/issues/46): [no private-schema writer with current evidence](WRITER_DECISION.md)
 - [ ] [#47](https://github.com/scarver2/abbu/issues/47): public API stability checklist
 - [ ] Thumbnail/full-size image selection after reproducible format evidence
 - [ ] Region filtering and an explicit CLI filter grammar

data/docs/WRITER_DECISION.md

@@ -0,0 +1,90 @@
+<!-- docs/WRITER_DECISION.md -->
+
+# Decision: Do Not Generate Apple-Private ABBU Bundles
+
+Date: 2026-10-01. Scope: research issue [#46](https://github.com/scarver2/abbu/issues/46).
+Status: proposed for review; effective when merged. No runtime API or version change.
+
+## Decision
+
+Do not implement an ABBU bundle writer with the evidence currently available.
+Keep source archives and live stores read-only. Do not add `deduplicate!`,
+in-place repair, private SQLite writes, or an archive reconstruction API from
+normalized Contact objects. Continue to offer vCard as the documented contact
+interchange path, with its field limitations explicit. Keep original archives
+as evidence; neither vCard nor normalized JSON is a complete archive backup.
+
+This is a decision about this project's evidence, not a claim that creating
+valid archives is impossible or that no private-format research exists.
+
+## Evidence and Limits
+
+- Apple's [import guide](https://support.apple.com/en-gb/guide/contacts/adrbk1457/mac)
+  documents vCard and ABBU import and warns that archive import replaces current
+  contact information. Its UI instructions are not a bundle-construction schema.
+- Apple's [export guide](https://support.apple.com/guide/contacts/export-or-archive-contacts-adrbdcfd32e6/mac)
+  distinguishes selected-contact vCards from full Contacts archives. Photo and
+  note inclusion can be controlled for vCard exports. This does not establish
+  the fidelity of ABBU's own serializer.
+- Both pages were inspected on 2026-10-01. No Contacts import experiment was
+  performed for this decision; no personal address book was opened or modified.
+- The [compatibility matrix](FORMAT_COMPATIBILITY.md) has synthetic layouts with
+  unknown macOS/Contacts builds. Successful parsing proves those read contracts,
+  not that Contacts accepts a database produced from them.
+- [Format evidence](ABBU.md) describes observed fields and explicit gaps.
+  Unknown private metadata, identifiers, relationships, account state and
+  alternate calendars must not be manufactured from table/column names.
+
+Inference: current read fixtures and public UI documentation are insufficient
+to justify a safe, version-scoped private writer. Renaming exported SQLite to
+`.abcddb` or packaging normalized contacts into an `.abbu` directory would not
+meet the import-evidence requirement.
+
+## Preservation Requirements Before Reconsideration
+
+| Evidence | Required proof, not an assumption |
+| --- | --- |
+| Labels and multivalues | Raw labels, duplicates, order where significant, Unicode, empty and absent values survive; normalization does not replace originals. |
+| Photos | Original bytes and source identity remain available; image relationships and supported encodings are demonstrated. No inferred thumbnail/full-size preference. |
+| Groups and sources | Membership remains source-local; same-name groups and colliding record keys remain distinct. Account/sync identities are never fabricated. |
+| Dates | Unknown years remain unknown; custom labels, alternate calendars and leap metadata remain raw until their semantics are demonstrated. |
+| Provenance | Original snapshot/file identity remains separately traceable; destination keys are not presented as original identities or human-edit timestamps. |
+| Unsupported fields | Every omission has an explicit loss report; unknown private fields cannot silently disappear behind a “lossless” claim. |
+
+Current vCard output does not reconstruct sources/groups/private provenance or
+every date collection. URI photos depend on external paths. Optional embedded
+JPEG/PNG/GIF vCard photos are available, with the documented content-signature,
+memory and unsupported-HEIC limits; embedding does not establish whole-archive
+fidelity. Retain original bytes and use available
+JSON evidence for inspection, not as an assumed reconstruction format.
+
+## Gate for a Future Proposal
+
+1. Obtain explicit approval for isolated import experiments. Use a disposable
+   macOS user or VM with no real contacts or synced accounts; never a user's
+   everyday Contacts store. A backup alone does not make replacement harmless.
+2. Record exact macOS and Contacts builds, export settings, initial synthetic
+   data and schema fingerprints. Record unknowns honestly. Preserve old cases.
+3. Demonstrate a minimal generated bundle importing successfully, then inspect
+   and re-export it. Verify field-level values, raw evidence and losses against
+   the table above; counts alone are insufficient. Repeat for every claimed
+   supported version. Negative/unsupported versions must fail explicitly.
+4. Require a new destination outside every source tree. Stage on the same
+   filesystem and publish atomically with no overwrite, rejecting symlink/path
+   aliases and existing destinations. Test interruption, failures, cleanup and
+   races. Never update a live Contacts database or reuse input files as staging.
+5. Independently review sanitized fixtures, import observations, preservation
+   reports and the safety implementation before introducing a public writer.
+
+These are future acceptance gates, not implemented guarantees. Existing vCard
+`to_file` is not an atomic/no-overwrite archive writer. This decision adds no
+writer, no import automation, no mutation API and no new format claims. Issue
+#46 can close on the explicitly allowed no-writer outcome; new evidence should
+open a new scoped proposal rather than silently reversing this boundary.
+
+Return to [README](../README.md), [roadmap](TODO.md), or [format evidence](ABBU.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/lib/abbu/archive.rb

@@ -27,6 +27,20 @@ module Abbu
       @contacts ||= parser.contacts.tap { |cs| attach_images(cs) }
     end
 
+    def each_contact
+      return enum_for(:each_contact) unless block_given?
+
+      resolver = Utils::ImageResolver.new(@path)
+      parser.each_contact do |contact|
+        if contact.image_uri
+          contact.image_path = resolver.resolve(contact.image_uri, source: contact.source)
+          record_missing_image(contact) unless contact.image_path
+        end
+        yield contact
+      end
+      self
+    end
+
     def query
       Query.new(contacts)
     end

data/lib/abbu/exporters/csv_exporter.rb

@@ -24,6 +24,13 @@ module Abbu
         end)
       end
 
+      def write_to(io)
+        csv = CSV.new(io)
+        csv << headers
+        @contacts.each { |contact| csv << row(contact) }
+        nil
+      end
+
       private
 
       def headers

data/lib/abbu/exporters/icalendar_encoding.rb

@@ -0,0 +1,35 @@
+# lib/abbu/exporters/icalendar_encoding.rb
+# frozen_string_literal: true
+
+module Abbu
+  module Exporters
+    # RFC 5545 TEXT and 75-octet content lines, without splitting UTF-8.
+    module IcalendarEncoding
+      module_function
+
+      def text(value)
+        utf8(value).gsub(/\\|;|,|\r\n|\r|\n/) do |character|
+          character.match?(/[\r\n]/) ? '\\n' : "\\#{character}"
+        end
+      end
+
+      def fold(line)
+        parts = [+'']
+        utf8(line).each_char do |character|
+          parts << +' ' if parts.last.bytesize + character.bytesize > 75
+          parts.last << character
+        end
+        parts.join("\r\n")
+      end
+
+      def utf8(value)
+        string = value.to_s.encode(Encoding::UTF_8)
+        raise ArgumentError, 'iCalendar text has invalid encoding' unless string.valid_encoding?
+        raise ArgumentError, 'iCalendar text contains an unsupported control character' if
+          string.match?(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/)
+
+        string
+      end
+    end
+  end
+end

data/lib/abbu/exporters/icalendar_event.rb

@@ -0,0 +1,61 @@
+# lib/abbu/exporters/icalendar_event.rb
+# frozen_string_literal: true
+
+require 'date'
+
+require_relative 'icalendar_encoding'
+
+module Abbu
+  module Exporters
+    # Internal validation of normalized Gregorian date components only.
+    class IcalendarEvent
+      attr_reader :error
+
+      def initialize(date, year:, kind:)
+        @date = date
+        @year = year
+        @kind = kind
+        @error = validate
+      end
+
+      def lines(name:, uid:, stamp:)
+        label = @date[:raw_label] || @date[:label] || @kind.to_s.capitalize
+        start = occurrence.strftime('%Y%m%d')
+        ['BEGIN:VEVENT', "UID:#{uid}", "DTSTAMP:#{stamp}", "DTSTART;VALUE=DATE:#{start}",
+         'DURATION:P1D', 'RRULE:FREQ=YEARLY', 'TRANSP:TRANSPARENT',
+         "SUMMARY:#{IcalendarEncoding.text("#{name} — #{label}")}",
+         "X-ABBU-YEAR-UNKNOWN:#{unknown_year? ? 'TRUE' : 'FALSE'}",
+         "DESCRIPTION:#{IcalendarEncoding.text(description)}", 'END:VEVENT']
+      end
+
+      private
+
+      def validate
+        return :invalid_date unless @date.is_a?(Hash)
+        return :unsupported_calendar unless [nil, 'gregorian', :gregorian].include?(@date[:calendar])
+
+        values = @date.values_at(:month, :day)
+        year = unknown_year? ? 2000 : @date[:year]
+        return :invalid_date unless [year, *values].all?(Integer) && (1..9999).cover?(year)
+        return :invalid_date unless Date.valid_date?(year, *values, Date::GREGORIAN)
+
+        nil
+      end
+
+      def unknown_year?
+        @date[:year].nil? || (@date[:year].is_a?(Integer) && @date[:year].zero?)
+      end
+
+      def occurrence
+        year = [@year, unknown_year? ? @year : @date[:year]].max
+        year += 1 until Date.valid_date?(year, @date[:month], @date[:day], Date::GREGORIAN)
+        Date.new(year, @date[:month], @date[:day], Date::GREGORIAN)
+      end
+
+      def description
+        origin = unknown_year? ? 'Original year unknown; no age is asserted.' : "Original year: #{@date[:year]}."
+        "ABBU reminder. DTSTART is the recurrence start, not an assertion of birth or marriage year. #{origin}"
+      end
+    end
+  end
+end

data/lib/abbu/exporters/icalendar_exporter.rb

@@ -0,0 +1,86 @@
+# lib/abbu/exporters/icalendar_exporter.rb
+# frozen_string_literal: true
+
+require 'date'
+require 'digest'
+require 'json'
+require 'time'
+
+require_relative 'icalendar_encoding'
+require_relative 'icalendar_event'
+
+module Abbu
+  module Exporters
+    # Derived reminders, not Apple calendar identities or a synchronization feed.
+    class IcalendarExporter
+      attr_reader :diagnostics
+
+      def initialize(contacts, year:, generated_at:, calendar_id:)
+        raise ArgumentError, 'year must be an Integer between 1 and 9996' unless
+          year.is_a?(Integer) && (1..9996).cover?(year)
+        raise ArgumentError, 'calendar_id must be a nonempty String' unless
+          calendar_id.is_a?(String) && !calendar_id.strip.empty?
+
+        @contacts = contacts
+        @year = year
+        @stamp = timestamp(generated_at)
+        @calendar_id = IcalendarEncoding.text(calendar_id)
+        @diagnostics = [].freeze
+      end
+
+      def to_file(path)
+        File.binwrite(path, to_ical)
+      end
+
+      def to_stdout
+        print to_ical
+      end
+
+      def to_ical
+        @diagnostics = []
+        lines = ['BEGIN:VCALENDAR', 'VERSION:2.0', 'PRODID:-//ABBU//Contact Reminders//EN', 'CALSCALE:GREGORIAN']
+        @contacts.each_with_index { |contact, index| append_contact(lines, contact, index) }
+        return '' if lines.length == 4
+
+        lines << 'END:VCALENDAR'
+        "#{lines.map { |line| IcalendarEncoding.fold(line) }.join("\r\n")}\r\n"
+      ensure
+        @diagnostics.freeze
+      end
+
+      private
+
+      def timestamp(value)
+        valid = value.is_a?(Time) && (1..9999).cover?(value.getutc.year)
+        raise ArgumentError, 'generated_at must be a Time with a UTC year between 1 and 9999' unless valid
+
+        value.getutc.strftime('%Y%m%dT%H%M%SZ')
+      end
+
+      def append_contact(lines, contact, index) # rubocop:disable Metrics/MethodLength
+        diagnose(:unsupported_calendar, index, :lunar_birthday) if contact.lunar_birthday
+        %i[birthday anniversary].each do |field|
+          date = contact.public_send(field)
+          next if date.nil?
+
+          event = IcalendarEvent.new(date, year: @year, kind: field)
+          if event.error
+            diagnose(event.error, index, field)
+          else
+            lines.concat(event.lines(name: contact.full_name, uid: uid(contact, index, field), stamp: @stamp))
+          end
+        end
+      end
+
+      def uid(contact, index, field)
+        name = IcalendarEncoding.text(contact.full_name)
+        evidence = [@calendar_id, index, field, contact.source&.fetch(:relative_path, nil), name]
+        "#{Digest::SHA256.hexdigest(JSON.generate(evidence))}@abbu.invalid"
+      end
+
+      def diagnose(category, index, field)
+        @diagnostics << { category: category, contact_index: index, field: field }.freeze
+      end
+    end
+  end
+end

data/lib/abbu/exporters/json_exporter.rb

@@ -19,12 +19,12 @@ module Abbu
         puts JSON.pretty_generate(payload)
       end
 
-      private
-
       def payload
         @contacts.map { |c| contact_hash(c) }
       end
 
+      private
+
       def contact_hash(contact) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         {
           name: contact.full_name,

data/lib/abbu/exporters/jsonl_exporter.rb

@@ -0,0 +1,23 @@
+# lib/abbu/exporters/jsonl_exporter.rb
+# frozen_string_literal: true
+
+require_relative 'json_exporter'
+
+module Abbu
+  module Exporters
+    class JsonlExporter < JsonExporter
+      def write_to(io)
+        @contacts.each { |contact| io.write("#{JSON.generate(contact_hash(contact))}\n") }
+        nil
+      end
+
+      def to_file(path)
+        File.open(path, 'wb') { |io| write_to(io) }
+      end
+
+      def to_stdout
+        write_to($stdout)
+      end
+    end
+  end
+end

data/lib/abbu/exporters/sqlite_exporter.rb

@@ -0,0 +1,85 @@
+# lib/abbu/exporters/sqlite_exporter.rb
+# frozen_string_literal: true
+
+require 'pathname'
+require 'sqlite3'
+require 'tempfile'
+
+require_relative '../version'
+require_relative 'sqlite_rows'
+require_relative 'sqlite_schema'
+
+module Abbu
+  module Exporters
+    # A separate, plaintext derived artifact. Publication never replaces a file.
+    class SqliteExporter
+      SCHEMA_VERSION = SqliteSchema::VERSION
+
+      def initialize(contacts)
+        @contacts = contacts
+      end
+
+      def to_file(path)
+        destination = destination_path(path)
+        contacts = @contacts.to_a
+        check_source_boundaries(contacts, destination)
+        Tempfile.create(['.abbu-export-', '.sqlite'], File.dirname(destination)) do |file|
+          file.close
+          build(file.path, contacts)
+          File.link(file.path, destination)
+        end
+        destination
+      end
+
+      private
+
+      def destination_path(path)
+        expanded = File.expand_path(path)
+        parent = File.realpath(File.dirname(expanded))
+        destination = File.join(parent, File.basename(expanded))
+        raise Errno::EEXIST, destination if File.exist?(destination) || File.symlink?(destination)
+        if [parent, File.dirname(expanded)].any? { |entry| abbu_ancestors(entry).any? }
+          raise ArgumentError, 'SQLite export destination must be outside source ABBU bundles'
+        end
+
+        destination
+      end
+
+      def check_source_boundaries(contacts, destination)
+        contacts.each do |contact|
+          path = contact.source&.fetch(:path, nil)
+          next unless path
+
+          if source_bundles(path).any? { |bundle| destination.start_with?("#{bundle}/") }
+            raise ArgumentError, 'SQLite export destination must be outside source ABBU bundles'
+          end
+        end
+      end
+
+      def source_bundles(path)
+        paths = [File.expand_path(path)]
+        paths << File.realpath(path) if File.exist?(path)
+        paths.flat_map do |entry|
+          abbu_ancestors(entry).map do |ancestor|
+            File.exist?(ancestor) ? File.realpath(ancestor) : ancestor.to_s
+          end
+        end
+      end
+
+      def abbu_ancestors(path)
+        Pathname.new(path).ascend.select { |ancestor| ancestor.extname.downcase == '.abbu' }
+      end
+
+      def build(path, contacts)
+        SQLite3::Database.new(path) do |db|
+          SqliteSchema.create(db)
+          db.transaction do
+            db.execute('INSERT INTO metadata VALUES (?, ?)', [SCHEMA_VERSION, Abbu::VERSION])
+            rows = SqliteRows.new(db)
+            contacts.each_with_index { |contact, index| rows.write(contact, index + 1) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/abbu/exporters/sqlite_rows.rb

@@ -0,0 +1,113 @@
+# lib/abbu/exporters/sqlite_rows.rb
+# frozen_string_literal: true
+
+require 'json'
+require 'pathname'
+require 'time'
+
+require_relative 'sqlite_schema'
+
+module Abbu
+  module Exporters
+    # Writes normalized columns and complete per-entry evidence side by side.
+    class SqliteRows
+      def initialize(db)
+        @db = db
+        @sources = {}
+        @groups = {}
+      end
+
+      def write(contact, id)
+        source_id = source(contact.source)
+        fields = flat_fields(contact)
+        times = [timestamp(contact.created_at), timestamp(contact.modified_at)]
+        insert(:contacts, [id, source_id, *fields.values.map { |value| value&.to_s }, *times, evidence(fields)])
+        collections(contact, id)
+        dates(contact, id)
+        groups(contact, id, source_id)
+      end
+
+      private
+
+      def flat_fields(contact)
+        SqliteSchema::CONTACT_FIELDS.to_h do |field|
+          value = contact.public_send(field)
+          [field, value.is_a?(Pathname) ? value.to_s : value]
+        end
+      end
+
+      def insert(table, values)
+        placeholders = Array.new(values.length, '?').join(', ')
+        @db.execute("INSERT INTO #{table} VALUES (#{placeholders})", values)
+      end
+
+      def evidence(value)
+        JSON.generate(canonical(value))
+      end
+
+      def canonical(value)
+        case value
+        when Hash
+          value.sort_by { |key, _| key.to_s }.to_h.transform_values { |entry| canonical(entry) }
+        when Array
+          value.map { |entry| canonical(entry) }
+        else
+          value
+        end
+      end
+
+      def timestamp(value)
+        value&.iso8601(9)
+      end
+
+      def source(value)
+        return if value.nil?
+
+        json = evidence(value)
+        @sources[json] ||= begin
+          id = @sources.length + 1
+          insert(:sources, [id, *value.values_at(:path, :relative_path, :kind, :identifier), json])
+          id
+        end
+      end
+
+      def collections(contact, id)
+        SqliteSchema::COLLECTIONS.each do |field, columns|
+          contact.public_send(field).each_with_index do |entry, position|
+            insert(field, [id, position, *entry.values_at(*columns), evidence(entry)])
+          end
+        end
+        scalar_values(:notes, contact.notes, id)
+        scalar_values(:group_labels, contact.groups, id)
+      end
+
+      def scalar_values(table, values, id)
+        values.each_with_index { |value, position| insert(table, [id, position, value&.to_s, evidence(value)]) }
+      end
+
+      def dates(contact, id)
+        SqliteSchema::DATE_FIELDS.each do |field|
+          values = field == :dates ? contact.dates : [contact.public_send(field)].compact
+          values.each_with_index do |entry, position|
+            components = entry.values_at(:year, :month, :day, :label, :raw_label)
+            insert(:dates, [id, field.to_s, position, *components, evidence(entry)])
+          end
+        end
+      end
+
+      def groups(contact, id, source_id)
+        contact.group_memberships.each_with_index do |entry, position|
+          json = evidence(entry)
+          # Without source evidence, membership observations stay contact-local.
+          key = [source_id || "contact:#{id}", json]
+          group_id = @groups[key] ||= begin
+            next_id = @groups.length + 1
+            insert(:groups, [next_id, source_id, *entry.values_at(:record_id, :name), json])
+            next_id
+          end
+          insert(:group_memberships, [id, position, group_id])
+        end
+      end
+    end
+  end
+end