feat(registry): run status + supersession provenance model (Phase 1)

[GondekNP]

Summary

Implements Phase 1 of REGISTRY_PROVENANCE.md: a first-class run provenance model. Today "current" is an emergent side-effect of a label-renaming hack (on_collision="timestamp"), which is why tags can't tell current from archived and supersession keeps no record of why or what replaced what. This gives each concern one home:

run_hash is what it is · label is what I call it (a pure alias) · tags are what it's about · status is whether I should use it.

"Current" collapses entirely into status = 'active'.

Schema (additive, backward-compatible)

• New columns on job_configs: status, superseded_by, status_reason, status_updated_at, applied through the existing probe-and-ALTER migration path. NULL status is read as 'active' everywhere via coalesce — zero behavior change for existing databases (covered by a migration test that opens a pre-status DB).
• New non-materialized cell_data_current view (active runs only). Created after _init_spatial() so its SELECT c.* captures the geom column when spatial is enabled.

API

• mark_run(run_hash, status, *, superseded_by=None, reason=None) — closed enum {active, superseded, bad}, enum-validated, with target-exists / no-self-supersede checks. Returning a run to active clears its supersession link.
• get_run_status(label_or_hash) -> RunStatus (with effective_status / is_current).
• supersede(new_hash, replaces=, reason=) sugar; run_history(label) walks the superseded_by chain (current → oldest), replacing the removed resolve_latest().
• label_run: retire on_collision="timestamp" in favor of "supersede" — the old run releases its label (label=NULL) and is marked status='superseded' pointing at the new run, so it self-cleans out of list_labels(). Added a reason arg; force=True unchanged.
• status surfaced on ConfigInfo and in describe_run; SweepManagerBuilder.with_label(on_collision=, reason=) wired through.

Testing — including real-JAR integration

• New tests/test_provenance_integration.py (-m integration, real DEV jar, no mocking): runs actual Josh sims through SweepManager, ingests real cell_data, and asserts against it — supersession provenance, label handover, run_history lineage, and that cell_data_current filters a superseded (and a mark_run("bad")) run's real rows while leaving raw cell_data intact. Both pass.
• Unit tests: replaced the timestamp/resolve_latest tests with status/supersession/migration coverage. Full suite 1206 passed, 24 skipped; -m integration (jshdz + new provenance) pass, MinIO skipped (no server).

Docs — regenerated against the real jar

• Tutorials (complete-example.qmd, manual-workflow.qmd) and llms-full.txt rewritten to the supersession model; quartodoc reference index (objects.json) regenerated.
• _freeze regenerated for all four affected tutorials by executing the real sims, and verified figure-by-figure (e.g. complete-example maxGrowth 5/10/15 → ~12/25/37 over 10 steps; the fire-intervention drop at step 5).

Bundled: adapt example models to new josh-jar semantics

Regenerating the freeze surfaced two intended josh behavior changes (confirmed against josh's own llms-full.txt, not regressions) that broke the example models. Fixed here so the docs render correctly:

1. external reads now index by raw timestep. A bare external X resolves to "current raw timestep as index" (and warns once). The example models read static spatial maps every step, so a bare read walked past the single record on later steps and collapsed growth (flat figures). Pinned to external X at index 0 (explicit, non-warning) in external_sweep.josh, variant_sweep.josh.j2, and timestep_intervention.josh.
2. Stricter entity-count validation. create ... of now rejects fractional counts; wrapped the scaled density in round() in timestep_intervention.josh.

Follow-ups (not in this PR)

• Phase 2 (tag currency) and Phase 3 (remote bucket aggregation), per REGISTRY_PROVENANCE.md §10.
• Open design question (§11): whether status='bad' should also trigger a rerun (a collision_policy concern) vs. purely exclude from reads. This PR does exclude-only.

🤖 Generated with Claude Code