feat(import): MacDive SQLite import (Milestone 3 of 4)

Adds direct import from MacDive's Core Data SQLite database, the most
complete MacDive metadata path. Captures the same entity set as MacDive
XML — dives, sites, buddies, tags, and gear inventory — plus per-dive
tank/gas mix linkage from ZTANKANDGAS and per-dive equipmentRefs
linking dives to their gear. Cross-format deduplication via source UUIDs
means re-importing the same dives via MacDive UDDF/XML/SQLite won't
create duplicates.

## What landed

- `ImportFormat.macdiveSqlite` with `MacDive (SQLite)` source override.
- `_detectFormat` extended: SQLite → Shearwater check → MacDive check →
  generic. Single SQLite probe reused across flavors to avoid doubling
  temp-file I/O on large DBs.
- `BPlistDecoder` (Apple binary plist v00) in `lib/core/utils/bplist/`
  — supports dict, array, string (ASCII + UTF-16BE), int (1..8 byte;
  16-byte best-effort low-64-bit), real, bool, null, data, date, and
  NSKeyedArchiver UID markers (1..4 bytes per spec).
- `MacDiveDbReader`: schema validation (required tables enforced up
  front; optional tables read safely), typed row graph, filters null-FK
  tombstones in ZTANKANDGAS.
- `MacDiveDiveMapper`: joins raw rows into a unified `ImportPayload`
  matching M2's key conventions. Emits per-dive `equipmentRefs` so
  `UddfEntityImporter.equipmentIdMapping` can link gear back to dives.
  Gear maps require `name` and carry a stable `uddfId` (MacDive gear
  UUID, with name fallback).
- `MacDiveSqliteParser`: `ImportParser` implementation wrapping reader
  + mapper.
- `ImportDuplicateChecker`: first-pass exact match on `source_uuid`
  via a new `DiveRepository.getSourceUuidByDiveId({diverId})` helper
  that optionally scopes the UUID map to one diver.

## Known limitations

- `ZDIVE.ZSAMPLES` (MacDive's proprietary profile-sample BLOB) is NOT
  decoded. MacDive's format isn't bplist and doesn't match common
  compressions. Users who want profile time-series data should use
  MacDive UDDF import (M1). M3 is the rich-metadata path; UDDF is the
  sample-data path.
- Critters (marine-life sightings), dive events, service records, and
  certifications are read into the typed row graph but not yet emitted
  into the import payload — tracked as follow-up work (the unified
  importer lacks entity types for critters/events/service records).

## Test coverage

- Synthetic-DB tests: reader, mapper, parser (`macdive_db_reader_test`,
  `macdive_dive_mapper_test`, `macdive_sqlite_parser_test`).
- BPlist decoder golden tests (Python-plistlib fixtures + real MacDive
  ZTIMEZONE BLOB). Regression tests for 1/2/4-byte UID indexes.
- Gated real-sample regression against a 6.7MB MacDive.sqlite (enable
  via `MACDIVE_SQLITE_REAL_SAMPLE_PATH`): 540 dives / 373 sites /
  33 buddies / 39 tags / 32 gear, equipmentRefs resolution verified.
- New `dive_repository_new_methods_test` coverage for scoped and
  unscoped `getSourceUuidByDiveId`.

Closes #179.

Author: ericgriffin

CHANGELOG.md

@@ -19,6 +19,15 @@ All notable changes to Submersion are documented in this file.
   internal units at the reader boundary.
 - **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. 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,
   Shearwater Cloud, Subsurface SSRF, and generic UDDF are now preserved on
   the `dive_data_sources` sidecar. Re-importing the same dives in a
@@ -42,6 +51,22 @@ All notable changes to Submersion are documented in this file.
   parsed but not yet persisted to the profile samples table. A future
   milestone will wire them through, likely via the dive-events table.
 
+### Known limitations
+
+- Profile samples (depth/time-series data) are NOT imported from
+  MacDive SQLite. MacDive stores sample data in `ZDIVE.ZSAMPLES`
+  using a proprietary binary format that isn't publicly documented
+  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)
 

docs/superpowers/plans/2026-04-21-macdive-sqlite-import.md

