Train 41: --path hop/route bodies, --defs lookup, Rust struct-field slots, Python handler rules, ranked caller hop

.github/pargates-shard-weights.json

@@ -240,6 +240,7 @@
 "greptiercheck.sh": 16.6,
 "guardmsgcheck.sh": 1.1,
 "handoffcheck.sh": 12.6,
+"handlerrulecheck.sh": 3.0,
 "hasacheck.sh": 2.7,
 "hazardpatterncheck.sh": 5.2,
 "headsnapcachecheck.sh": 19.9,

README.md

@@ -982,9 +982,9 @@ Full retrieval tables — including the MRR figures behind the router numbers ab
 ## What it answers
 
 <details>
-<summary><b>192 long flags</b> across seven families, plus the MCP server — and <code>--help-task</code> names the ONE command a task wants, or abstains honestly when the evidence is too thin</summary>
+<summary><b>193 long flags</b> across seven families, plus the MCP server — and <code>--help-task</code> names the ONE command a task wants, or abstains honestly when the evidence is too thin</summary>
 
-Around the core sit 192 long flags advertised in `--help`, across seven families — plus an MCP
+Around the core sit 193 long flags advertised in `--help`, across seven families — plus an MCP
 server, so a coding agent can call any of them mid-task instead of grepping and reading whole files.
 `--help` prints one line per flag (~4.5K tokens); `--help=--FLAG` prints that flag's full entry with
 every caveat, `--help=SECTION` one family, and `--help=all` the whole catalog.
@@ -2120,9 +2120,9 @@ wrong, and it has. These are the results that say so, all in-tree, all published
 ### In the tests
 
 <details>
-<summary><b>726 gate scripts</b>, five contracts no unit test can hold, and the house rule: write the gate before the code it measures</summary> <!-- gatecount -->
+<summary><b>729 gate scripts</b>, five contracts no unit test can hold, and the house rule: write the gate before the code it measures</summary> <!-- gatecount -->
 
-`test/regression.sh` names **726 gate scripts** and is the authoritative list; <!-- gatecount -->
+`test/regression.sh` names **729 gate scripts** and is the authoritative list; <!-- gatecount -->
 `python3 test/pargates.py . ./build/ripwire -j 6` runs the same set in parallel. On top of them sit the
 contracts that do not fit a unit test: two runs byte-identical, warm output identical to cold, output
 that pipes clean through `xmllint --noout`, a sanitizer build with `-fno-sanitize-recover=all`, and a
@@ -2684,7 +2684,7 @@ identity of the index, and says which one is at fault.
 
 ### 5. Command families
 
-The `--help` output groups 192 long flags advertised in `--help` into seven families. The `--help=`
+The `--help` output groups 193 long flags advertised in `--help` into seven families. The `--help=`
 column below is the argument that prints one family: `ripwire --help=navigate`. `ripwire
 --help=--FLAG` prints one flag's full text — the caveats, the units, what it refuses and why.
 `ripwire --help=all` is the whole catalog, about 46,000 tokens.
@@ -2878,7 +2878,7 @@ python3 test/pargates.py . ./build/ripwire -j 6
 A new gate script must be added to `test/regression.sh` in the same change. The gate
 `test/manifestcheck.sh` enforces this rule.
 
-Another gate derives the cap inventory. The tool has 287 compile-time caps and 7 ranking parameters.
+Another gate derives the cap inventory. The tool has 298 compile-time caps and 7 ranking parameters.
 `docs/LIMITS.md` lists each cap, its value, and whether the file discloses a truncation when the cap
 fires, and `python3 docs/limits_build.py --check` proves that list against `src/`. `docs/TUNING.md`
 lists the measured cost of each cap.

changelog.d/ci-flakes-3-memguard-b6b.md

@@ -0,0 +1,18 @@
+### Fixed — three flaky gate arms: memguardcheck (B6b, B21) and pargatescheck (I control)
+
+None is a product change; each arm depended on something the gate did not control.
+
+- `test/memguardcheck.sh` (B6b): the arm sent a `find_symbol a_02` as the second MCP call against an index cut by the crawl
+  trip at entry 30. Which fixture files survive that cut is the filesystem's directory order (the crawl does not sort before it
+  stops): on macOS `a/f02.c` is kept; on a Linux runner whose directory order places it later, `a_02` is outside the cut index and
+  the answer is a not-found error, which carries no `_memory_stop` envelope field, so the arm read an empty string (red on main
+  and on both train-40 PR runs, ubuntu release shard 4/4, green on rerun). The follow-up call is now `grep`, whose answer is a
+  result on any partial index, so the arm checks the same thing (a later answer from the same cut index keeps the disclosure) on
+  every filesystem; the `find_symbol` call stays as a third probe asserted on the shape it returns, with a NOTE line when it fell outside the cut.
+- `test/pargatescheck.sh` (I control): the control copy that puts the old "wait, then look at the stop" loop back waited 0.5 s
+  before looking, leaving 0.2 s for the probe gate to start and pass its 0.3 s mark; at load average 9 to 13 it failed three
+  runs of three on unmodified main. The control's first wait is now 3.0 s; the ordering defect it models is unchanged.
+- `test/memguardcheck.sh` (B21): the arm required the refusal to return within 4 s of a 6 s git-log stream, but the shim's 60
+  spawned sleeps stretch that stream on a busy host and the refusal took 5 s at load average 13 to 19. The arm now asks what a
+  join would do, which is wait for the stream's end: the shim writes a marker after its last line and the refusal must return
+  without it.

