feat(art): draw what a wiring edge settles and what it only repeats

README.md

@@ -160,6 +160,8 @@ for r in results:
 
 ## Declared, not probed
 
+<p align="center"><img src="docs/art/edge-evidence.svg" alt="The six keys plexus discover returns for one wiring edge, one to a row, each with what settled it. Four are computed by discovery: the producing organ, the consuming organ, the capability that matched, and whether both ends are the same organ. One is copied out of a manifest without being read: via, the producer's own pointer at the code behind the port. One is a constant: evidence, always the word declared. The via row is accented, because it is the field that looks like a citation and is the one plexus never follows." width="100%"></p>
+
 Every edge is tagged `evidence: "declared"` and cites the **module** its producer
 names as the source (`file:function`). plexus does not import, resolve, or run
 that pointer, so the citation is a self-reported claim to check, not a verified

docs/art/plexus.art.json

@@ -137,5 +137,53 @@
         }
       ]
     }
+  ],
+  "cards": [
+    {
+      "file": "edge-evidence.svg",
+      "kicker": "declared, never probed",
+      "title": "What one wiring edge settles, and what it only repeats",
+      "source": "plexus discover --dir manifests",
+      "heads": [
+        "key",
+        "what settled it",
+        "what it does not settle"
+      ],
+      "fields": [
+        {
+          "key": "producer",
+          "value": "COMPUTED",
+          "note": "The organ whose emitted port satisfied the name. Only organs in the manifest set this run loaded can appear."
+        },
+        {
+          "key": "consumer",
+          "value": "COMPUTED",
+          "note": "The organ that named this capability among its own inputs."
+        },
+        {
+          "key": "capability",
+          "value": "COMPUTED",
+          "note": "The consumer's input name. A port satisfies it by equality, or by naming it in consumable_as."
+        },
+        {
+          "key": "self_loop",
+          "value": "COMPUTED",
+          "note": "True when both ends are the same organ. Reported rather than dropped, so a cycle stays visible in the plan."
+        },
+        {
+          "key": "via",
+          "value": "COPIED",
+          "tone": "drift",
+          "note": "The producer's own pointer at the code behind the port. plexus never resolves it, so a path at nothing reads as a real one."
+        },
+        {
+          "key": "evidence",
+          "value": "CONSTANT",
+          "note": "Always declared. The field is here to say the edge was matched on strings and that no tool was run."
+        }
+      ],
+      "alt": "The six keys plexus discover returns for one wiring edge, one to a row, each with what settled it. Four are computed by discovery: the producing organ, the consuming organ, the capability that matched, and whether both ends are the same organ. One is copied out of a manifest without being read: via, the producer's own pointer at the code behind the port. One is a constant: evidence, always the word declared. The via row is accented, because it is the field that looks like a citation and is the one plexus never follows.",
+      "footnote": "An edge forms by matching capability strings the manifests report about themselves. That is enough to settle who names what, and it is not enough to settle that the cited module exists or that the two sides compose. The edge carries a second pointer, the consumer's own module, which discover holds and never serializes, so it is not drawn here either."
+    }
   ]
 }

tests/test_repo_art.py

@@ -4,6 +4,7 @@
 the spec and compares bytes. This runs the gate under pytest and asserts on its receipt,
 so a drifted drawing fails the suite instead of quietly shipping."""
 
+import dataclasses
 import json
 import subprocess
 import sys
@@ -25,13 +26,18 @@
     "art.every_illustration_is_shown",
     "art.tagline_stays_inside_its_rule",
     "art.outcome_fits_its_box",
+    "art.card_draws_shapes_not_digits",
+    "art.card_text_fits_its_column",
+    "art.card_carries_one_mark",
+    "art.card_alt_reaches_the_readme",
     "art.the_gate_can_fail",
 )
 
 DRAWINGS = (
     "docs/art/plexus-header.svg",
     "docs/art/wiring-lane.svg",
     "docs/art/honesty-lane.svg",
+    "docs/art/edge-evidence.svg",
 )
 
 
@@ -70,3 +76,86 @@ def test_a_gate_that_cannot_fail_is_not_a_gate(tmp_path, monkeypatch):
     (tmp_path / "plexus.art.json").write_text(json.dumps(spec), encoding="utf-8")
     monkeypatch.setattr(gate, "ART", tmp_path)
     assert len(gate.check_outcome_fits_its_box([])) == 1
+
+
+# docs/art/edge-evidence.svg draws the six keys plexus discover returns for one
+# wiring edge and says, per key, whether discovery settled it or copied it. That
+# is a claim about mesh.py and cli.py, not about the picture, so nothing in
+# tools/ can settle it. Each row below is driven against a real mesh.
+sys.path.insert(0, str(_REPO / "src"))
+
+from plexus.cli import _mesh_json  # noqa: E402
+from plexus.manifest import Manifest, Port  # noqa: E402
+from plexus.mesh import Edge, discover  # noqa: E402
+from plexus.registry import builtin_manifests  # noqa: E402
+
+
+def _card() -> dict:
+    spec = json.loads(
+        (_REPO / "docs" / "art" / "plexus.art.json").read_text("utf-8"))
+    return next(c for c in spec["cards"] if c["file"] == "edge-evidence.svg")
+
+
+def _live() -> dict:
+    return _mesh_json(discover(builtin_manifests()))
+
+
+def test_the_card_draws_the_keys_an_edge_actually_comes_back_with():
+    """A key drawn that discover does not return, or one returned and not
+    drawn, makes the picture a description of a different tool."""
+    drawn = [f["key"] for f in _card()["fields"]]
+    returned = list(_live()["edges"][0])
+    assert drawn == returned
+
+
+def test_evidence_is_the_constant_the_card_says_it_is():
+    assert {e["evidence"] for e in _live()["edges"]} == {"declared"}
+
+
+def test_self_loop_is_computed_from_the_two_ends_and_kept():
+    """Drawn COMPUTED, and drawn as reported rather than dropped, so both
+    halves of that row need something that reaches them."""
+    edges = _live()["edges"]
+    assert all(e["self_loop"] == (e["producer"] == e["consumer"])
+               for e in edges)
+    assert any(e["self_loop"] for e in edges), "no self loop survived to check"
+
+
+def test_via_is_carried_through_without_being_read():
+    """Drawn COPIED. Point a producer's module at a path that is not in the
+    repository at all and the edge still forms, carrying that string as it was
+    written. Nothing between the manifest and the receipt opens it."""
+    nowhere = "src/does_not_exist.py:never_defined"
+    assert not (_REPO / "src" / "does_not_exist.py").exists()
+    pair = [
+        Manifest(organ="a", emits=[Port(capability="c/1", module=nowhere)]),
+        Manifest(organ="b", consumes=[Port(capability="c/1", module="b.py:f")]),
+    ]
+    edge = _mesh_json(discover(pair))["edges"][0]
+    assert edge["via"] == nowhere
+    assert edge["evidence"] == "declared"
+
+
+def test_the_marked_row_is_the_one_that_looks_like_a_citation():
+    """The accent claims via is the field a reader would take for proof. The
+    other five are drawn as settled, so the mark has to sit on via and the
+    accented row has to be the one the footnote is about."""
+    marked = [f["key"] for f in _card()["fields"]
+              if f.get("tone", "none") != "none"]
+    assert marked == ["via"]
+    assert [f["value"] for f in _card()["fields"] if f["key"] == "via"] \
+        == ["COPIED"]
+
+
+def test_the_footnote_second_pointer_is_held_and_never_returned():
+    """The footnote says the edge carries the consumer's own module too, and
+    that discover holds it without serializing it. Both halves, because a field
+    quietly added to the receipt would make the footnote wrong."""
+    fields = {f.name for f in dataclasses.fields(Edge)}
+    assert "consumer_module" in fields
+    assert "consumer_module" not in _live()["edges"][0]
+    pair = [
+        Manifest(organ="a", emits=[Port(capability="c/1", module="a.py:g")]),
+        Manifest(organ="b", consumes=[Port(capability="c/1", module="b.py:f")]),
+    ]
+    assert discover(pair).edges[0].consumer_module == "b.py:f"

tools/check_repo_art.py

@@ -25,17 +25,14 @@
 
 import render_repo_art as RENDER  # noqa: E402
 import repo_art as ART_LIB  # noqa: E402
+import check_repo_card as CARD_GATE  # noqa: E402
+import check_repo_flow as FLOW_GATE  # noqa: E402
 import repo_flow as FLOW  # noqa: E402
 
 ROOT = Path(__file__).resolve().parents[1]
 ART = ROOT / "docs" / "art"
 SCHEMA = "plexus.repo-art/v1"
 
-# The widest tagline that has been looked at on a rendered page. It counts
-# characters rather than measuring glyphs, so it cannot tell "mmmm" from
-# "iiii": a guardrail, not a typographic fact.
-TAGLINE_BUDGET = 70
-
 # Where an illustration lives. .github/assets/ and docs/brand/ are deliberately
 # outside this set: they hold the social-preview source and the flagship heroes,
 # which other gates already cover.
@@ -130,18 +127,7 @@ def check_note_survives_the_wrapper(_unused: list[Path]) -> list[str]:
     """Card notes wrap to three lines and the wrapper drops the rest, so an
     edited sentence can lose its ending in the drawing while reading fine
     in the spec."""
-    return _notes_the_wrapper_cuts(_loaded())
-
-
-def _notes_the_wrapper_cuts(specs: list[dict]) -> list[str]:
-    bad = []
-    for spec in specs:
-        for flow in spec.get("flows", []):
-            for stage in flow["stages"]:
-                drawn = " ".join(FLOW._wrap(stage["note"]))
-                if drawn != " ".join(stage["note"].split()):
-                    bad.append(f'{stage["title"]}: the drawing cuts off at "{drawn}"')
-    return bad
+    return FLOW_GATE.notes_the_wrapper_cuts(_loaded())
 
 
 def check_return_edge_stays_on_its_row(_unused: list[Path]) -> list[str]:
@@ -171,65 +157,19 @@ def check_every_illustration_is_shown(_unused: list[Path]) -> list[str]:
 def check_tagline_stays_inside_its_rule(_unused: list[Path]) -> list[str]:
     """The tagline is one unwrapped line under a rule that ends at x=700. Past
     that it runs on toward the aperture and nothing about the render fails."""
-    return _taglines_that_overrun(_loaded())
-
-
-def _taglines_that_overrun(specs: list[dict]) -> list[str]:
-    bad = []
-    for spec in specs:
-        tagline = spec["header"]["tagline"]
-        if len(tagline) > TAGLINE_BUDGET:
-            bad.append(f"{len(tagline)} characters runs past the rule: {tagline!r}")
-    return bad
-
-
-def _outcome_budgets(count: int) -> tuple[int, int]:
-    """Label and note budgets for one box in a band of `count` boxes."""
-    span = (FLOW.W - FLOW.PAD * 2 - FLOW.GAP * (count - 1)) / count
-    usable = span - 14 - 10
-    return int(usable / 7.0), int(usable / 5.4)
+    return FLOW_GATE.taglines_that_overrun(_loaded())
 
 
 def check_outcome_fits_its_box(_unused: list[Path]) -> list[str]:
     """An outcome box is one unwrapped label over one unwrapped note, and
     neither is clipped, so an over-long note runs into the next box."""
-    return _outcomes_that_overflow(_loaded())
-
-
-def _outcomes_that_overflow(specs: list[dict]) -> list[str]:
-    bad = []
-    for spec in specs:
-        for flow in spec.get("flows", []):
-            label_budget, note_budget = _outcome_budgets(len(flow["outcomes"]))
-            for item in flow["outcomes"]:
-                if len(item["label"]) > label_budget:
-                    bad.append(f'{item["label"]!r} is wider than its box')
-                if len(item["note"]) > note_budget:
-                    bad.append(f'the note under {item["label"]} is wider than '
-                               f'its box: {item["note"]!r}')
-    return bad
-
-
-# A spec built to break all three geometry budgets at once. Every other check
-# here reports clean, which says it ran and not that it works.
-CONTROL = [{
-    "header": {"tagline": "x" * (TAGLINE_BUDGET + 1)},
-    "flows": [{
-        "stages": [{"title": "CARD", "note": "word " * 60}],
-        "outcomes": [{"label": "OK", "note": "x" * 200},
-                     {"label": "y" * 200, "note": "short"}],
-    }],
-}]
+    return FLOW_GATE.outcomes_that_overflow(_loaded())
 
 
 def check_the_gate_can_fail(_unused: list[Path]) -> list[str]:
-    """Feed the three geometry checks input they have to reject."""
-    return [f"the gate missed {what}" for caught, what in (
-        (len(_notes_the_wrapper_cuts(CONTROL)) == 1, "a truncated note"),
-        (len(_taglines_that_overrun(CONTROL)) == 1, "a tagline past its rule"),
-        (len(_outcomes_that_overflow(CONTROL)) == 2,
-         "an over-wide label and an over-long note"),
-    ) if not caught]
+    """A gate that cannot fail is not a gate. Every check with a budget in it
+    gets handed input it has to reject, and anything that passes is named."""
+    return FLOW_GATE.control_failures() + CARD_GATE.control_failures()
 
 
 CHECKS = [
@@ -245,6 +185,7 @@ def check_the_gate_can_fail(_unused: list[Path]) -> list[str]:
     ("art.every_illustration_is_shown", check_every_illustration_is_shown),
     ("art.tagline_stays_inside_its_rule", check_tagline_stays_inside_its_rule),
     ("art.outcome_fits_its_box", check_outcome_fits_its_box),
+] + CARD_GATE.checks() + [
     ("art.the_gate_can_fail", check_the_gate_can_fail),
 ]