@@ -2,7 +2,13 @@
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
-**Goal:** Import directly from MacDive's Core Data SQLite database (`MacDive.sqlite`). This is the most complete path: tags, critters, events, service records, full relationship graph, and per-dive profile samples encoded as Apple binary plists.
+**Goal:** Import directly from MacDive's Core Data SQLite database (`MacDive.sqlite`). Rich METADATA path — tags, critters, events, service records, full relationship graph, certifications, gear inventory.
+
+**Scope adjustment (discovered during Task 4):** `ZDIVE.ZSAMPLES` is NOT bplist — MacDive uses a proprietary binary format (entropy 7.85 bits/byte, all 256 byte values present — either bit-packed+delta-encoded or compressed with a non-standard algorithm). Tried zlib/gzip/lzma at offsets 0/4/8/12 — nothing works. Reverse-engineering MacDive's sample format is out of M3 scope.
+
+**Consequence:** M3 imports dive metadata only. `profile: []` is emitted for every dive. Users who want profile time-series data can use M1's UDDF import instead (which decodes profiles correctly from MacDive UDDF exports). SQLite import becomes the "rich metadata" path; UDDF remains the "sample data" path.
+
+`ZDIVE.ZTIMEZONE` IS bplist (NSKeyedArchiver format with UID markers) — handled correctly by the bplist decoder from Tasks 1-3.
 
 **Architecture:** Hand-rolled `BPlistDecoder` (binary plist v00) for decoding MacDive's BLOB columns (`ZRAWDATA`, `ZSAMPLES`, `ZTIMEZONE`). New `MacDiveDbReader` modeled on `ShearwaterDbReader` validates the schema and produces typed raw rows. New `MacDiveDiveMapper` joins the rows (dive ↔ site, dive ↔ buddy, dive ↔ tank ↔ gas, dive ↔ tag, dive ↔ critter) and maps them to a unified `ImportPayload`. Pipeline wiring mirrors Shearwater Cloud.
 
@@ -14,6 +20,41 @@
 
 ---
 
+## Milestone 3 Status — COMPLETE
+
+- All 14 tasks landed; bplist decoder (Tasks 1-4) shipped with UID
+  support after real-sample probing revealed NSKeyedArchiver format
+  in ZTIMEZONE.
+- ZSAMPLES profile-sample decoding **descoped** — MacDive uses a
+  proprietary binary format (entropy 7.85 bits/byte; not bplist; not
+  zlib/gzip/lzma at any reasonable offset). Users wanting profile
+  samples should use M1's UDDF import. M3 is the "rich metadata"
+  path; UDDF remains the "sample data" path.
+- New `ImportFormat.macdiveSqlite` + source override. Detector
+  chain: SQLite magic → Shearwater check → MacDive check → generic.
+- `MacDiveDbReader` validates schema (ZDIVE + ZDIVESITE + ZGAS +
+  ZTANKANDGAS) and returns typed row graph keyed by PK; junctions
+  as dive_pk → related_pks maps. Filters null-FK tombstones in
+  ZTANKANDGAS discovered on real data.
+- `MacDiveDiveMapper` reuses M2's `MacDiveUnitConverter` and
+  `MacDiveValueMapper`. Dive map keys match M2's `MacDiveXmlParser`
+  exactly so the same `UddfEntityImporter` downstream consumes
+  both sources uniformly.
+- `ImportDuplicateChecker` now short-circuits on `source_uuid`
+  when incoming dives match existing `dive_data_sources.source_uuid`.
+  Separate parameter map keeps the `Dive` entity unchanged
+  (multi-source-per-dive semantics preserved).
+- Gated `@Tags(['real-data'])` test asserts against user's real
+  6.7MB DB: 540 dives, 373 sites, 33 buddies, 39 tags, 32 gear —
+  all with sourceUuid populated. Profile always empty per descope.
+- Full test suite passes.
+
+Next: M4 (Photos) extends M2's XML parser and M3's SQLite reader
+to emit `imageRefs` on payloads and adds a photo-linking wizard
+step.
+
+---
+
 ## File Structure
 
 | File | Role | New / Modified |

lib/core/utils/bplist/bplist_decoder.dart