changelog.d/defs-lookup-verb.md

@@ -0,0 +1,11 @@
+### Added — `--defs=NAME[,NAME…]`: which definitions a name binds, with the spelling that picks each one alone
+
+One call answers "which definitions does this name bind?" for up to 16 names in one index load. Each definition group (a C-family
+prototype with the definition it declares is one; a TypeScript overload with its implementation is one) is a row with its
+owner-qualified name, kind, `file:line`, language, `class=source|test` and its distinct graph callers (a floor), plus `sel=`: a
+spelling every symbol verb accepts that the lookup re-resolved and proved binds that definition and nothing else (`name`,
+`file:name`, `file:Owner.name`, then the `@file:line` seed; `sel_proven="0"` when none does). Source rows come first, then by
+callers. A JSON/YAML key or a markdown heading of the same name is counted as `data_defs=` and never listed as code; a definition
+the parser does not model (an assignment, `define_method`, `setattr`) is not one. More than 16 rows page with `--offset`; a single
+name that binds nothing answers with the shared "not found" refusal. `--json` gives the same rows. The lookup lives in one header
+(`src/defslookup.h`, `rw::lookupDefs`), reusing the definition-group rule the callers/impact tables use.

changelog.d/for-wrapper-follow.md

@@ -0,0 +1,13 @@
+### Added — the `--for` body fold follows a one-line wrapper into the function it calls
+
+When a body the `--for` fold serves is a thin delegator (one proven callee, no other call, at most 3 statement lines, such as
+`fetch` returning `this.#dispatch(...)`), the callee's body is now printed right after it as `<b follow_of="fetch">`, up to two
+levels (`handle -> fetch -> #dispatch`). A callee bound by name alone, a body with a second call or a fourth statement line, and
+a body the answer already carries are never followed. The followed bodies ride outside the fold's `budget_bytes=`, each whole up
+to 4000 bytes (a longer one is cut and says so). `RIPWIRE_NO_HOP_BODY=1` turns it off.
+
+Measured: hono's default `--for "How does a request flow from app.fetch to a handler's Response?"` now carries `#dispatch`'s body
+(router match, Context, the one-handler fast path, `compose`, error handling) after `fetch` (+1.9 KB). Over the in-sample tables
+the follow fires on 3 of 163 S1 rows (+4.3 KB, all already complete), 2 of 39 MF1-DEV rows (+3.0 KB; ninja `Plan::AddTarget ->
+AddSubTarget`) and 3 of 56 LARGE-DEV rows (+5.7 KB, one body cut at the 4000-byte guard); no row loses an item.
+Gate: `test/hopbodycheck.sh`.

changelog.d/message-handler-rule.md

