Brummel/Aura
1
0
Fork 0
Code Issues 31 Pull Requests Actions Packages Projects Releases Wiki Activity

Render a harness graph as an ASCII DAG via an aura graph subcommand #13

New Issue
Closed
opened 2026-06-04 18:53:17 +02:00 by Brummel · 1 comment
Brummel commented 2026-06-04 18:53:17 +02:00
Owner
Copy Link
Copy Source

Concern

The engine cannot display the topology of a wired graph. A harness is assembled
today as raw index lists — Harness::bootstrap(nodes, sources, edges) with
Edge { from: 0, to: 2, slot: 0, from_field: 0 } (see
fieldtests/cycle-0006-substrate/c0006_2_fanout_dag.rs:62) — whose correctness
cannot be eyeballed. A mis-wired but type-valid graph (e.g. fast/slow SMA inputs
swapped) compiles, bootstraps, and runs; nothing surfaces the mistake. C9 (design
ledger docs/design/INDEX.md) promises "the built graph is introspectable
runtime data"; no code realizes it yet.

Direction

Render a graph as an ASCII DAG to stdout, exposed as an aura graph CLI
subcommand (crates/aura-cli/src/main.rs is currently a scaffold with no
subcommands, sibling to the aura run subcommand of #8). This is the CLI-face
half of "structure before a run" (C14/C22).

Crate choice (verified by local test)

Two candidates were tested against the walking-skeleton wiring (price -> 2xSMA ->
Sub -> Exposure -> SimBroker -> sink):

  • ratatui-graph v0.1.0 — disqualified: the entire crate source is
    fn hello_world() {}; a parked name with no implementation, on the stale
    ratatui ^0.28.
  • ascii-dag v0.9.1 (MIT OR Apache-2.0) — works. Maintained (last push
    2026-03-26, 0 open issues), zero-dependency / no_std, Sugiyama layered
    layout, renders to a String, has subgraph/cluster support. The
    walking-skeleton DAG rendered correctly, diamond and all.

Constraints found while testing ascii-dag:

  • Node labels must be single-line — a newline in a label breaks the box drawing.
  • RenderMode::Horizontal collapses a DAG onto one path (drops fan-out
    branches); RenderMode::Vertical is required for any graph with fan-out.
  • Output is a String, not a ratatui widget — an interactive TUI shell would be
    a separate effort on top.

Two cut depths

  • Minimal cut (no engine change): a free render(labels, sources, edges) -> String over the pre-bootstrap wiring data (Edge/SourceSpec/Target
    are already pub), labels passed as a parallel &[&str], plus an aura graph subcommand rendering one built-in sample harness. Proves the
    integration but renders only a hardcoded example — names are bolted on, not
    intrinsic.
  • Useful cut: render any graph from a named, introspectable blueprint (the
    builder/blueprint layer, C9/C19). This is what makes "build signal X, show
    its graph" real, and it depends on the composite/builder work in #12.

Composites should render as ascii-dag subgraph (cluster) boxes once #12 lands.

Acceptance

  • ascii-dag added as a dependency of the rendering crate.
  • A graph -> ascii_dag::Graph adapter (Vertical mode, single-line labels).
  • aura graph prints an ASCII DAG to stdout.
  • A snapshot test pins the rendered output of a sample graph.
## Concern The engine cannot display the topology of a wired graph. A harness is assembled today as raw index lists — `Harness::bootstrap(nodes, sources, edges)` with `Edge { from: 0, to: 2, slot: 0, from_field: 0 }` (see `fieldtests/cycle-0006-substrate/c0006_2_fanout_dag.rs:62`) — whose correctness cannot be eyeballed. A mis-wired but type-valid graph (e.g. fast/slow SMA inputs swapped) compiles, bootstraps, and runs; nothing surfaces the mistake. C9 (design ledger `docs/design/INDEX.md`) promises "the built graph is introspectable runtime data"; no code realizes it yet. ## Direction Render a graph as an ASCII DAG to stdout, exposed as an `aura graph` CLI subcommand (`crates/aura-cli/src/main.rs` is currently a scaffold with no subcommands, sibling to the `aura run` subcommand of #8). This is the CLI-face half of "structure before a run" (C14/C22). ## Crate choice (verified by local test) Two candidates were tested against the walking-skeleton wiring (price -> 2xSMA -> Sub -> Exposure -> SimBroker -> sink): - `ratatui-graph` v0.1.0 — disqualified: the entire crate source is `fn hello_world() {}`; a parked name with no implementation, on the stale `ratatui ^0.28`. - `ascii-dag` v0.9.1 (MIT OR Apache-2.0) — works. Maintained (last push 2026-03-26, 0 open issues), zero-dependency / `no_std`, Sugiyama layered layout, renders to a `String`, has subgraph/cluster support. The walking-skeleton DAG rendered correctly, diamond and all. Constraints found while testing `ascii-dag`: - Node labels must be single-line — a newline in a label breaks the box drawing. - `RenderMode::Horizontal` collapses a DAG onto one path (drops fan-out branches); `RenderMode::Vertical` is required for any graph with fan-out. - Output is a `String`, not a ratatui widget — an interactive TUI shell would be a separate effort on top. ## Two cut depths - [ ] Minimal cut (no engine change): a free `render(labels, sources, edges) -> String` over the pre-bootstrap wiring data (`Edge`/`SourceSpec`/`Target` are already `pub`), labels passed as a parallel `&[&str]`, plus an `aura graph` subcommand rendering one built-in sample harness. Proves the integration but renders only a hardcoded example — names are bolted on, not intrinsic. - [ ] Useful cut: render any graph from a named, introspectable blueprint (the builder/blueprint layer, C9/C19). This is what makes \"build signal X, show its graph\" real, and it depends on the composite/builder work in #12. Composites should render as `ascii-dag` subgraph (cluster) boxes once #12 lands. ## Acceptance - [ ] `ascii-dag` added as a dependency of the rendering crate. - [ ] A graph -> `ascii_dag::Graph` adapter (Vertical mode, single-line labels). - [ ] `aura graph` prints an ASCII DAG to stdout. - [ ] A snapshot test pins the rendered output of a sample graph.
Brummel added the feature label 2026-06-04 18:53:17 +02:00
Brummel added this to the (deleted) milestone 2026-06-05 11:31:46 +02:00
Brummel added this to the Construction layer milestone 2026-06-05 12:58:12 +02:00
Brummel commented 2026-06-05 22:40:31 +02:00
Author
Owner
Copy Link
Copy Source

Delivered by cycle 0013 (spec/plan 0013-aura-graph-ascii-dag, feat 0a855c3, audit d97fada). aura graph renders a wired graph as an ASCII DAG in two views — clustered blueprint (composites as named boxes) and --compiled flat compilat (boundaries dissolved, C23) — with param-carrying node labels so a mis-wiring is visible. Acceptance met (ascii-dag dep in aura-cli, Vertical adapter, stdout render, frozen snapshot tests) plus the concern-defining swap test. Milestone fieldtest green (no bugs). Closing manually; the feat commit also carries closes #13 for when the branch is pushed.

Delivered by cycle 0013 (spec/plan 0013-aura-graph-ascii-dag, feat 0a855c3, audit d97fada). `aura graph` renders a wired graph as an ASCII DAG in two views — clustered blueprint (composites as named boxes) and `--compiled` flat compilat (boundaries dissolved, C23) — with param-carrying node labels so a mis-wiring is visible. Acceptance met (ascii-dag dep in aura-cli, Vertical adapter, stdout render, frozen snapshot tests) plus the concern-defining swap test. Milestone fieldtest green (no bugs). Closing manually; the feat commit also carries `closes #13` for when the branch is pushed.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
BLOCKER
Core functionality blocked; preempts other selection
 bug
Observable misbehaviour
 feature
Substantial extension; no full spec required
 idea
Droppable; no commitment
No Label feature
Milestone
No items
No Milestone Construction layer
Projects
Clear projects
No project
Assignees
Clear assignees
claude (Claude) Brummel
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Brummel/Aura#13
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?