PolicyEngine / PolicyEngine/microcosm
Graph explorer: per-version column table and column lineage walk (variable-level traceability, not just process tracing)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 4
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 94
Description
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)
- 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.
- Column lineage walk. Pick
entity.column; show the chain of writers back to its source (node id, kernelname@version, the input coordinates each writer read, and the receipt link), i.e. the same data the executor uses for tolerance-writer provenance, rendered. - 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.
- 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, namedname@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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with _input_writers and _writers_of in microcosm/graph/executor.py, then trace how the manifest reaches microcosm/graph/explain.py and tools/graph_explain.py. Review docs/graph-explorer.md and docs/graph-acceptance.md V1–V4. Done means the explorer shows per-version columns, column lineage, node reads and writes, and defines kernels consistently from manifest data.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100