@@ -0,0 +1,29 @@
+### Added — a posted message class names its handlers (`via="name-key"`, `<handler_rule>` on `--path`)
+
+A Python message framework dispatches by a name the message's class carries: textual's `Message.__init_subclass__` writes
+`cls.handler_name = f"on_{name}"`, and the pump looks the handler up with `cls.__dict__.get( method_name )`. That lookup takes a
+parameter, so it can name every `on_*` method. The class is known where the message is posted, though:
+`self.post_message( Button.Pressed( self ) )` names `Button.Pressed`, and its handler is `on_button_pressed`. Such a post site
+is now a name-key hop to the methods of that name, with `cands=K` beside it. The hop shows in `--impact`
+(`reaches_hedged_via="name-key"`), in the `--path` hedged bridge (at most 16 candidates), and in `near_sink`, where a
+dispatched handler is now `why="declined:N" via="name-key"`, no longer `why="external"`. When `from=` is a poster and the
+posted classes name a `to=` handler, a reachable="0" `--path` also prints `<handler_rule>`. It holds the rule's `p=` and its
+spelling, the functions that read the handler-name attribute with the method each one passes it to (textual:
+`MessagePump._on_message` passes it to `MessagePump._get_dispatch_methods`, the MRO walk), and the posted classes, widest
+first. The handler definitions are listed only when there are at most 16 of them. Above that, the answer gives a count and
+`next=`, never a cut list.
+
+The rule is read from the repo's own source, never from a framework list. It needs a Python `__init_subclass__` with ONE
+top-level write `cls.A = f"P{v}"` (not under an `if`/`else`/`for`/`while`/`try`/`match`), where every assignment of the local
+`v` calls a camel-to-snake converter (a body holding the `[a-z][A-Z]` regex and `.lower()`) on `__qualname__`'s last two parts
+or on `cls.__name__`. A `{namespace}_` branch reads a `namespace="x"` class keyword. A class takes the NEAREST rule base (the
+most derived one); a class below an intermediate class whose own `__init_subclass__` also writes `cls.A` is not named, and two
+unrelated rule bases decline. A base written by name that several classes carry binds only through the deriving file's own
+import. Readers and posters are kept per rule. A post site is a call to a method of a class that reads `.A` outside test
+paths, with a first argument that constructs a subclass: `X( … )`, `self.X( … )`, `Owner.X( … )` or `module.X( … )`.
+
+What it does NOT mean: the name is matched, not traced. Which candidate runs depends on the receiving object's class, and the
+index does not decide that. A hop is never counted in `reaches=`, `reachable=` or `hops=`. The floors are: a variable
+argument (`msg = Tick(); post_message( msg )`); a factory (`events.Click.from_event( … )`); a converter or qualname cut of any
+other shape; `@on( Message )`-decorated handlers (already shown as value refs); and a class body's own `handler_name =`
+(the rule runs after the class body and overwrites it). Gate: `test/handlerrulecheck.sh`.

changelog.d/path-hop-body-fixes.md

@@ -0,0 +1,9 @@
+### Fixed — the middle-hop body and the wrapper follow say what they prove
+
+- A middle hop reached by name (`obj.process(x)` with two `process` definitions) prints its body with `via="name" cands="2"` on
+  the `<b>`, never as if it were the proven callee.
+- A `--for` wrapper follow needs a function or method whose text holds exactly one call site of any kind, that call its last
+  statement: a declined, external or undefined call beside it, logic around it, a loop aggregator or a class field initializer
+  is no wrapper. A C `*out = v;` line counts as a statement; a Python docstring does not.
+- `follow_of=` names the wrapper as its row does (`ChildRunner.launch`), and one answer follows at most 3 bodies; past that
+  `<follow_cut n= next=>` counts the wrappers left and names the first callee.

changelog.d/path-hop-body.md

@@ -0,0 +1,16 @@
+### Added — a short `--path` answer prints the body of its middle hop
+
+A reached `--path` (and MCP `path_between`) whose chain has 2 hops now prints, after its hop rows, the body of its
+middle hop inside `<bodies of="hops">`: the same `<b>` element `--expand` prints, without callee rows. The endpoints never get a
+body. Each body is whole up to 4000 bytes; a longer one is cut at a line end and says so on the element (`truncated="1"
+lines="1-K/T" next=` the call that serves the rest). A chain of more hops prints no body, and its root carries
+`next="--expand=…"` naming the first middle hop. Inside a `--for` answer's graph-verb block on the CLI, a middle hop whose body the
+answer already prints is not printed twice (MCP `for` has no served set to compare: a known divergence). `RIPWIRE_NO_HOP_BODY=1` turns it off.
+
+Why: `--path=fetch,compose` on hono named `Hono.fetch -> Hono.#dispatch -> compose` and stopped there, while the whole request
+flow (path extraction, router match, Context, the one-handler fast path, compose, error handling) lives in `#dispatch`'s body.
+Measured on the 163-row S1 replay: hono-12 goes from 0 to 6 of 7 required items (✗ -> ◐ by Rule C, ✗ -> ✓ legacy), 0 rows
+lower; 9 of the 15 `--path` rows change, +3.1 KB in total (hono-12 +2.1 KB, kysely-14 +0.5 KB, six longer chains +~90 B of
+`next=` each). The 2-hop gate is measured: 3 hops would add 1.6 KB on one already-complete row, 4 hops 13 KB on two more, and no
+item. On LARGE-DEV one `--for` graph-verb path block gains a middle body (zed `get_any_active_multi_workspace`, +1.0 KB) and seven
+gain only `next=`. Gate: `test/hopbodycheck.sh`.

changelog.d/path-inline-alternatives.md

@@ -0,0 +1,9 @@
+### Changed — `--path` lists the other definitions of an endpoint whose pick is not provably unique
+
+`--path=fetch,compose` on hono printed `from_defs="7"`, bound one `fetch` and named none of the others, so an agent had to guess a
+`file:name` spelling and retry. When an endpoint's name binds two or more definition groups, the answer (CLI and MCP
+`path_between`) now ends with `<alts side="from|to" of=NAME>`: one compact row per other definition with `p=`, `class=` and a
+pasteable `sel=`, and `decl_only="1"` when the row has no body (a header declaration or an interface contract). Up to 16 rows;
+past that `alts_shown=K defs=N next=--defs=NAME` pages the rest. A definition the answer already prints (the bound one, the
+endpoint of a listed `<pair>`, or a function whose body sits in `<bodies>`) is not listed again, and a C prototype no `#include` ties to a definition is not a second candidate
+(the rule `from_defs`/`to_defs` use), so an endpoint that binds one definition, or a `*` glob endpoint, adds nothing.

changelog.d/path-route-body.md

@@ -0,0 +1,13 @@
+### Added — an unreached `--path` prints the bodies of the route it names
+
+A `reachable="0"` `--path` (and MCP `path_between`) that names a route it could not trace — the bridge rows (a poster, the queue
+consumer, the dispatcher) and the `<handler_rule>` readers — now prints those functions' bodies in `<bodies of="route"
+proven="0">`: the bridge rows within 2 hops of `from=` (never `to=`), then the readers, at most 4 bodies (past that `capped="1"`
+and `next=` the first one left out), each whole up to 4000 bytes. Every body is a hedge: one under a crossing carries that hop's
+`via=` and `cands=` (`via="queue" cands="3"`), a reader's carries `via="name-key"`, and none of it enters `reachable=` or `hops=`.
+Inside a `--for` answer's graph-verb block it stays off (that answer serves its own bodies; the one in-sample fire there, a
+vscode `--for`, added 7.7 KB that named nothing the question asked). `RIPWIRE_NO_HOP_BODY=1` turns it off.
+
+Why: textual's `--path=post_message,on_*` named `post_message -> _process_messages_loop -> _dispatch_message` and the reader
+`_on_message`, but the answer to "how does a posted message reach its handler" lives in their bodies (the queue put, the loop's
+get, the bubble to `_parent`). Measured: textual-11 goes from 4 to 6 of 6 required items by Rule C (◐ -> ✓), +7.0 KB.

changelog.d/private-member-selectors.md

@@ -0,0 +1,7 @@
+### Fixed — a JS/TS private member resolves as the rows print it: `Hono.#dispatch`
+
+Train 40 started printing owner-qualified names (`n="Hono.#dispatch"`) on `--path`, `--callers` and `--callees` rows, but pasting
+one back failed: `--callees=Hono.#dispatch` answered "not found" and `--path=Hono.#dispatch,compose` exited 1 on hono, because the
+spelling splitter read the `#` as Ruby's `Class#method` separator and saw an empty segment. A `#` that starts a segment is now part
+of the name, so `Owner.#name` and `file:Owner.#name` bind the one private member they name; Ruby `Cart#total` reads as before, and
+`Owner.name` without the `#` still names nothing. Found while grading `--path` answers on hono. Gate: `test/writtenspellingcheck.sh` (1b).

changelog.d/py-alias-split-marker.md

@@ -0,0 +1,11 @@
+### Fixed — a module `__getattr__` no longer withholds a renamed-import call to a function the module defines
+
+A Python call through a renamed import (`from m import f as g; g()`) stayed undecided whenever `m` defined a module-level
+`__getattr__` (PEP 562), as if `__getattr__` could replace `m.f`. It cannot: Python consults it only for a name the module
+does not bind. The call now binds `m.f` as a proven edge in that case too, and a module `__getattr__` in the calling file no
+longer withholds it either. It still stays undecided when `f`'s definition in `m` sits inside an `if`, `try`, `with`, `match` or
+loop at module scope (it may not run, and `__getattr__` then answers), when `m` writes its namespace dynamically (`globals()[...]`,
+`setattr(...)`), and in every case listed for the renamed-import change. Known limit, unchanged: a module that rebinds a
+name some other way (`vars()[...]`, `locals()[...]`, `exec(...)`, `__dict__[...]`, `sys.modules[__name__].name = ...`) is not
+recognized as a dynamic write, so a pin into it can be wrong, now also in files that define `__getattr__`. On CPython's standard library this restores 11
+call sites (`re.sub`, `re.escape`, `re.compile`, `platform.system`, `platform.architecture`). Gate: `test/pyaliascallcheck.sh`.