fix(macdive-sqlite): address PR #256 review (UID width, reader guards, UUID scoping)

- bplist: UID now reads 1-4 bytes big-endian per spec (low nibble =
  byteCount - 1); regression tests added for 1/2/4-byte indexes and the
  BPlistUID docstring now matches the decoder.
- MacDive DB reader: wrap optional-table reads (_readBuddies / _readTags
  / _readGear / _readTanks) in _selectOrEmpty so missing tables yield
  empty collections, matching the docstring; docstring tightened to
  call out the required/optional split explicitly.
- dive_repository.getSourceUuidByDiveId: optional diverId parameter
  that joins to dives.diver_id, matching the scope the
  universal_adapter already uses for existingDives. 4 targeted tests.
- CHANGELOG: rewrote the MacDive SQLite entry to describe only what
  actually ships (dives/sites/buddies/tags/gear plus per-dive tank/gas
  linkage); added a Known Limitations bullet for the
  critters/events/service-records/certifications gap. Inline code
  comments in the mapper document why dive dateTime follows M2's
  absolute-UTC convention and why diveToGearPks is collected-but-not-
  emitted, both tracked as cross-parser follow-up work.
- real-sample test: replaced hard-coded dev path with
  MACDIVE_SQLITE_REAL_SAMPLE_PATH env var; group-level skip with a
  clear reason when unset; StateError guard for --run-skipped.
- synthetic fixture: ZTANKANDGAS UUIDs renamed tag-uuid-* to
  tankandgas-uuid-*.
- Regenerated 9 mock files for the new diverId parameter.

Author: ericgriffin

CHANGELOG.md

@@ -20,12 +20,12 @@ All notable changes to Submersion are documented in this file.
 - **MacDive (XML) source override** in the import wizard's detected-source
   dropdown, alongside the existing MacDive (CSV) option.
 - **MacDive SQLite import.** Direct import from MacDive's Core Data
-  SQLite database — the most complete metadata path. Captures dives,
-  sites, buddies, tags (as with XML), gear inventory, critters/marine
-  life sightings, dive events, service records, and certifications.
-  Cross-format deduplication via source UUIDs: if you've already
-  imported the same dives via MacDive UDDF or XML, re-importing from
-  SQLite won't create duplicates.
+  SQLite database. Captures the same entity set as MacDive XML — dives,
+  sites, buddies, tags, and gear inventory — plus per-dive tank and gas
+  mix linkage drawn from the `ZTANKANDGAS` join table. Cross-format
+  deduplication via source UUIDs: if you've already imported the same
+  dives via MacDive UDDF or XML, re-importing from SQLite won't create
+  duplicates.
 - **MacDive (SQLite) source override** in the import wizard's
   detected-source dropdown, alongside MacDive (CSV) and MacDive (XML).
 - Cross-format import deduplication: stable per-dive UUIDs from MacDive,
@@ -59,6 +59,13 @@ All notable changes to Submersion are documented in this file.
   and isn't standard bplist or any common compression. Users who
   need time-series profile data should use the MacDive UDDF import
   path instead, which decodes MacDive's UDDF profile correctly.
+- The MacDive SQLite path reads critters (marine-life sightings),
+  dive events, service records, and certifications into its typed
+  row graph, but these are not yet emitted into the import payload —
+  the unified importer doesn't have entity types for critters,
+  events, or service records, and certification emission is scoped
+  for a follow-up. For now, only the dive/site/buddy/tag/gear subset
+  is persisted.
 
 
 ## 1.4.6 (2026-04-22)

lib/core/utils/bplist/bplist_decoder.dart

@@ -122,8 +122,9 @@ class BPlistDecoder {
         }
         return BPlistArray(refs.map(_readObject).toList(growable: false));
 
-      case 0x8: // UID — CFKeyedArchiver reference (always 1 byte)
-        return BPlistUID(_bytes[offset + 1]);
+      case 0x8: // UID — CFKeyedArchiver reference (1..4 bytes; info encodes byteCount - 1)
+        final byteCount = info + 1;
+        return BPlistUID(_readBigEndianInt(_bytes, offset + 1, byteCount));
 
       case 0xD: // dict
         final li = _readLenAndStart(offset, info);

lib/core/utils/bplist/bplist_object.dart

@@ -59,9 +59,11 @@ class BPlistDict extends BPlistObject {
   const BPlistDict(this.value);
 }
 