@@ -0,0 +1,223 @@
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:submersion/core/utils/bplist/bplist_object.dart';
+
+/// Decoder for Apple binary property list v00 ("bplist00"). Supports
+/// the subset of types observed in MacDive Core Data BLOBs: null,
+/// bool, int (1/2/4/8-byte; 16-byte ints decoded as best-effort from
+/// their low 64 bits with a warning in a comment — MacDive hasn't been
+/// seen to emit them), real (4/8-byte IEEE754), string (ASCII + UTF-16BE),
+/// data, date, dict, array, and CFKeyedArchiver UID refs. Sets throw
+/// FormatException.
+class BPlistDecoder {
+  final Uint8List _bytes;
+  final int _offsetIntSize;
+  final int _objectRefSize;
+  final int _offsetTableOffset;
+
+  BPlistDecoder._(
+    this._bytes, {
+    required int offsetIntSize,
+    required int objectRefSize,
+    required int offsetTableOffset,
+  }) : _offsetIntSize = offsetIntSize,
+       _objectRefSize = objectRefSize,
+       _offsetTableOffset = offsetTableOffset;
+
+  /// Entry point: decode [bytes] into the root [BPlistObject].
+  /// Throws [FormatException] if [bytes] is not a valid bplist00 stream
+  /// or uses unsupported type markers (sets).
+  static BPlistObject decode(Uint8List bytes) {
+    if (bytes.length < 8 + 32) {
+      throw const FormatException('bplist00 stream too short');
+    }
+    // Magic: bytes 0..7 must equal "bplist00".
+    const magic = [0x62, 0x70, 0x6C, 0x69, 0x73, 0x74, 0x30, 0x30];
+    for (var i = 0; i < 8; i++) {
+      if (bytes[i] != magic[i]) {
+        throw const FormatException('not a bplist00 stream');
+      }
+    }
+
+    final trailer = bytes.length - 32;
+    final offsetIntSize = bytes[trailer + 6];
+    final objectRefSize = bytes[trailer + 7];
+    final topObjectIndex = _readBigEndianInt(bytes, trailer + 16, 8);
+    final offsetTableOffset = _readBigEndianInt(bytes, trailer + 24, 8);
+
+    final decoder = BPlistDecoder._(
+      bytes,
+      offsetIntSize: offsetIntSize,
+      objectRefSize: objectRefSize,
+      offsetTableOffset: offsetTableOffset,
+    );
+    return decoder._readObject(topObjectIndex);
+  }
+
+  int _offsetOfObject(int index) {
+    final pos = _offsetTableOffset + index * _offsetIntSize;
+    return _readBigEndianInt(_bytes, pos, _offsetIntSize);
+  }
+
+  BPlistObject _readObject(int index) {
+    final offset = _offsetOfObject(index);
+    final marker = _bytes[offset];
+    final type = marker >> 4;
+    final info = marker & 0x0F;
+
+    switch (type) {
+      case 0x0: // singletons
+        return switch (info) {
+          0x0 => const BPlistNull(),
+          0x8 => const BPlistBool(false),
+          0x9 => const BPlistBool(true),
+          _ => throw FormatException(
+            'unknown bplist singleton marker 0x${marker.toRadixString(16)}',
+          ),
+        };
+
+      case 0x1: // int
+        // info bits 0..3 encode log2(byteCount): 0->1, 1->2, 2->4, 3->8, 4->16.
+        // 16-byte ints are decoded as a best-effort truncation to the low
+        // 64 bits: Dart's `int` is 64-bit on native platforms, and the
+        // `(value << 8) | byte` accumulator in `_readBigEndianInt` silently
+        // drops the high bytes once the value overflows — which for a big-
+        // endian read keeps exactly the low 64 bits of the source integer.
+        // MacDive has not been seen to emit 16-byte ints in practice.
+        final byteCount = 1 << info;
+        return BPlistInt(_readBigEndianInt(_bytes, offset + 1, byteCount));
+
+      case 0x2: // real
+        final byteCount = 1 << info;
+        return BPlistReal(_readBigEndianReal(_bytes, offset + 1, byteCount));
+
+      case 0x3: // date — always 8-byte big-endian IEEE754
+        return BPlistDate(_readBigEndianReal(_bytes, offset + 1, 8));
+
+      case 0x4: // data
+        final li = _readLenAndStart(offset, info);
+        return BPlistData(
+          Uint8List.sublistView(_bytes, li.start, li.start + li.length),
+        );
+
+      case 0x5: // ASCII string
+        final li = _readLenAndStart(offset, info);
+        return BPlistString(
+          ascii.decode(
+            _bytes.sublist(li.start, li.start + li.length),
+            allowInvalid: true,
+          ),
+        );
+
+      case 0x6: // UTF-16BE string; length is char count
+        final li = _readLenAndStart(offset, info);
+        return BPlistString(_decodeUtf16Be(_bytes, li.start, li.length));
+
+      case 0xA: // array
+        final li = _readLenAndStart(offset, info);
+        final refs = <int>[];
+        for (var i = 0; i < li.length; i++) {
+          refs.add(
+            _readBigEndianInt(
+              _bytes,
+              li.start + i * _objectRefSize,
+              _objectRefSize,
+            ),
+          );
+        }
+        return BPlistArray(refs.map(_readObject).toList(growable: false));
+
+      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);
+        final keys = <int>[];
+        final values = <int>[];
+        for (var i = 0; i < li.length; i++) {
+          keys.add(
+            _readBigEndianInt(
+              _bytes,
+              li.start + i * _objectRefSize,
+              _objectRefSize,
+            ),
+          );
+        }
+        for (var i = 0; i < li.length; i++) {
+          values.add(
+            _readBigEndianInt(
+              _bytes,
+              li.start + (li.length + i) * _objectRefSize,
+              _objectRefSize,
+            ),
+          );
+        }
+        final map = <String, BPlistObject>{};
+        for (var i = 0; i < li.length; i++) {
+          final key = _readObject(keys[i]);
+          if (key is! BPlistString) {
+            throw FormatException(
+              'bplist dict key at index $i is not a string',
+            );
+          }
+          map[key.value] = _readObject(values[i]);
+        }
+        return BPlistDict(map);
+
+      default:
+        throw FormatException(
+          'unsupported bplist marker 0x${marker.toRadixString(16)}',
+        );
+    }
+  }
+
+  /// Decodes a length field that appears inline in a marker byte or, for
+  /// info == 0x0F, as a trailing integer marker followed by the int bytes.
+  /// Returns the length and the start offset of the payload data.
+  _LenAndStart _readLenAndStart(int markerOffset, int info) {
+    if (info != 0x0F) {
+      return _LenAndStart(info, markerOffset + 1);
+    }
+    final intMarker = _bytes[markerOffset + 1];
+    if ((intMarker >> 4) != 0x1) {
+      throw FormatException(
+        'expected int marker after 0x0F length, got 0x${intMarker.toRadixString(16)}',
+      );
+    }
+    final intByteCount = 1 << (intMarker & 0x0F);
+    final length = _readBigEndianInt(_bytes, markerOffset + 2, intByteCount);
+    return _LenAndStart(length, markerOffset + 2 + intByteCount);
+  }
+
+  static int _readBigEndianInt(Uint8List bytes, int offset, int size) {
+    var value = 0;
+    for (var i = 0; i < size; i++) {
+      value = (value << 8) | bytes[offset + i];
+    }
+    return value;
+  }
+
+  static double _readBigEndianReal(Uint8List bytes, int offset, int size) {
+    final bd = ByteData.sublistView(bytes, offset, offset + size);
+    if (size == 4) return bd.getFloat32(0, Endian.big);
+    if (size == 8) return bd.getFloat64(0, Endian.big);
+    throw FormatException('unsupported bplist real size: $size');
+  }
+
+  static String _decodeUtf16Be(Uint8List bytes, int start, int charCount) {
+    final units = <int>[];
+    for (var i = 0; i < charCount; i++) {
+      final offset = start + i * 2;
+      units.add((bytes[offset] << 8) | bytes[offset + 1]);
+    }
+    return String.fromCharCodes(units);
+  }
+}
+
+class _LenAndStart {
+  final int length;
+  final int start;
+  const _LenAndStart(this.length, this.start);
+}