bottomtime 0.1.0__py3-none-any.whl

bottomtime/__init__.py

@@ -0,0 +1,7 @@
+"""bottomtime: lossless dive-log store for multi-computer divers."""
+
+__version__ = "0.1.0"
+
+from .api import list_dives, load_dive
+
+__all__ = ["load_dive", "list_dives", "__version__"]

bottomtime/api.py

@@ -0,0 +1,88 @@
+"""Small read API for analysis code.
+
+    import bottomtime
+    dive = bottomtime.load_dive("data/dives.db", 291)
+    dive["sources"]["garmin"]["samples"]["depth_m"]
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+_SAMPLE_TABLES = {"garmin": "garmin_samples", "shearwater": "shearwater_samples"}
+
+
+def _columns_of(con: sqlite3.Connection, table: str) -> list[str]:
+    return [r[1] for r in con.execute(f"PRAGMA table_info({table})")]
+
+
+def load_dive(db_path: str | Path, dive_number: int) -> dict:
+    """Load one canonical dive with every member source log's samples as
+    column-oriented lists (ready for plotting / DataFrame construction)."""
+    con = sqlite3.connect(db_path)
+    con.row_factory = sqlite3.Row
+    try:
+        dive = con.execute(
+            "SELECT * FROM dives WHERE dive_number=?", (dive_number,)
+        ).fetchone()
+        if dive is None:
+            raise KeyError(f"no dive with number {dive_number}")
+        out = {k: dive[k] for k in dive.keys()}
+        out["sources"] = {}
+        members = con.execute(
+            "SELECT sd.* FROM source_dives sd JOIN dive_members dm"
+            " ON dm.source_dive_id = sd.id WHERE dm.dive_id=?",
+            (dive["id"],),
+        ).fetchall()
+        for sd in members:
+            table = _SAMPLE_TABLES[sd["source"]]
+            cols = [c for c in _columns_of(con, table) if c != "source_dive_id"]
+            rows = con.execute(
+                f"SELECT {', '.join(cols)} FROM {table}"
+                " WHERE source_dive_id=? ORDER BY t_s",
+                (sd["id"],),
+            ).fetchall()
+            samples = {c: [r[i] for r in rows] for i, c in enumerate(cols)}
+            entry = {
+                "source_dive_id": sd["id"],
+                "source_key": sd["source_key"],
+                "start_time_utc": sd["start_time_utc"],
+                "start_time_local": sd["start_time_local"],
+                "duration_s": sd["duration_s"],
+                "max_depth_m": sd["max_depth_m"],
+                "mode": sd["mode"],
+                "header": json.loads(sd["header_json"]),
+                "samples": samples,
+            }
+            key = sd["source"]
+            if key in out["sources"]:  # several logs from one source (splits)
+                existing = out["sources"][key]
+                if isinstance(existing, list):
+                    existing.append(entry)
+                else:
+                    out["sources"][key] = [existing, entry]
+            else:
+                out["sources"][key] = entry
+        return out
+    finally:
+        con.close()
+
+
+def list_dives(db_path: str | Path, include_tests: bool = False) -> list[dict]:
+    con = sqlite3.connect(db_path)
+    con.row_factory = sqlite3.Row
+    try:
+        where = "" if include_tests else "WHERE d.is_test = 0"
+        return [
+            {k: r[k] for k in r.keys()}
+            for r in con.execute(
+                "SELECT d.*, group_concat(sd.source) AS sources FROM dives d"
+                " JOIN dive_members dm ON dm.dive_id = d.id"
+                " JOIN source_dives sd ON sd.id = dm.source_dive_id"
+                f" {where} GROUP BY d.id ORDER BY d.start_time_utc"
+            )
+        ]
+    finally:
+        con.close()

bottomtime/cli.py

@@ -0,0 +1,107 @@
+"""bottomtime command line interface.
+
+    bottomtime init
+    bottomtime ingest garmin <fit-dir>
+    bottomtime ingest shearwater <dive_data.db>
+    bottomtime match
+    bottomtime verify [--xml-dir DIR]
+    bottomtime status
+
+All commands are idempotent: re-running an ingest skips anything already
+stored (content-hash keyed), match recomputes only 'auto' links.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .store import db as store_db
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="bottomtime")
+    parser.add_argument("--db", default="data/dives.db", help="path to the dive store")
+    parser.add_argument(
+        "--archive", default="archive", help="directory for verbatim raw source copies"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("init", help="create an empty dive store")
+
+    p_ingest = sub.add_parser("ingest", help="ingest a data source")
+    ingest_sub = p_ingest.add_subparsers(dest="source", required=True)
+    p_garmin = ingest_sub.add_parser("garmin", help="a directory of FIT files")
+    p_garmin.add_argument("fit_dir", type=Path)
+    p_garmin.add_argument(
+        "--index",
+        default="dives_index.json",
+        help="Garmin Connect index JSON filename inside fit-dir",
+    )
+    p_sw = ingest_sub.add_parser("shearwater", help="a Shearwater Cloud dive_data.db")
+    p_sw.add_argument("db_path", type=Path)
+
+    sub.add_parser("match", help="match dual-computer dives, build canonical dives")
+
+    p_verify = sub.add_parser("verify", help="run the verification suite")
+    p_verify.add_argument("--xml-dir", type=Path, default=None,
+                          help="directory of Shearwater XML exports to cross-check")
+
+    sub.add_parser("status", help="summarize the store")
+
+    args = parser.parse_args(argv)
+    con = store_db.connect(args.db)
+    archive_dir = Path(args.archive)
+
+    if args.command == "init":
+        print(f"initialized {args.db}")
+        return 0
+
+    if args.command == "ingest" and args.source == "garmin":
+        from .ingest.garmin_fit import ingest_garmin_dir
+
+        stats = ingest_garmin_dir(con, archive_dir, args.fit_dir, args.index)
+        print(f"garmin: {stats}")
+        return 1 if stats["failed"] else 0
+
+    if args.command == "ingest" and args.source == "shearwater":
+        from .ingest.shearwater_db import ingest_shearwater_db
+
+        stats = ingest_shearwater_db(con, archive_dir, args.db_path)
+        print(f"shearwater: {stats}")
+        return 1 if stats["failed"] else 0
+
+    if args.command == "match":
+        from .match.matcher import run_match
+
+        stats = run_match(con)
+        print(f"match: {stats}")
+        return 0
+
+    if args.command == "verify":
+        from .verify.crosscheck import run_verify
+
+        return run_verify(con, args.xml_dir)
+
+    if args.command == "status":
+        for line in con.execute(
+            "SELECT source || ' source dives: ' || count(*) FROM source_dives GROUP BY source"
+        ):
+            print(line[0])
+        for line in con.execute(
+            "SELECT 'canonical dives: ' || count(*) || ' (' ||"
+            " sum(CASE WHEN is_test THEN 1 ELSE 0 END) || ' test)' FROM dives"
+        ):
+            print(line[0])
+        for line in con.execute(
+            "SELECT 'matched pairs: ' || count(*) FROM matches WHERE status IN ('auto','confirmed')"
+        ):
+            print(line[0])
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bottomtime/decode/__init__.py

@@ -0,0 +1 @@
+

bottomtime/decode/pnf.py

@@ -0,0 +1,435 @@
+"""Pure-Python decoder for Shearwater's Petrel Native Format (PNF).
+
+Shearwater Cloud stores each dive as a `sw-pnf` blob: a 4-byte little-endian
+uncompressed-length prefix followed by a gzip stream. The decompressed payload
+is a sequence of 32-byte records; byte 0 of each record is its type:
+
+  0x01       dive sample            0x10-0x19  opening (config) records
+  0x02       freedive sample (4x8)  0x20-0x29  closing records
+  0x03       Avelo sample           0x30       info event
+  0xE1       extended dive sample   0xFF       final record
+
+Byte offsets follow libdivecomputer's shearwater_predator_parser.c: sample
+fields sit at legacy-offset + 1 (the PNF type byte), opening/closing record
+fields at the absolute offsets used for their legacy 128-byte block.
+
+Record types this decoder does not understand are returned raw in
+`PnfDive.unknown_records` — nothing is dropped.
+
+DECODER_VERSION history:
+  1  initial port of the libdivecomputer field set
+  2  adds ceiling_m (byte 24), gf99 (byte 25), battery_v (byte 18 / 100) and
+     @+5 TTS (bytes 26-27), identified empirically: byte 25 converges on
+     dive_details.EndGF99 and decays during surface offgassing; byte 24 sits
+     just below the 3 m-quantized stop depth and zeroes when deco clears;
+     byte 18 equals the XML export's batteryVoltage x 100
+"""
+
+from __future__ import annotations
+
+import gzip
+import struct
+from dataclasses import dataclass, field
+
+DECODER_VERSION = 2
+
+RECORD_SIZE = 32
+
+DIVE_SAMPLE = 0x01
+FREEDIVE_SAMPLE = 0x02
+AVELO_SAMPLE = 0x03
+OPENING_0, OPENING_9 = 0x10, 0x19
+CLOSING_0, CLOSING_9 = 0x20, 0x29
+INFO_EVENT = 0x30
+DIVE_SAMPLE_EXT = 0xE1
+FINAL = 0xFF
+
+# status flag bits (sample byte 12)
+FLAG_GASSWITCH = 0x01
+FLAG_PPO2_EXTERNAL = 0x02
+FLAG_SETPOINT_HIGH = 0x04
+FLAG_SC = 0x08
+FLAG_OC = 0x10
+
+DIVE_MODES = {
+    0: "cc",
+    1: "oc_tec",
+    2: "gauge",
+    3: "ppo2",
+    4: "sc",
+    5: "cc2",
+    6: "oc_rec",
+    7: "freedive",
+    12: "avelo",
+}
+
+DECO_MODELS = {0: "gf", 1: "vpmb", 2: "vpmb_gfs", 3: "dciem"}
+
+# Sample bytes not (yet) assigned a meaning; kept per sample as b<offset>.
+# 18 (battery), 24 (ceiling), 25 (gf99), 26-27 (@+5) were identified
+# empirically and promoted in v2. 30-31 read 0xFFFF (sentinel) so far.
+UNMAPPED_SAMPLE_BYTES = (11, 17, 30, 31)
+
+
+def _u16be(data: bytes, off: int) -> int:
+    return struct.unpack_from(">H", data, off)[0]
+
+
+def _u24be(data: bytes, off: int) -> int:
+    return (data[off] << 16) | (data[off + 1] << 8) | data[off + 2]
+
+
+def _u32be(data: bytes, off: int) -> int:
+    return struct.unpack_from(">I", data, off)[0]
+
+
+def _bcd2dec(value: int) -> int:
+    return ((value >> 4) & 0x0F) * 10 + (value & 0x0F)
+
+
+def _bcd_bytes(data: bytes, off: int, n: int) -> int:
+    result = 0
+    for i in range(n):
+        result = result * 100 + _bcd2dec(data[off + i])
+    return result
+
+
+@dataclass
+class PnfSample:
+    t_s: float
+    depth_m: float | None = None
+    temp_c: float | None = None
+    stop_depth_m: float | None = None
+    stop_or_ndl_min: float | None = None
+    tts_min: float | None = None
+    in_deco: int | None = None
+    avg_ppo2: float | None = None
+    o2_pct: float | None = None
+    he_pct: float | None = None
+    setpoint: float | None = None
+    cns_pct: float | None = None
+    gf99: float | None = None
+    ceiling_m: float | None = None
+    sensor1_raw: int | None = None
+    sensor2_raw: int | None = None
+    sensor3_raw: int | None = None
+    sensor1_ppo2: float | None = None
+    sensor2_ppo2: float | None = None
+    sensor3_ppo2: float | None = None
+    battery_v: float | None = None
+    status_flags: int | None = None
+    tank0_psi: float | None = None
+    tank1_psi: float | None = None
+    gas_time_min: float | None = None
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass
+class PnfGas:
+    index: int
+    o2_pct: int
+    he_pct: int
+    diluent: bool
+    enabled: bool
+
+
+@dataclass
+class PnfEvent:
+    t_s: float
+    event: int
+    timestamp: int
+    w1: int
+    w2: int
+    raw_hex: str
+
+
+@dataclass
+class PnfDive:
+    header: dict
+    samples: list[PnfSample]
+    gases: list[PnfGas]
+    events: list[PnfEvent]
+    unknown_records: list[tuple[str, int, bytes]]  # (type_key, seq, raw)
+    sample_interval_ms: int
+
+
+def decompress(blob: bytes) -> bytes:
+    """Strip the 4-byte LE length prefix and gunzip; verify the length."""
+    expected = struct.unpack_from("<I", blob, 0)[0]
+    data = gzip.decompress(blob[4:])
+    if len(data) != expected:
+        raise ValueError(f"PNF length mismatch: prefix {expected}, got {len(data)}")
+    if len(data) % RECORD_SIZE:
+        raise ValueError(f"PNF payload not a multiple of {RECORD_SIZE} bytes")
+    return data
+
+
+def decode(blob: bytes) -> PnfDive:
+    """Decode a raw sw-pnf blob (as stored in Shearwater Cloud's log_data)."""
+    data = decompress(blob)
+
+    opening: dict[int, int] = {}
+    closing: dict[int, int] = {}
+    final_off: int | None = None
+    raw_records: list[tuple[int, int]] = []  # (type, offset), stream order
+
+    for off in range(0, len(data), RECORD_SIZE):
+        rec = data[off : off + RECORD_SIZE]
+        if rec == b"\x00" * RECORD_SIZE:
+            continue
+        rtype = rec[0]
+        raw_records.append((rtype, off))
+        if OPENING_0 <= rtype <= OPENING_9:
+            opening[rtype - OPENING_0] = off
+        elif CLOSING_0 <= rtype <= CLOSING_9:
+            closing[rtype - CLOSING_0] = off
+        elif rtype == FINAL:
+            final_off = off
+
+    for i in range(5):
+        if i not in opening or i not in closing:
+            raise ValueError(f"missing opening/closing record {i}")
+
+    header = _parse_header(data, opening, closing, final_off)
+    interval_ms = header["sample_interval_ms"]
+    calibrated = header["sensor_calibrated_mask"]
+    calibration = header["sensor_calibration"]
+    imperial = header["imperial"]
+
+    gases = [
+        PnfGas(
+            index=i,
+            o2_pct=header["gas_o2"][i],
+            he_pct=header["gas_he"][i],
+            diluent=i >= 5,
+            enabled=bool(header["gas_enabled_mask"] & (1 << i)),
+        )
+        for i in range(10)
+    ]
+
+    samples: list[PnfSample] = []
+    events: list[PnfEvent] = []
+    unknown: list[tuple[str, int, bytes]] = []
+    seq = 0
+    t = 0.0
+
+    for rtype, off in raw_records:
+        rec = data[off : off + RECORD_SIZE]
+        if rtype in (DIVE_SAMPLE, AVELO_SAMPLE):
+            samples.append(
+                _parse_sample(rec, t, imperial, calibrated, calibration, rtype)
+            )
+            t += interval_ms / 1000.0
+        elif rtype == FREEDIVE_SAMPLE:
+            for i in range(4):
+                sub = rec[i * 8 : (i + 1) * 8]
+                if sub == b"\x00" * 8:
+                    break
+                pressure_mbar = _u16be(sub, 1)
+                depth = (
+                    (pressure_mbar - header["atmospheric_mbar"])
+                    * 100.0
+                    / (header["water_density"] * 9.80665)
+                )
+                temp = struct.unpack_from(">h", sub, 3)[0] / 10.0
+                samples.append(PnfSample(t_s=t, depth_m=round(depth, 2), temp_c=temp))
+                t += interval_ms / 1000.0
+        elif rtype == DIVE_SAMPLE_EXT:
+            s = samples[-1] if samples else None
+            for i, key in enumerate(("tank2_psi", "tank3_psi")):
+                v = _u16be(rec, 1 + i * 2)
+                if v < 0xFFF0 and (v & 0x0FFF) and s is not None:
+                    s.extra[key] = (v & 0x0FFF) * 2
+            for i, key in enumerate(("tank_dil_psi", "tank_o2_psi")):
+                v = _u16be(rec, 1 + 4 + i * 2)
+                if v and s is not None:
+                    s.extra[key] = v * 2
+        elif rtype == INFO_EVENT:
+            events.append(
+                PnfEvent(
+                    t_s=t,
+                    event=rec[1],
+                    timestamp=_u32be(rec, 4),
+                    w1=_u32be(rec, 8),
+                    w2=_u32be(rec, 12),
+                    raw_hex=rec.hex(),
+                )
+            )
+        elif OPENING_0 <= rtype <= OPENING_9 or CLOSING_0 <= rtype <= CLOSING_9 or rtype == FINAL:
+            pass  # consumed by _parse_header; raw copies kept in header dict
+        else:
+            unknown.append((f"0x{rtype:02x}", seq, rec))
+        seq += 1
+
+    return PnfDive(
+        header=header,
+        samples=samples,
+        gases=gases,
+        events=events,
+        unknown_records=unknown,
+        sample_interval_ms=interval_ms,
+    )
+
+
+def _parse_sample(
+    rec: bytes,
+    t: float,
+    imperial: bool,
+    calibrated: int,
+    calibration: list[float],
+    rtype: int,
+) -> PnfSample:
+    ft = 0.3048
+    depth = _u16be(rec, 1) / 10.0
+    stop_depth = float(_u16be(rec, 3))
+    if imperial:
+        depth *= ft
+        stop_depth *= ft
+
+    temp = struct.unpack_from("b", rec, 14)[0]
+    if temp < 0:
+        temp = min(temp + 102, 0)
+    if imperial:
+        temp = (temp - 32.0) * 5.0 / 9.0
+
+    status = rec[12] if rtype != AVELO_SAMPLE else 0
+    ccr = (status & FLAG_OC) == 0 if rtype != AVELO_SAMPLE else False
+
+    sample = PnfSample(
+        t_s=t,
+        depth_m=round(depth, 2),
+        temp_c=float(temp),
+        stop_depth_m=stop_depth,
+        tts_min=float(_u16be(rec, 5)),
+        stop_or_ndl_min=float(rec[10]),
+        in_deco=1 if _u16be(rec, 3) else 0,
+        avg_ppo2=rec[7] / 100.0,
+        o2_pct=float(rec[8]),
+        he_pct=float(rec[9]),
+        status_flags=status,
+        sensor1_raw=rec[13],
+        sensor2_raw=rec[15],
+        sensor3_raw=rec[16],
+        cns_pct=float(rec[23]),
+        ceiling_m=float(rec[24]) if rec[24] != 0xFF else None,
+        gf99=float(rec[25]) if rec[25] != 0xFF else None,  # 0xFF = not available
+        battery_v=rec[18] / 100.0,
+    )
+
+    if ccr:
+        sample.setpoint = rec[19] / 100.0
+        if not (status & FLAG_PPO2_EXTERNAL):
+            if calibrated & 0x01:
+                sample.sensor1_ppo2 = round(rec[13] * calibration[0], 3)
+            if calibrated & 0x02:
+                sample.sensor2_ppo2 = round(rec[15] * calibration[1], 3)
+            if calibrated & 0x04:
+                sample.sensor3_ppo2 = round(rec[16] * calibration[2], 3)
+
+    for idx, key in ((20, "tank1_psi"), (28, "tank0_psi")):
+        v = _u16be(rec, idx)
+        if v < 0xFFF0:
+            pressure = v & 0x0FFF
+            battery = (v >> 12) & 0x0F
+            if key == "tank1_psi":
+                sample.tank1_psi = pressure * 2.0
+            else:
+                sample.tank0_psi = pressure * 2.0
+            if battery:
+                sample.extra[key + "_battery"] = battery
+
+    if rec[22] < 0xF0:
+        sample.gas_time_min = float(rec[22])
+
+    # @+5: TTS if the diver stayed 5 more minutes (minutes, u16be)
+    at_plus_five = _u16be(rec, 26)
+    if at_plus_five != 0xFFFF:
+        sample.extra["at_plus_five_min"] = at_plus_five
+
+    for b in UNMAPPED_SAMPLE_BYTES:
+        if rec[b]:
+            sample.extra[f"b{b}"] = rec[b]
+
+    return sample
+
+
+def _parse_header(
+    data: bytes,
+    opening: dict[int, int],
+    closing: dict[int, int],
+    final_off: int | None,
+) -> dict:
+    o = opening
+    c = closing
+
+    logversion = data[o[4] + 16]
+    imperial = data[o[0] + 8] == 1
+
+    gas_o2 = [data[o[0] + 20 + i] for i in range(10)]
+    gas_he = [data[o[0] + 30 + i] for i in range(2)] + [
+        data[o[1] + 1 + i] for i in range(8)
+    ]
+
+    calib_base = o[3] + 6
+    calibrated_mask = data[calib_base]
+    calibration = [
+        _u16be(data, calib_base + 1 + i * 2) / 100000.0 for i in range(3)
+    ]
+
+    interval_ms = 10000
+    if logversion >= 9 and 5 in o:
+        interval_ms = _u16be(data, o[5] + 23) or 10000
+
+    max_depth = _u16be(data, c[0] + 4) / 10.0
+    if imperial:
+        max_depth *= 0.3048
+
+    header = {
+        "logversion": logversion,
+        "imperial": imperial,
+        "divemode": DIVE_MODES.get(data[o[4] + 1], str(data[o[4] + 1])),
+        "gf_low": data[o[0] + 4],
+        "gf_high": data[o[0] + 5],
+        "deco_model": DECO_MODELS.get(data[o[2] + 18], str(data[o[2] + 18])),
+        "vpmb_conservatism": data[o[2] + 19],
+        "atmospheric_mbar": _u16be(data, o[1] + 16),
+        "water_density": _u16be(data, o[3] + 3),
+        "sensor_calibrated_mask": calibrated_mask,
+        "sensor_calibration": calibration,
+        "gas_o2": gas_o2,
+        "gas_he": gas_he,
+        "gas_enabled_mask": _u16be(data, o[4] + 17),
+        "ai_mode": data[o[4] + 28],
+        "sample_interval_ms": interval_ms,
+        "max_depth_m": round(max_depth, 2),
+        "divetime_s": _u24be(data, c[0] + 6),
+    }
+
+    if final_off is not None:
+        header["computer_serial"] = _u32be(data, final_off + 2)
+        header["computer_firmware"] = _bcd2dec(data[final_off + 10])
+        header["computer_model"] = data[final_off + 13]
+
+    if logversion >= 17:
+        for name, recs in (("gnss_start", o), ("gnss_end", c)):
+            if 9 in recs:
+                off = recs[9]
+                fix = data[off + 16]
+                if fix in (2, 3):  # 2D / 3D fix
+                    lat = struct.unpack_from(">i", data, off + 21)[0] / 100000.0
+                    lon = struct.unpack_from(">i", data, off + 25)[0] / 100000.0
+                    header[name] = {"fix": fix, "lat": lat, "lon": lon}
+
+    # Verbatim copies of every config record, keyed by record type.
+    header["raw_opening"] = {
+        f"0x{OPENING_0 + i:02x}": data[off : off + RECORD_SIZE].hex()
+        for i, off in sorted(o.items())
+    }
+    header["raw_closing"] = {
+        f"0x{CLOSING_0 + i:02x}": data[off : off + RECORD_SIZE].hex()
+        for i, off in sorted(c.items())
+    }
+    if final_off is not None:
+        header["raw_final"] = data[final_off : final_off + RECORD_SIZE].hex()
+
+    return header

bottomtime/ingest/__init__.py

@@ -0,0 +1 @@
+

bottomtime/ingest/archive.py

@@ -0,0 +1,48 @@
+"""Content-addressed archive of verbatim raw source files.
+
+Every ingested file is copied (if absent) to <archive_dir>/<kind>/<sha256><ext>
+and registered in raw_artifacts. The archive, not the database, is the
+byte-level source of truth; re-running is a no-op.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+import sqlite3
+from pathlib import Path
+
+from ..store.db import utcnow
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def archive_file(
+    con: sqlite3.Connection, archive_dir: Path, kind: str, path: Path
+) -> tuple[int, str]:
+    """Archive path under kind; return (artifact_id, sha256)."""
+    digest = sha256_file(path)
+    row = con.execute(
+        "SELECT id FROM raw_artifacts WHERE sha256=?", (digest,)
+    ).fetchone()
+    if row:
+        return row[0], digest
+
+    dest_dir = archive_dir / kind
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / (digest + path.suffix.lower())
+    if not dest.exists():
+        shutil.copy2(path, dest)
+
+    cur = con.execute(
+        "INSERT INTO raw_artifacts (kind, sha256, size_bytes, original_path, archive_path, imported_at)"
+        " VALUES (?,?,?,?,?,?)",
+        (kind, digest, path.stat().st_size, str(path), str(dest), utcnow()),
+    )
+    return cur.lastrowid, digest