-/// CFKeyedArchiver UID: a 1-byte reference to another object in the
-/// archive's object table. Used in NSKeyedArchiver-encoded Core Data
-/// blobs to represent cross-references between objects.
+/// CFKeyedArchiver UID: a big-endian reference to another object in the
+/// archive's object table. The bplist marker's low nibble encodes
+/// `byteCount - 1`, so the index field is 1..4 bytes wide. Used in
+/// NSKeyedArchiver-encoded Core Data blobs to represent cross-references
+/// between objects.
 class BPlistUID extends BPlistObject {
   final int index;
   const BPlistUID(this.index);

lib/features/dive_log/data/repositories/dive_repository_impl.dart

@@ -3561,21 +3561,35 @@ class DiveRepository {
   /// has multiple data sources (multi-computer), the primary row's UUID wins;
   /// otherwise the most recently created row's UUID is used. Dives with no
   /// source_uuid on any row are absent from the map.
-  Future<Map<String, String>> getSourceUuidByDiveId() async {
+  ///
+  /// When [diverId] is provided, the result is restricted to that diver's
+  /// dives — callers that have already scoped `existingDives` to a single
+  /// diver should pass it here so the UUID map shares the same scope.
+  Future<Map<String, String>> getSourceUuidByDiveId({String? diverId}) async {
     try {
-      final query = _db.select(_db.diveDataSources)
-        ..where((t) => t.sourceUuid.isNotNull())
-        ..orderBy([
-          (t) => OrderingTerm.desc(t.isPrimary),
-          (t) => OrderingTerm.desc(t.createdAt),
-        ]);
-      final rows = await query.get();
+      final sql = StringBuffer('SELECT s.dive_id, s.source_uuid ')
+        ..write('FROM dive_data_sources s ');
+      final variables = <Variable<Object>>[];
+      if (diverId != null) {
+        sql.write('INNER JOIN dives d ON d.id = s.dive_id ');
+      }
+      sql.write('WHERE s.source_uuid IS NOT NULL ');
+      if (diverId != null) {
+        sql.write('AND d.diver_id = ? ');
+        variables.add(Variable<Object>(diverId));
+      }
+      sql.write('ORDER BY s.is_primary DESC, s.created_at DESC');
+
+      final rows = await _db
+          .customSelect(sql.toString(), variables: variables)
+          .get();
       final result = <String, String>{};
       for (final row in rows) {
-        final uuid = row.sourceUuid;
+        final diveId = row.read<String>('dive_id');
+        final uuid = row.read<String?>('source_uuid');
         if (uuid == null || uuid.isEmpty) continue;
         // First row wins (ordered by isPrimary DESC then createdAt DESC).
-        result.putIfAbsent(row.diveId, () => uuid);
+        result.putIfAbsent(diveId, () => uuid);
       }
       return result;
     } catch (e, stackTrace) {

lib/features/import_wizard/data/adapters/universal_adapter.dart

@@ -296,7 +296,9 @@ class UniversalAdapter implements ImportSourceAdapter {
     final existingDiveTypes = await _ref.refresh(diveTypesProvider.future);
     final diveRepo = _ref.read(diveRepositoryProvider);
     final existingDives = await diveRepo.getAllDives(diverId: diverId);
-    final existingSourceUuidByDiveId = await diveRepo.getSourceUuidByDiveId();
+    final existingSourceUuidByDiveId = await diveRepo.getSourceUuidByDiveId(
+      diverId: diverId,
+    );
 
     final dupResult = checker.check(
       payload: payload,

lib/features/universal_import/data/services/macdive_db_reader.dart

@@ -44,9 +44,12 @@ class MacDiveDbReader {
   }
 
   /// Reads every MacDive table relevant to the import pipeline and
-  /// returns a fully populated [MacDiveRawLogbook]. Missing/unpopulated
-  /// tables (e.g. `ZCRITTER` when the user logs no marine-life
-  /// sightings) produce empty collections rather than errors.
+  /// returns a fully populated [MacDiveRawLogbook]. The four tables in
+  /// [_requiredTables] are validated up-front and must exist. For every
+  /// other table (e.g. `ZCRITTER`, `ZBUDDY`, `ZGEARITEM`), a missing or
+  /// unpopulated table produces an empty collection rather than an
+  /// error — some MacDive schema versions omit tables the user has
+  /// never touched.
   static Future<MacDiveRawLogbook> readAll(Uint8List bytes) async {
     final tmpPath = _tmpPath();
     final tmpFile = File(tmpPath);
@@ -155,28 +158,34 @@ class MacDiveDbReader {
   }
 
   static List<MacDiveRawBuddy> _readBuddies(Database db) {
-    return db.select('SELECT Z_PK, ZUUID, ZNAME FROM ZBUDDY').map((r) {
-      return MacDiveRawBuddy(
+    return _selectOrEmpty<MacDiveRawBuddy>(
+      db,
+      'SELECT Z_PK, ZUUID, ZNAME FROM ZBUDDY',
+      (r) => MacDiveRawBuddy(
         pk: r['Z_PK'] as int,
         uuid: _str(r['ZUUID']) ?? '',
         name: _str(r['ZNAME']),
-      );
-    }).toList();
+      ),
+    );
   }
 
   static List<MacDiveRawTag> _readTags(Database db) {
-    return db.select('SELECT Z_PK, ZUUID, ZNAME FROM ZTAG').map((r) {
-      return MacDiveRawTag(
+    return _selectOrEmpty<MacDiveRawTag>(
+      db,
+      'SELECT Z_PK, ZUUID, ZNAME FROM ZTAG',
+      (r) => MacDiveRawTag(
         pk: r['Z_PK'] as int,
         uuid: _str(r['ZUUID']) ?? '',
         name: _str(r['ZNAME']),
-      );
-    }).toList();
+      ),
+    );
   }
 
   static List<MacDiveRawGear> _readGear(Database db) {
-    return db.select('SELECT * FROM ZGEARITEM').map((r) {
-      return MacDiveRawGear(
+    return _selectOrEmpty<MacDiveRawGear>(
+      db,
+      'SELECT * FROM ZGEARITEM',
+      (r) => MacDiveRawGear(
         pk: r['Z_PK'] as int,
         uuid: _str(r['ZUUID']) ?? '',
         name: _str(r['ZNAME']),
@@ -191,21 +200,23 @@ class MacDiveDbReader {
         notes: _str(r['ZNOTES']),
         url: _str(r['ZURL']),
         warranty: _str(r['ZWARRANTY']),
-      );
-    }).toList();
+      ),
+    );
   }
 
   static List<MacDiveRawTank> _readTanks(Database db) {
-    return db.select('SELECT * FROM ZTANK').map((r) {
-      return MacDiveRawTank(
+    return _selectOrEmpty<MacDiveRawTank>(
+      db,
+      'SELECT * FROM ZTANK',
+      (r) => MacDiveRawTank(
         pk: r['Z_PK'] as int,
         uuid: _str(r['ZUUID']) ?? '',
         name: _str(r['ZNAME']),
         size: _double(r['ZSIZE']),
         workingPressure: _double(r['ZWORKINGPRESSURE']),
         type: _str(r['ZTYPE']),
-      );
-    }).toList();
+      ),
+    );
   }
 
   static List<MacDiveRawGas> _readGases(Database db) {

lib/features/universal_import/data/services/macdive_dive_mapper.dart

@@ -159,6 +159,15 @@ class MacDiveDiveMapper {
 
     if (d.uuid.isNotEmpty) map['sourceUuid'] = d.uuid;
     if (d.identifier != null) map['sourceIdentifier'] = d.identifier;
+    // `rawDate` is an absolute UTC DateTime derived from ZRAWDATE (NSDate
+    // reference seconds). MacDive stores the per-dive zone separately in
+    // `ZTIMEZONE` as an NSKeyedArchiver-encoded NSTimeZone. Emitting
+    // rawDate directly matches M2 (`macdive_xml_parser.dart`) and reads
+    // back correctly as long as the diver views the dive from the same
+    // zone in which they dove. A cross-parser move to the wall-time-as-UTC
+    // convention (cf. `subsurface_xml_parser.dart`) requires NSTimeZone
+    // extraction for M3 and structured-date emission for M1/M2 — tracked
+    // as follow-up work, not folded into this PR.
     if (d.rawDate != null) map['dateTime'] = d.rawDate;
     if (d.diveNumber != null) map['diveNumber'] = d.diveNumber;
     if (d.repetitiveDiveNumber != null) {
@@ -245,6 +254,14 @@ class MacDiveDiveMapper {
     ];
     if (buddyNames.isNotEmpty) map['unmatchedBuddyNames'] = buddyNames;
 
+    // Per-dive gear linkage (`logbook.diveToGearPks`) is read but not
+    // emitted: the unified import payload currently has no dive→gear
+    // reference convention (`equipmentRefs` isn't recognised by the
+    // entity importer), and M2 behaves identically — gear is imported
+    // as standalone equipment entities dedup'd across all dives. Wiring
+    // dive↔gear links end-to-end is a cross-parser change tracked as
+    // follow-up work.
+
     // Tags - emit names under `tagRefs`.
     final tagPks = logbook.diveToTagPks[d.pk] ?? const <int>[];
     final tagNames = <String>[

test/core/utils/bplist/bplist_decoder_test.dart

@@ -113,6 +113,54 @@ void main() {
     });
   });
 
+  group('BPlistDecoder — multi-byte UID markers', () {
+    // Synthetic bplist: root = UID(index). The decoder must honor the
+    // bplist spec's `byteCount = (marker & 0x0F) + 1` rule so archives
+    // with > 255 objects (e.g. large NSKeyedArchiver graphs) decode
+    // correctly. Regression test for the 1-byte-only bug.
+    Uint8List buildBplistWithRootUid(List<int> uidBytes) {
+      final marker = 0x80 | (uidBytes.length - 1);
+      final body = <int>[marker, ...uidBytes];
+      const bodyOffset = 8;
+      final offsetTableOffset = bodyOffset + body.length;
+      const numObjects = 1;
+      const topObject = 0;
+      final trailer = <int>[
+        0, 0, 0, 0, 0, 0, // unused / sortVersion
+        1, // offsetIntSize
+        1, // objectRefSize
+        0, 0, 0, 0, 0, 0, 0, numObjects, // numObjects (u64 BE)
+        0, 0, 0, 0, 0, 0, 0, topObject, // topObject (u64 BE)
+        0, 0, 0, 0, 0, 0, 0, offsetTableOffset, // offsetTableOffset (u64 BE)
+      ];
+      return Uint8List.fromList([
+        0x62, 0x70, 0x6C, 0x69, 0x73, 0x74, 0x30, 0x30, // "bplist00"
+        ...body,
+        bodyOffset, // offset table: one entry pointing at body
+        ...trailer,
+      ]);
+    }
+
+    test('decodes 2-byte UID index (e.g. object 256)', () {
+      final bytes = buildBplistWithRootUid(const [0x01, 0x00]);
+      final result = BPlistDecoder.decode(bytes);
+      expect(result, isA<BPlistUID>());
+      expect((result as BPlistUID).index, 256);
+    });
+
+    test('decodes 4-byte UID index', () {
+      final bytes = buildBplistWithRootUid(const [0x00, 0x01, 0x00, 0x00]);
+      final result = BPlistDecoder.decode(bytes);
+      expect((result as BPlistUID).index, 0x00010000);
+    });
+
+    test('still decodes the common 1-byte case', () {
+      final bytes = buildBplistWithRootUid(const [0x2A]);
+      final result = BPlistDecoder.decode(bytes);
+      expect((result as BPlistUID).index, 42);
+    });
+  });
+
   group('BPlistDecoder — real MacDive ZTIMEZONE BLOB', () {
     late BPlistObject root;
 

test/features/dive_computer/data/services/dive_import_service_test.mocks.dart

@@ -993,9 +993,9 @@ class MockDiveRepository extends _i1.Mock implements _i4.DiveRepository {
           as _i7.Future<List<_i16.DiveDataSource>>);
 
   @override
-  _i7.Future<Map<String, String>> getSourceUuidByDiveId() =>
+  _i7.Future<Map<String, String>> getSourceUuidByDiveId({String? diverId}) =>
       (super.noSuchMethod(
-            Invocation.method(#getSourceUuidByDiveId, []),
+            Invocation.method(#getSourceUuidByDiveId, [], {#diverId: diverId}),
             returnValue: _i7.Future<Map<String, String>>.value(
               <String, String>{},
             ),

test/features/dive_import/data/services/uddf_entity_importer_test.mocks.dart

@@ -2058,9 +2058,9 @@ class MockDiveRepository extends _i1.Mock implements _i13.DiveRepository {
           as _i17.Future<List<_i35.DiveDataSource>>);
 
   @override
-  _i17.Future<Map<String, String>> getSourceUuidByDiveId() =>
+  _i17.Future<Map<String, String>> getSourceUuidByDiveId({String? diverId}) =>
       (super.noSuchMethod(
-            Invocation.method(#getSourceUuidByDiveId, []),
+            Invocation.method(#getSourceUuidByDiveId, [], {#diverId: diverId}),
             returnValue: _i17.Future<Map<String, String>>.value(
               <String, String>{},
             ),