Graph explorer: per-version column table and column lineage walk (variable-level traceability, not just process tracing)

[MaxGhenis]

Ask

At the 2026-09-03 data weekly, Anthony's read of the graph after a first pass was: good process tracing ("akin to GitHub CI/CD": stages, dependencies, outputs), but no variable-level traceability. He could not walk a column through the build: which columns exist at each population version, which node wrote each one, and what a given node read to produce it. Max: "I really want to get to the point where it can actually visualize what it is."

The runtime already knows this. Every node declares the slices it reads and the cells it owns; the executor resolves the causal writers of every read coordinate (_input_writers / _writers_of in microcosm/graph/executor.py) and the manifest carries the receipts. What is missing is the view.

What to add to the explorer (microcosm/graph/explain.py, tools/graph_explain.py)

1. Per-version column table. For each population version in a run: entity, column, dtype, and the node that owns it at that version (CREATE/EXPAND/writer), with the version it first appeared in.
2. Column lineage walk. Pick entity.column; show the chain of writers back to its source (node id, kernel name@version, the input coordinates each writer read, and the receipt link), i.e. the same data the executor uses for tolerance-writer provenance, rendered.
3. Node detail = reads and writes. On a node card, list the exact coordinates read (with their writers) and the coordinates owned, not just the stage name.
4. Define kernel in one sentence on the explorer's landing panel and in docs/graph-explorer.md: a kernel is the pure function a node runs, named name@version, whose implementation hash is part of the node key. Neither Anthony nor Max could say what a kernel was from the current docs.

Keep it neutral across countries (charter group G) and derive everything from the manifest so the view never disagrees with receipts. Anthony will show the current SVG at stand-up or next week's data meeting; this issue is the depth he asked for. Related: microcosm-dynamics#412 (person/household-level depth for dynamics), docs/graph-acceptance.md V1–V4.

[juaristi22]

Picking this up as the variable-lineage workstream for Microcosm → Orrery. Keep the work in this issue, alongside two companion drafts covering country-agnostic graph export and execution-evidence overlays. The UK will be the first consumer; the shared metadata and exporter should support any Microcosm country graph.

Orrery's current main already provides an orrery-lineage/v1 extension with variable and stage selection, explicit value/control/context roles, and source/unknown boundaries. Microcosm needs to supply the domain mappings. #888 provides related export groundwork, but currently exports operation-level relationships without these precise lineage annotations.

Proposed scope for this issue

• Carry forward the per-version column table, writer-chain and read/write requirements above. Export entity, column, dtype, row scope, ownership/absence, first appearance, and carrier/writer identities through one shared metadata API.
• Reuse or factor the executor/compiler's writer resolution. Preserve field versions, pre-rewrite values, partial-row rewrites, structural carry-through, filtering, expansion/entrant materialization, and weight changes. Distinguish declared possibilities from what a run's receipts establish.
• Add explicit per-output dependency mappings where the kernel's semantics support them. A stage reading several inputs and producing several outputs does not establish that every input determines every output. Preserve operation-level context and show an unknown boundary where a composite kernel lacks a justified mapping.
• Export a variable catalog, stage choices, and supported value/control/context annotations using the existing graph node/edge identities. Structural ancestry alone does not establish unchanged values. Use Orrery's lineage contract where its semantics fit.
• Keep static lineage usable without a completed run; attach validated runtime writer evidence through the execution overlay when available. Retain the kernel explanation requested above.

Acceptance criteria

• The metadata implementation is country-agnostic; UK fixtures provide the first integration coverage.
• Per-version inventories match declarations, and runtime-backed writer claims match the supplied receipts.
• Synthetic UK traces cover a carried source field, an imputed field, a partial-row rewrite, geographic expansion/materialization, and calibration weights or their explicit artifact/control representation.
• Tests distinguish carriers, actual writers, values and controls, and preserve pre-rewrite identities. A multi-output kernel without sufficient mappings exposes an unknown boundary.
• All lineage references resolve and annotations survive JSON/HTML round trips through a pinned Orrery build supporting the extension. Graphs without lineage remain supported.
• Document supported mappings and remaining composite-kernel boundaries; share the same metadata with the native explorer where it consumes these facts.

Once graph export, execution overlays and this lineage work are supported in Microcosm, use their artifacts to assess any remaining Orrery features and agree which repository should own those changes. New viewer features and hosted build discovery can be scoped at that point.