Provenance

Scan, Check, Fix — the read-write triad

provenance scan walks an entire tree and emits a structured JSON report keyed by stable rule IDs. Every issue carries a rule code, a record reference, and a severity classification, so downstream tooling — the desktop app, a CI job, a custom dashboard — can render the same data without re-implementing the parser. scan_file() is exposed as a public Python API for programmatic use.

provenance check runs a stricter consistency pass and writes a markdown report suitable for review or commit. Both commands are read-only; nothing mutates state. provenance fix is the mutating counterpart — date normalization (American order rewriting, FROM/TO ranges, BET/AND with month+year), name canonicalization, place-string normalization — and every fix invocation produces an AutoFix annotation log plus a timestamped backup, so any change is reversible.

A separate in-memory API, fix_gedcom_text(), takes a GEDCOM string and returns the normalized output without touching disk — the seam used by the Tauri app, the web build, and the Chrome extension to share one parser across every surface.

Dedupe, Merge, Review — the trust layer

provenance dedupe runs fuzzy-match duplicate detection across individuals and surfaces candidate pairs with a similarity score. The merge logic is relationship-safe: when a pair is collapsed, child and spouse references on both sides are retained, conflicting facts are preserved as alternates, and the entire operation is captured as a reversible diff against the pre-merge backup.

provenance merge joins two GEDCOM files into one with automatic xref collision handling — the engineering equivalent of merging two researchers’ trees without manually renumbering every @I pointer. provenance review opens an interactive review session over the consistency-check output, letting a researcher walk issues one at a time, accept or annotate each, and produce a clean follow-up scan to confirm closure.

provenance stats rounds out the surface with tree statistics (individuals, families, surnames, date ranges) for quick orientation when picking up a file you haven’t opened in months. provenance export --filter-living applies living-person privacy rules — suppressing dates of birth, current locations, and identifying details for individuals presumed living — before producing a public-shareable file.

CLI distribution and install path

The Python CLI ships as tools/cli in the monorepo and installs editable via pip install -e tools/cli. provenance --help enumerates all nine subcommands. Tested against Python 3.11 and 3.12 in CI; MIT-licensed.

Public Python APIs

normalize_gedcom_date_safe(text), fix_gedcom_text(gedcom_str), and scan_file(path) are stable public APIs as of v1.0.0. Every API returns structured types — DateResult, normalized strings, or a list of typed issue records — never raw strings or untyped dicts. Downstream code can rely on the shape.

Date parsing rules

American date order (e.g. “January 15, 1850” → “15 JAN 1850”), FROM/TO and BET/AND patterns including month+year support, GEDCOM-canonical month abbreviation, and a deterministic DateResult output that records both the normalized form and the original string so reversibility is preserved.

Backup discipline

Every mutating CLI run — fix, dedupe, merge, export — produces a timestamped backup of the input file before touching it. Backups are local, named with the operation that produced them, and never deleted automatically. Rollback is a file copy.

Release pipeline

Pushing an app-v* tag triggers a single GitHub Actions release workflow that produces macOS, Windows, Linux, Android, iOS, and web builds in parallel. The CI pipeline already validates the Python CLI on 3.11 and 3.12 on every push.