Drift-aware, link-preserving mint/supersede publishing

[tkuhn]

Makes republishing update already-published defining nanopubs instead of only appending new ones, and preserves inter-term link resolution when it does.

Motivation

Publishing was append-only: mint_publish skipped any term already in the id-map, keyed solely on its old id — blind to a change in the term's content or in a batch-level wrapper (template, dcterms:isPartOf, nanopub-type, license). There was no way to re-issue a published nanopub when, say, the assertion template changed.

What this adds

Drift fingerprint (fingerprint.py) — a key-independent SHA-256 over the identity-defining inputs only: the URDNA2015-canonicalized assertion plus suggester/derived_from/license/introduces/nanopub-type/template. Computed on the placeholder form so the thing URI never feeds its own hash. Excludes the build timestamp, signature and blank-node/order noise (no-op tier) and the signing key / toolchain (build-provenance tier), so a key rotation cannot masquerade as content drift.

Id-map schema (idmap.py) — a fourth fingerprint column; still reads legacy 3-column files.

Incremental publisher (incremental.py) — publish_incremental(): per term, mint (new), skip (fingerprint unchanged), or supersede (drifted). A superseded term is re-stated against its existing fixed thing URI in a nanopub that npx:supersedes the recorded one, keeping the term's identity; the id-map is repointed. Legacy rows without a fingerprint are backfilled as a baseline, not mass-superseded. Wired into cli/mint_publish.py.

Drift-aware migration (migrate.py) — the migration now records each term's fingerprint (over the as-given source assertion, same wrapper — identical to what publish_incremental recomputes), so a later incremental run over the migrated sources skips unchanged terms instead of hitting the backfill branch and silently swallowing a post-migration wrapper change.

Link-preserving supersede — migrate's reference resolver is extracted to references.resolve_references() and reused on the incremental supersede path: re-issuing a term resolves its inter-term references to new thing URIs via the id-map (all targets already minted) rather than reverting to old-id references. The mint path (new terms) still mints as-given. Migration also repoints the id-map at the cyclic-link supersession so the supersedes chain stays linear.

Behavior

State	Condition	Action
new	absent from id-map	mint defining nanopub, record fingerprint
unchanged	fingerprint matches	skip
drifted	fingerprint differs	supersede against fixed thing URI (references resolved), repoint id-map
legacy	fingerprint empty (3-col row)	backfill baseline, skip

Tests

New test_fingerprint.py / test_incremental.py and additions to test_idmap.py / test_migrate.py / test_cli_mint_publish.py cover: determinism, cosmetic/no-op invariance, each identity field moving the fingerprint, key-independence, the mint/skip/supersede/backfill decisions, CLI end-to-end (superseding .trig with npx:supersedes + repointed id-map), migration fingerprint consistency (no phantom drift), a template change superseding migrated terms, and reference resolution preserved on supersede. Full suite: 124 passed.

🤖 Generated with Claude Code

[GertjanBisschop]

Hi Tobias, thanks a bunch for this. This is indeed the next thing that we'd be needing. But you beat me to it.
Just checking, is this PR ready for evaluating and merging, or was Claude getting quite trigger happy again?

[tkuhn]

Hi Gertjan! Sorry, if I interfered with your plans. I hope it's fine like this.

This PR was intentional but good that you ask :)

It looks all good to me and is tested, so ready to merge from my side. But let me know if you'd like to have more info, or like the PR in a different form.

[GertjanBisschop]

Awesome! Merging.