Skip to content

v0.6.0: Proactive provenance (run-record + node runner) + LaTeX paper standard#12

Open
hebbianloop wants to merge 4 commits into
mainfrom
schema-v0.6-proactive-provenance
Open

v0.6.0: Proactive provenance (run-record + node runner) + LaTeX paper standard#12
hebbianloop wants to merge 4 commits into
mainfrom
schema-v0.6-proactive-provenance

Conversation

@hebbianloop

Copy link
Copy Markdown
Owner

Summary

Makes the Glimmer graph executable, not just descriptive, and establishes a LaTeX standard for submittable papers.

The agentic loop (docs/agentic-loop.md) was specified but had no runtime primitive; the only "verification" script re-hashed files on disk ("not a full re-run"). This PR closes that gap with one core node type and one tool, and lands two manuscripts.

Schema (v0.5.1 → v0.6.0)

  • run-record core node type — one concrete, replayable invocation (PROV Activity) with a planned → ready → running → executed lifecycle, binding a method + pinned, standard-validated inputs + expected outputs + command + container digest + a runner-written verdict. The executable unit of the agentic loop.
  • New edges reruns / consumes / regenerates / emits (+ inverse regenerated-by); tests-hypothesis / addresses-concept allowed from a run-record.
  • Method-registry affordances: registry-ref + implements / equivalent-to / refines. standard.validator hint for the runtime gate.

Runner — glimmer/tools/run.py (glimmer run / glimmer rerun)

  • Pre-run standards gate (inputs pinned AND valid; delegated to each standard's validator).
  • datalad containers-run replay (feature-detected; degrades honestly).
  • Three verification tiers: byte-identical (NIfTI/GIFTI/JSON normalization), numeric-within-tolerance (re-derive published numbers), structural (agent/LLM).
  • certify_equivalence, dependency-ordered all, provenance manifest, verdict writeback.

Validator, example, docs

  • validate.py: run-record field/edge/target/lifecycle checks + agent-protocol rule.
  • examples/synthetic-provenance/: exercises the loop + all three tiers + the gate + equivalence, no real data / no heavy deps.
  • New docs/proactive-provenance.md; agentic-loop.md made executable; roadmap renumbered (federation → v0.7, registry/minimal-path folded in); README repositioned as AI-native reproducibility; agent-protocol + datalad-pattern cross-linked.

Papers (new LaTeX standard)

  • papers/glimmer-paper.cls — venue-neutral house class; papers/README.md documents the convention.
  • Paper 1 (01-knowledge-graph-navigation/) — scoped to v0.5: the graph as a navigable substrate; verification as a validator-enforced contract, the executable runner named as forthcoming. Preprint candidate (9pp).
  • Paper 2 (02-proactive-provenance/) — v0.6: the run-record + node runner (7pp). LaTeX port of docs/paper-draft.md.

Verification

  • glimmer validate on the synthetic example: 0 errors. glimmer rerun … all → 100% (verified ×2, reproduced-within-tolerance, structurally-valid).
  • Negative controls: gate-fail (exit 1), tamper → mismatch, offline → inputs-unavailable, equivalence certified by output-match.
  • Backward-compat: ds000114-nipype validates unchanged.
  • Both papers compile via make (latexmk + bibtex), no undefined references.

🤖 Generated with Claude Code

Shady El Damaty and others added 4 commits June 24, 2026 14:17
Make the Glimmer graph executable, not just descriptive. The agentic loop
(docs/agentic-loop.md) was specified but had no runtime primitive; the only
"verification" script re-hashed files on disk ("not a full re-run").

Core schema (v0.5.1 → v0.6.0):
- new `run-record` node type: one concrete, replayable invocation (PROV Activity)
  with a planned → ready → running → executed lifecycle, binding a method + pinned,
  standard-validated inputs + expected outputs + command + container digest + a
  runner-written verdict. The executable unit of the agentic loop.
- edges reruns/consumes/regenerates/emits (+ inverse regenerated-by); broaden
  tests-hypothesis/addresses-concept to allow a run-record source.
- method-registry affordances: registry-ref + implements/equivalent-to/refines.
- standard.validator hint for the runtime gate.

Runner (glimmer/tools/run.py + `glimmer run` / `glimmer rerun`):
- pre-run standards gate (inputs pinned AND valid; validation delegated to each
  standard's validator or glimmer validate).
- datalad containers-run replay (feature-detected; degrades honestly).
- three verification tiers: byte-identical (NIfTI/GIFTI/JSON normalization),
  numeric-within-tolerance (re-derive published numbers), structural (agent/LLM).
- certify_equivalence, dependency-ordered `all`, provenance manifest, verdict
  writeback.

Validator: run-record field/edge/target/lifecycle checks + agent-protocol rule.

Worked example: examples/synthetic-provenance/ exercises the loop + all three
tiers + the gate + equivalence, with no real data and no heavy deps.

Docs: new docs/proactive-provenance.md; agentic-loop.md made executable; roadmap
(federation → v0.7, registry/minimal-path folded in); README repositioned as
AI-native reproducibility; agent-protocol + datalad-pattern cross-linked.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add docs/paper-draft.md — a working manuscript (no journal boilerplate)
extending "Reproducibility as Knowledge Graph Navigation" to proactive
provenance: the executable run-record + node runner, the standards gate, the
three verification tiers, runtime-certified method equivalence, and the
agentic loop made executable. Point paper-citation.md at it and bump the
software citation version to 0.6.0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Establish LaTeX as the standard for submittable Glimmer papers:
- papers/glimmer-paper.cls — venue-neutral house document class (preprint/draft
  banners, title-block macros; preloads amsmath/hyperref/natbib/booktabs/…).
- papers/README.md — the convention + build instructions; papers/.gitignore for
  TeX artifacts.
- papers/01-knowledge-graph-navigation/ — Paper 1, scoped to v0.5 (the graph as a
  navigable substrate; verification as a validator-enforced contract, the
  executable runner named as forthcoming). Preprint candidate. Compiles to 9pp.
- papers/02-proactive-provenance/ — Paper 2 (v0.6): the run-record + node runner,
  standards gate, three verification tiers, certified equivalence. LaTeX port of
  docs/paper-draft.md. Compiles to 7pp.

Both build with `make` (latexmk + bibtex) against the shared class.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant