vyges loom stt — CLI reference

Generated from vyges loom stt --help — this page is the tool’s own output, verbatim.

vyges loom stt — rectilinear Steiner minimal trees over a net's pin locations

USAGE:
  vyges loom stt run   <job.json>   [-o FILE] [--json]
  vyges loom stt batch <nets.json>  [-o FILE] [--json]
  vyges loom stt check <tree.json>  [-o FILE] [--json]
  vyges loom stt --describe
  vyges loom stt --help
  vyges loom stt --version

JOB FIELDS (`run`; `batch` takes an array of these, each with a `name`):
  x, y      required, equal length — the pin locations, in database units
  drvr      driver PIN INDEX (default 0) — an index into x/y, never a coordinate
  alpha     > 0 selects Prim-Dijkstra; 0 (the default) selects FLUTE

OPTIONS:
  -o FILE               write the report to FILE instead of stdout
  --json                emit JSON instead of the reference's printed tree
  -q, --quiet           raise the causal trail's floor to `error` (VYGES_LOG)
  -v, --verbose         lower it to `debug` — adds the per-net trail in `batch`
  --describe            print a machine-readable JSON description of the command
  --bug-report          file a bug (central: vyges/community)
  --feature-request     request a feature (central)
  --sponsor             sponsor Vyges (github.com/sponsors/vyges-ip)
  --star                star this tool on GitHub

EXIT STATUS:
  0  ok           a tree was built, or the check passed
  1  failed       the tree FAILED the self-overlap check — a finding, not an error
  2  vacuous      nothing was built: a net with no pins, or a batch of none. NOT a pass.
  2  error        usage, unreadable input, or a driver index that is not a pin
  3  refused      the engine declined to answer — see stderr for which path declined

Contract

Generated from vyges loom stt --describe.

stt

rectilinear Steiner minimal trees over a net’s pin locations (FLUTE and Prim-Dijkstra)

Maturity: workflow-validated

run {job}

Consumes: job

Artifacts: steiner_tree (report_path)

Assertion: steiner-tree-built — passes when status equals ok

Provenance limitations

• input_hash covers the argument vector, not the content of the job file it names.
• status is one of ok, failed, vacuous, refused or error. VACUOUS IS NOT OK: it means no tree was built because the input carried no pins, and the declared assertion passes only on ok, so a vacuous run fails it rather than signing off a net nothing was built for. Exit status is 0 for ok, 1 for a failed self-overlap check, 2 for vacuous and for error, 3 for refused.
• Correlated against the reference at the pin above, 2026-09-20, over every tree-producing case in the reference’s own test suite plus a 41-net gate of our own: 341 of 341 trees byte-identical, comparing the wire length, the path depth and every branch line of reportSteinerTree. That covers check, flute1, flute_gcd, pd1, pd2 and pd_gcd. A NUMBER HERE MEANS NOTHING WITHOUT THE BUILD: the reference’s own answer moves between its builds, so the pin is part of the claim.
• Two transcription details are UNWITNESSED: the f32 weight arithmetic in the Prim-Dijkstra search, and top_child_index taking the first maximum. Both are transcribed from the reference and neither changes any of the 341 trees, so no input we have distinguishes them from the alternatives.
• alpha > 0 selects Prim-Dijkstra, strictly. alpha = 0 never reaches it, which is the reference’s own branch and not a simplification. A Prim-Dijkstra tree that fails the self-overlap check is DISCARDED and FLUTE rebuilds the net; the JSON reports which builder answered, which the reference does not.
• A one-pin net at alpha 0 has no reportable tree: Flute::flute returns degree 1 with an empty branch vector, so there is no branch at the driver’s location. The reference raises STT-0007 and aborts on exactly this input; we report it rather than inventing a branch.
• Path depth is the longest root-to-leaf distance from the branch at the driver’s COORDINATES, not from the pin index passed in. That is the reference’s findLocationIndex, which exists because flute reorders the points.
• The FLUTE lookup tables are the reference’s own POWV9/POST9 data, fetched at build time from the pinned commit rather than vendored. Degrees above 9 go through the decomposition and the scoring heuristic, not the table.