Skip to content

starmap: surface strategy reasoning and support/lowering signal#781

Open
fkguo wants to merge 4 commits into
SiliconEinstein:mainfrom
fkguo:codex/starmap-graph-clarity
Open

starmap: surface strategy reasoning and support/lowering signal#781
fkguo wants to merge 4 commits into
SiliconEinstein:mainfrom
fkguo:codex/starmap-graph-clarity

Conversation

@fkguo

@fkguo fkguo commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

What

An external portfolio of argument graphs (nine compiled packages reviewed side by side) surfaced a set of clarity gaps in the gaia inspect starmap surfaces. This PR fixes them across graph.json, the dot/SVG emitter, and the interactive HTML, plus a CLI-docs drift found along the way.

Graph exports and renderers (feat(starmap))

  • Strategy reasoning was silently dropped. The graph.json exporter read a top-level reason key that compiled IR never carries (Strategy has no such field, extra="forbid"), so every strategy node shipped an empty reason. The exporter now joins steps[].reasoning and falls back to metadata.reason — the two places the DSL's reason= actually compiles to. In the reviewed portfolio this restored 12/12 previously-empty explanations per graph.
  • Support vs lowering is now visually encoded. Strategy nodes and their conclusion edges carry a signed effect = cp[-1] - cp[-2] from the inline conditional-probability table (the premise present/absent contrast at every given count — the two gated slots _infer_conditional_probabilities writes). Both renderers color scored conclusion edges on the same red-grey-green ramp and scale stroke width by magnitude; the side panel shows the probability pair and an effect badge. Strategy forms without an inline CPT stay unscored and keep plain role styling.
  • Generated helper nodes no longer dominate the layout. Knowledge nodes with metadata.generated start collapsed (with their incident edges) behind a default-off filter bucket, instead of being the dominant visual structure; search skips hidden nodes and sheds stale highlights.
  • Legends tell the truth per graph. The HTML legend hides rows for absent kinds and gains two edge-color rows; the stellaris SVG legend scopes glyph rows to the strategy/operator types actually present and documents the edge colors whenever the graph carries scored edges (the standalone SVG has no hover panel, so its legend is the only decoding surface).
  • Exported root claims get a topbar banner with the current root belief, click-to-open-panel.

The shipped starmap_assets/template.html is rebuilt from viz/.

CLI docs drift (docs(cli))

The galileo and mendel CLI-authored walkthroughs and docs/reference/cli/author.md still showed --label as the Python-binding flag; the author verbs migrated to --dsl-binding-name (note/question/variable have no --label at all; claim's optional --label requires the binding flag; relation verbs treat --label as the engine label kwarg). Every invocation now matches what tests/cli/galileo_demo/test_equivalence.py actually runs on each PR gate; gaia bayes's own --label binding convention is documented as intentionally different.

Testing

  • make check green: 2936 passed (full suite), ruff + mypy --strict + hygiene hooks, 116 baseline snapshots unchanged-or-passing.
  • 14 new unit tests: reason extraction (steps / metadata / precedence), effect math incl. the multi-given gated-CPT lock, effect edge styling replaces (not appends) role styling, legend type-scoping and effect rows, _has_effect_edges gating.
  • End-to-end verified against a real nine-package portfolio: all previously-empty strategy reasons restored, edges colored by sign, zero-operator graphs no longer show operator legend rows, tsc --noEmit clean, template placeholder intact.
  • graph.json changes are purely additive keys; the in-repo consumers (_wiki/_obsidian/_inquiry/github export) read IR or the parameterization payload and are unaffected (their suites pass).

FK Guo added 4 commits July 9, 2026 23:15
An external portfolio of argument graphs surfaced four clarity gaps in
the starmap surfaces; all four are fixed across graph.json, the dot/SVG
emitter, and the interactive HTML:

- Strategy reasoning was silently dropped: the exporter read a
  top-level reason key that compiled IR never carries. It now joins
  steps[].reasoning (falling back to metadata.reason), so the side
  panel shows the author's recorded support/lowering rationale.
- Support vs lowering was not visually encoded. Strategy nodes and
  conclusion edges now carry a signed effect derived from the inline
  conditional-probability table (cp[-1] - cp[-2], the premise
  present/absent contrast at every given count); both renderers color
  scored edges on the same red-grey-green ramp and scale stroke width
  by magnitude, and the panel shows the probability pair plus an
  effect badge. Unscored strategy forms keep plain role styling.
- Compiler-generated helper knowledge nodes (metadata.generated) start
  collapsed with their incident edges, behind a default-off filter
  bucket, instead of dominating the force layout; search skips hidden
  nodes so the camera never recenters on an invisible match.
- Legends now tell the truth per graph: the HTML legend hides rows for
  absent kinds and gains the two edge-color rows; the stellaris SVG
  legend scopes glyph rows to the strategy/operator types actually
  present and documents the edge colors whenever the graph carries
  scored edges. Exported root claims get a topbar banner with the
  current root belief.

The shipped starmap template is rebuilt from viz/.
The galileo and mendel CLI-authored walkthroughs and the author
reference still showed --label as the Python-binding flag, a convention
the author verbs migrated away from: note/question/variable have no
--label at all, claim's optional --label needs --dsl-binding-name, and
the relation verbs treat --label as the separate engine label kwarg.
Every invocation now matches the flags the equivalence test actually
runs on each PR gate; the gaia bayes group's own --label binding
convention is documented as intentionally different, and equal's module
docstring no longer claims --label is required.
A node highlighted by an earlier search query and then hidden through
the type filter kept its boosted size and highlighted flag, so it
reappeared highlighted when its bucket was re-enabled. Hidden nodes
still never match a query, but they now always take the restore branch.
The observe reference showed only two of the three one-of input modes;
the inline-prose mode the mendel walkthrough uses was missing.
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