feat(distribution-health): new leaf for validity verdicts and usability rollup

[ddeboer]

Closes #468. Part of the distribution-health feature: netwerk-digitaal-erfgoed/dataset-register#2103.

What

A new pure leaf package @lde/distribution-health that derives a distribution’s usability from two separately-produced signals — reachability (HTTP/SPARQL) and validity (does the fetched content parse as RDF?). It interprets the raw results of @lde/distribution-probe and @lde/sparql-importer; it does no I/O and is deliberately acyclic.

It returns plain TypeScript only — no RDF, no vocabulary. Converting a verdict to RDF is the consumer’s job (see below), mirroring @lde/iiif-validator.

Two modules, built test-first (red→green→refactor, one behaviour per cycle):

• verdict — a ValidityVerdict type (typed failure reason parse-error / empty, best-effort parser message, the validatedFingerprint judged against, producer depth shallow / deep) plus two mappers:
  • probeResultToVerdict (shallow): interprets the body validation the probe already performs for small RDF dumps; returns null when the probe carries no validity signal (network/HTTP failure, SPARQL, or a large HEAD-only body).
  • importOutcomeToVerdict (deep): a failed import is invalid (parse-error); a successful one is valid, or empty when it produced zero triples.
• usability — the one canonical rollup (reachability, verdicts) → { usable | unusable | unknown, cause }:
  • reachability dominates — unreachable ⇒ unusable;
  • staleness gate — a verdict applies only if its validatedFingerprint equals the currently-observed fingerprint (a null fingerprint never matches, mirroring sourceFingerprint), else it decays to unknown. This is what stops a since-fixed dump showing red;
  • depth beats breadth — a fresh deep verdict wins over a shallow one; a usability resting on a shallow verdict is flagged shallow.

RDF / vocabulary is the consumer’s responsibility

This package emits no quads and coins no predicates, so consumers never have to reconcile two namespaces for the same data. A consumer turns a ValidityVerdict into its own DQV/PROV quads under its own namespace — e.g. the NDE knowledge-graph pipeline / register write a dqv:QualityMeasurement on the distribution under def.nde.nl, alongside the existing quality measurements (qualityMeasurementsStage / failureUsage). The ValidityFailureReason local names drop straight into a SKOS failure scheme (<scheme>#${reason}).

This lands as epic tasks 4 (dataset-register) and 5 (dataset-knowledge-graph).

Tests

20 tests, 100% coverage. The usability rollup gets an exhaustive case matrix (reachability × validity × fingerprint fresh/stale × depth).

Notes

• The shallow mapper duplicates the probe’s parseable-content-type list and 10 KiB parse threshold (commented). A structured validity signal on the probe result would remove that coupling — noted in verdict.ts.
• Package version is 0.0.0 so the first nx release lands it at 0.1.0; npm Trusted Publisher bootstrap is a one-time manual step per AGENTS.md.