sensorium-trace 0.18.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,571 @@
1
+ """One `exceptions` block per SHAPE on a Rust trace (design N3-N5).
2
+
3
+ WHY THE GRAIN MOVED
4
+ -------------------
5
+ `exceptions` printed one block per CHAIN, and on real work that is the
6
+ wrong unit. In the E6'''' workspace record the busiest process printed 54
7
+ blocks, 52 of them about ONE sink (`http.rs:236`), and the adjudicator who
8
+ had to read 782 such lines built a 91-row per-site table BY HAND before any
9
+ of it could be answered. That table is the grain the question is asked at,
10
+ so the tool prints it: two chains that earned the same disposition at the
11
+ same site, with the same words once their ids are masked, are one shape.
12
+
13
+ WHAT A GROUP IS KEYED ON, AND WHAT IT DELIBERATELY IS NOT
14
+ ---------------------------------------------------------
15
+ The key is the language's (`Renderer.key`): Rust's is `(tag, site, masked
16
+ verdict, route)` and TypeScript's `(tag, reason, site, masked verdict,
17
+ route)`, whose mask exempts nothing (§3.1, and `_typescript_key` for what
18
+ the exemption cost). The SITE is in both, and it is the one the verdict is
19
+ ABOUT -- the sink for a swallow, the arm for an escaped `Err`, and the
20
+ unit's ORIGIN for every verdict that names no site -- from the classifier
21
+ (`Disposition.site`), never from parsing the sentence back out of itself.
22
+
23
+ A site is `(file, line, qualname)`, not the `qualname L<line>` a verdict
24
+ PRINTS (ruling R-G12, 2026-09-05). The first rung-4 measurement keyed on the
25
+ printed text and the E6⁗ workspace had two `sandbox` helpers at L42 in
26
+ different test files, and two `fresh_dir`s at L64: 21 chains were booked
27
+ under a sibling file, with every count conserved, and one file vanished from
28
+ the answer entirely. Where the SAME answer prints two shapes whose site text
29
+ collides, each of their verdicts names its file -- `(sandbox L42 in
30
+ task_exec_run_test.rs)` -- and where nothing collides, which is every corpus
31
+ case and every answer a reader has already read, the notation does not move
32
+ at all.
33
+
34
+ The head and the detail are NOT in the key. Neither is the ROUTE, for a
35
+ verdict that names a site: keying a sink on the path would split it into as
36
+ many rows as there are ways to reach it, which is precisely the split the
37
+ hand-built table had to undo. But where the verdict names NO site -- where
38
+ the fallback site is the chain's own origin -- the route JOINS the key
39
+ (ruling R-G2, 2026-09-05), because there the recorded journey is what the
40
+ question is about: `corpus/rust/macro_arg_partial` pins a chain whose
41
+ MISSING hop is the visible consequence of a declared instrumentation gap,
42
+ and `outcome_generic` pins one recorded route against one that stops at a
43
+ signature. Merging those would have deleted the answer.
44
+
45
+ A group whose members differ in something the key did not look at is
46
+ FLAGGED rather than silently merged -- one extra line per differing set,
47
+ in the order `origins:` / `messages:` / `details vary` / `routes:`. Each
48
+ names how many distinct ones there are and where the reader can see one:
49
+ `(first shown)`, or `(this one has none)` where the printed member has no
50
+ such line (ruling R-G5) -- a flag must not point at a line that is not
51
+ there. `origins` counts SITES and `messages` the errors' rendered text
52
+ (ruling R-G6): one head line carries both, so counting heads called two
53
+ errors raised at one site "2 distinct origins". The route's line is spelled
54
+ `routes:` and not `hops:` (ruling R-G3): the corpus caught the first
55
+ spelling sharing its prefix with the real `hops:` line, where it
56
+ double-counted under every counter.
57
+
58
+ Ids are masked (`e412` -> `e#`, `f204` -> `f#`) everywhere a set is
59
+ compared: two chains absorbed by the same `.ok()` differ in every id they
60
+ carry, and a comparison that saw those differences would report every
61
+ group as varying and say nothing.
62
+
63
+ WHAT IS PRINTED, AND WHY IT IS STILL TRUE
64
+ -----------------------------------------
65
+ A group of N > 1 prints the FIRST member's block exactly as a lone chain
66
+ would be printed -- its head, its verdict with its own ids, its detail, its
67
+ hops -- and appends a bracket naming the group. Every printed sentence
68
+ therefore remains true of a NAMED chain; the bracket adds one fact (how
69
+ many, and which) rather than rewriting the sentence into a claim about all
70
+ of them, which would need a rewrite rule per verdict and could misstate a
71
+ member (design N4, amended before implementation).
72
+
73
+ The bracket lists each member's ORIGIN event id: the id on the head line
74
+ above it, the id `--after` filters on, and the id `grep`/`tree` take. Its
75
+ first entry is always the head's own id, so a reader can see at a glance
76
+ which member the block's sentences are about.
77
+ """
78
+ import re
79
+ from dataclasses import dataclass, field
80
+
81
+ # Rust and TypeScript import this module INSIDE `run` (the house idiom of
82
+ # `exceptions_cmd`). C does not import it at all: its single-trace lines
83
+ # are its own. All three are safe to take at module level here. `_at`
84
+ # names a site the way every verdict in those modules does, and
85
+ # `_hops_line` is the block's own last line. Rendering either a second time
86
+ # here would be two spellings of one journey.
87
+ from sensorium.query import exceptions_c, exceptions_rust, exceptions_typescript
88
+ from sensorium.query.fmt import fmt_event, fmt_exc
89
+
90
+ #: An event or frame reference in printed text. Anchored on word boundaries
91
+ #: so `e412` masks and `kind: NotFound` does not, and guarded against the
92
+ #: Rust FLOAT TYPE NAMES (ruling R-G8): `f32`/`f64` are spellings a panic
93
+ #: message or an error text carries -- *"expected f64, found f32"* -- and
94
+ #: masking them to `f#` merged two verdicts that name different types.
95
+ #: RUST'S ONLY: the TypeScript key uses `TS_MASK` below, which exempts
96
+ #: nothing, because this guard is about a spelling only Rust has.
97
+ MASK = re.compile(r"\b(?!f(?:16|32|64|128)\b)([ef])\d+\b")
98
+
99
+ #: The same reference, on the TypeScript wire, with NO exemption (ruling,
100
+ #: 2026-09-11). The carve-out above is Rust's type-name rule and nothing
101
+ #: else: `f32` and `f64` are how Rust spells a float, and a panic message
102
+ #: saying *"expected f64, found f32"* must keep its words. No type name on
103
+ #: THIS wire spells that way -- JavaScript has `number`, and the only
104
+ #: `f<n>` and `e<n>` a TypeScript verdict prints are ids this tool minted
105
+ #: -- so exempting four of them was a guard borrowed from a language whose
106
+ #: problem it is not, and it split one `useAiAssist` sink three ways
107
+ #: (frames 32, 128 and 174) on the rung-2 lens. That was Gap 1.
108
+ TS_MASK = re.compile(r"\b([ef])\d+\b")
109
+
110
+ #: How many ids a bracket names before it says only how many more there
111
+ #: are. A group of 303 is a fact about a site, not a list to read.
112
+ MAX_IDS = 8
113
+
114
+
115
+ def mask(text: str) -> str:
116
+ """`e412` -> `e#`, `f204` -> `f#`, in printed text only. `f64` and its
117
+ three siblings are type names, not frames, and are left alone."""
118
+ return MASK.sub(r"\1#", text)
119
+
120
+
121
+ def ts_mask(text: str) -> str:
122
+ """`e412` -> `e#`, `f204` -> `f#`, `f32` -> `f#`. Every id, in printed
123
+ TypeScript text: this recorder mints `e<n>` and `f<n>` and nothing on
124
+ its wire is spelled that way for another reason."""
125
+ return TS_MASK.sub(r"\1#", text)
126
+
127
+
128
+ def _masked(text: str | None, masker) -> str | None:
129
+ """A line that may not exist, masked by the LANGUAGE's own `masker`
130
+ (`Renderer.mask`) -- never by whichever mask this module imported
131
+ first, which would compare a TypeScript route by Rust's rule.
132
+
133
+ `None` is a member of these sets: a chain of one event has no hops
134
+ line and a verdict may carry no detail, and collapsing that to `""`
135
+ would make "some members have hops and some do not" read as "they all
136
+ agree"."""
137
+ return None if text is None else masker(text)
138
+
139
+
140
+ @dataclass(frozen=True)
141
+ class Renderer:
142
+ """The eight things this module has to ask a UNIT, in one row per
143
+ language (design P5).
144
+
145
+ The grouping GRAIN is not Rust's and never was -- two verdicts about
146
+ one place that say the same thing are one shape in any language. What
147
+ IS each language's own is how a place and a journey are SPELLED, and
148
+ -- since rung 3 -- what "the same thing" is decided on: Rust compares
149
+ its verdicts' masked prose, TypeScript the classifier's own components
150
+ (§3.1). Every one of those spellings already exists in that language's
151
+ rules module beside the verdicts that use it. Passing the functions
152
+ rather than re-deriving them here is what keeps the text the grouper
153
+ compares identical to the text the verdict prints: a second renderer
154
+ would be a second place for a site to be named, and the first thing
155
+ that drifts is the key.
156
+
157
+ `tag_order` rides along because the mode that groups a whole invocation
158
+ prints a tally, and its order is the members' language's (§4.3).
159
+
160
+ The fields are TRANSPOSABLE -- seven callables, plus `tag_order` -- so
161
+ both rows below are built with keywords: a positional list whose site
162
+ and whose site text swapped would type-check, run, and key every shape
163
+ on the wrong spelling (rung-2 review).
164
+ """
165
+ at: object # (trace, event) -> `qualname L<line>`
166
+ hops_line: object # (trace, unit) -> the route line, or None
167
+ site: object # (trace, event) -> (file, line, qualname)
168
+ site_text: object # (site) -> `qualname L<line>`
169
+ site_file: object # (site) -> the basename
170
+ tag_order: tuple # the dispositions, in printing order
171
+ key: object # (trace, unit, d, site, hops) -> the key
172
+ #: (text) -> the text with this recorder's ids masked. Rust's spares
173
+ #: four spellings its float types share (`MASK`); TypeScript's spares
174
+ #: nothing (`TS_MASK`). Every SET this module compares goes through it,
175
+ #: so a group's route and its detail are masked by the same rule its
176
+ #: key is -- two spellings of "the same words" would disagree at the
177
+ #: first sentence that carries an id one of them keeps.
178
+ mask: object
179
+
180
+
181
+ def _rust_key(trace, unit, d, site, hops):
182
+ """`(tag, site, masked verdict, route)` -- today's tuple, verbatim.
183
+
184
+ Rust keeps the prose key (design R3, decision P6). Its answers are
185
+ quoted by two acceptance records, by nineteen fenced tests and by every
186
+ Rust corpus case, and the component key is a rung-3 TypeScript change:
187
+ moving Rust to it would move bytes this slice promised not to.
188
+ `tests/test_exceptions_typescript_grouping.py` states this very tuple
189
+ as an equality, so a rewrite here fails a test rather than a record.
190
+
191
+ R-G2: the ROUTE is part of the key exactly where the verdict names no
192
+ site of its own -- there the chain's journey is the information the
193
+ reader came for, and `None` (no hops line at all) is a route like any
194
+ other. Where the verdict DOES name a site, the route stays out and a
195
+ difference is flagged instead.
196
+ """
197
+ return (d.tag, site, mask(d.verdict), hops if d.site is None else None)
198
+
199
+
200
+ def _typescript_key(trace, unit, d, site, hops):
201
+ """`(disposition, reason, site, masked verdict, route)` -- the
202
+ classifier's parts AND its sentence, under a mask that exempts nothing
203
+ (§3.1 as amended 2026-09-11, twice).
204
+
205
+ WHAT GAP 1 ACTUALLY WAS. One `catch` in `useAiAssist` absorbed three
206
+ throws, in frames 32, 128 and 174, and the rung-2 key printed three
207
+ blocks about one line. The cause was not that the key held the
208
+ sentence: it was that `MASK` exempts `f16`/`f32`/`f64`/`f128` because
209
+ RUST spells its float types that way (R-G8), so two of those three
210
+ frame ids survived masking as if they were type names. `TS_MASK` fixes
211
+ exactly that, and on this wire there is nothing for it to break: the
212
+ only `e<n>` and `f<n>` a TypeScript verdict prints are ids this tool
213
+ minted.
214
+
215
+ WHY THE SENTENCE STAYS. Dropping it merged things this recorder can
216
+ tell apart. Two re-raises from one origin whose last raises ended
217
+ differently (`-> swallowed` and `-> propagated`) are one key without
218
+ it; so are two propagations from one origin naming two different
219
+ failing tests. Both are distinctions the words carry and no component
220
+ does, and a block that printed one test name over a `[x2]` bracket
221
+ would be a sentence about the wrong run.
222
+
223
+ WHY THE ORIGIN IS NOT A COMPONENT OF ITS OWN. It enters only through
224
+ `site_of`'s fallback -- where the disposition names no site -- exactly
225
+ as rung 2's key did. An UNCONDITIONAL origin component splits a sink
226
+ by the places that reached it, which is the split the hand-built table
227
+ had to undo, and §3.2 says so in as many words: `origins: N distinct`
228
+ is how a shape reports the origins its key ignored. Three rung-2
229
+ SWALLOWED blocks carry that line -- `useBuilderContent.<anonymous>
230
+ L72` (3 origins), `GuardedButton.<anonymous> L29` (2) and
231
+ `createHooks.dispatch L98` (2) -- and an unconditional component would
232
+ have printed 32 places where the pre-registration locks 28.
233
+
234
+ The REASON is a component of its own even so, because two ambiguities
235
+ at one site that say no more for different reasons are two facts, and
236
+ their sentences can differ only in a clause a reader has to parse.
237
+
238
+ The ROUTE joins under the same condition as Rust's (R-G2): where the
239
+ verdict names no site, the recorded journey is the information the
240
+ reader came for. `hops` arrives already masked by THIS renderer's mask
241
+ (`group_units` masks it with `render.mask`), so it is used as given --
242
+ masking it a second time here would be a second spelling of one rule.
243
+ """
244
+ return (d.tag, d.reason, site, ts_mask(d.verdict),
245
+ hops if d.site is None else None)
246
+
247
+
248
+ def _c_key(trace, unit, d, site, hops):
249
+ """`(tag, site, masked verdict)`.
250
+
251
+ A signal raise names no sink and no route: the site is the RAISE's
252
+ own, and the verdict is the whole of what two of them can share.
253
+ `hops` is always absent (`exceptions_c._hops_line` returns None) and
254
+ is not a component, so a missing journey cannot split one crash.
255
+ """
256
+ return (d.tag, site, exceptions_c.mask(d.verdict))
257
+
258
+
259
+ RUST = Renderer(at=exceptions_rust._at,
260
+ hops_line=exceptions_rust._hops_line,
261
+ site=exceptions_rust._site,
262
+ site_text=exceptions_rust.site_text,
263
+ site_file=exceptions_rust.site_file,
264
+ tag_order=exceptions_rust.TAG_ORDER,
265
+ key=_rust_key, mask=mask)
266
+
267
+ TYPESCRIPT = Renderer(at=exceptions_typescript._at,
268
+ hops_line=exceptions_typescript._hops_line,
269
+ site=exceptions_typescript._site,
270
+ site_text=exceptions_typescript.site_text,
271
+ site_file=exceptions_typescript.site_file,
272
+ tag_order=exceptions_typescript.TAG_ORDER,
273
+ key=_typescript_key, mask=ts_mask)
274
+
275
+ C = Renderer(at=exceptions_c._at,
276
+ hops_line=exceptions_c._hops_line,
277
+ site=exceptions_c._site,
278
+ site_text=exceptions_c.site_text,
279
+ site_file=exceptions_c.site_file,
280
+ tag_order=exceptions_c.TAG_ORDER,
281
+ key=_c_key, mask=exceptions_c.mask)
282
+
283
+
284
+ @dataclass
285
+ class Shape:
286
+ """One printed block: the first chain of a group, and the group."""
287
+ #: The renderer's own (`Renderer.key`): Rust's `(tag, site, masked
288
+ #: verdict, route)`, TypeScript's `(tag, reason, site, masked verdict,
289
+ #: route)`.
290
+ key: tuple
291
+ tag: str
292
+ first: object # the first Chain of the shape, origin order
293
+ disposition: object # ITS Disposition -- the one printed
294
+ #: The site this shape is keyed on, `(file, line, qualname)`.
295
+ #:
296
+ #: Required, with no default: handed in by `group_units`, which passes
297
+ #: the very same local to the key function, so a shape whose site and
298
+ #: whose key disagree cannot be built. It defaulted to `None` and fell
299
+ #: back to `key[1]` until 2026-09-11, which was only ever right for
300
+ #: Rust -- the key's SHAPE has been the language's since rung 3, and
301
+ #: TypeScript's second component is the reason, not a place. A fallback
302
+ #: that is correct for one of two languages is a wrong answer waiting
303
+ #: for the second caller, so the argument is asked for instead.
304
+ site: tuple
305
+ #: The language that produced these units, so every printer below
306
+ #: reaches the right spelling from the shape it is handed rather than
307
+ #: from a parameter each caller would have to keep passing.
308
+ render: Renderer = RUST
309
+ chains: list = field(default_factory=list)
310
+ origins: set = field(default_factory=set) # origin SITES, `q L<line>`
311
+ messages: set = field(default_factory=set) # the origin errors' text
312
+ details: set = field(default_factory=set) # masked details (None ok)
313
+ hops: set = field(default_factory=set) # masked routes (None ok)
314
+ #: The FIRST member's detail and route, so a vary line can say whether
315
+ #: the block above it actually shows one of the things it counts.
316
+ first_detail: str | None = None
317
+ first_route: str | None = None
318
+
319
+
320
+ def _message(event) -> str:
321
+ """The origin error as the head line renders it: `type('msg')`. Every
322
+ chain event carries an `exc` (the index selects on `exc.kind == "err"`),
323
+ and this is the same `fmt_exc` call `fmt_event` makes for a RAISE or a
324
+ HANDLED, so the set counts exactly what a reader sees."""
325
+ exc = (event.payload or {}).get("exc")
326
+ return fmt_exc(exc) if exc else "?"
327
+
328
+
329
+ def site_of(trace, unit, d, render: Renderer = RUST) -> tuple:
330
+ """The site the verdict is ABOUT, as `(file, line, qualname)`.
331
+
332
+ The classifier names it where the sentence does (the sink, the arm, the
333
+ escaped handler); everywhere else the verdict speaks of the unit rather
334
+ than of a place, and its ORIGIN is the site a reader would group it by
335
+ -- read here as the same triple, so both kinds of key hold the same
336
+ kind of thing.
337
+ """
338
+ return d.site if d.site is not None else render.site(trace, unit.origin)
339
+
340
+
341
+ def collisions(shapes) -> set:
342
+ """The keys of the shapes whose printed site text names more than one
343
+ PLACE in this answer.
344
+
345
+ PLACES, not shapes. One site can wear several shapes without being
346
+ ambiguous at all -- two sinks on one line (`sink_ok` and
347
+ `sink_unwrap_or` at `load L31`), or a swallow and a
348
+ `handled_then_failed` at one place -- and those blocks already tell
349
+ themselves apart by their words. Counting shapes instead of places put
350
+ `in lib.rs` into answers that had nothing to disambiguate, which is the
351
+ byte-identity R-G12 promises to every answer that never collides
352
+ (review fix, 2026-09-05). What is ambiguous is a site TEXT that names
353
+ two different `(file, line, qualname)`s: both blocks say `sandbox L42`
354
+ and a reader cannot tell which sink each accuses.
355
+
356
+ The set is computed over the whole answer -- every shape the grouping
357
+ produced, not the page `--limit` will print -- because a block whose
358
+ sentence changed when the limit was raised would be a sentence about
359
+ the page rather than about the run.
360
+ """
361
+ at: dict[str, set] = {}
362
+ for shape in shapes:
363
+ at.setdefault(shape.render.site_text(shape.site),
364
+ set()).add(shape.site)
365
+ ambiguous = {text for text, places in at.items() if len(places) > 1}
366
+ return {shape.key for shape in shapes
367
+ if shape.render.site_text(shape.site) in ambiguous}
368
+
369
+
370
+ def group_units(trace, units, idx, classify, render: Renderer):
371
+ """`(shapes, tally, reasons)` -- shapes in order of FIRST APPEARANCE,
372
+ which is origin order because `units` is; the tally counts UNITS by
373
+ disposition and `reasons` counts the ambiguities by reason.
374
+
375
+ A UNIT is whatever the language's rules judge one at a time: a Rust
376
+ `Err` chain, a TypeScript RAISE. All this needs of one is an `origin`
377
+ event, and all it needs of the language is `render` -- so the rule that
378
+ two verdicts about one place with the same words are one block is
379
+ stated once and holds for both.
380
+
381
+ The KEY is the renderer's (`Renderer.key`): Rust's four components or
382
+ TypeScript's five. One dict holds either -- the shapes of one answer
383
+ are one language's, so two lengths are never compared. `lang` is
384
+ deliberately NOT in it: a member set is one language
385
+ (`exceptions_invocation` refuses a mixed one), so two languages' keys
386
+ are never in one dict to collide.
387
+
388
+ The tally is deliberately not a count of shapes: every record this tool
389
+ has produced reports dispositions per unit, and a tally that started
390
+ counting sites would stop being comparable with any of them (N5).
391
+
392
+ Both tallies are counted HERE and printed by the callers (P7): this is
393
+ the one pass that classifies every unit, and a caller that classified
394
+ them a second time to count them would be a second judgement of the
395
+ same record -- which is what rung 3's first cut shipped as an interim
396
+ and this replaces.
397
+ """
398
+ shapes: list[Shape] = []
399
+ by_key: dict[tuple, Shape] = {}
400
+ tally: dict[str, int] = {}
401
+ reasons: dict[str, int] = {}
402
+ for unit in units:
403
+ d = classify(trace, unit, idx)
404
+ tally[d.tag] = tally.get(d.tag, 0) + 1
405
+ # By the REASON, not by the tag: a Rust ambiguity carries none (the
406
+ # field is TypeScript's, §2.3), and counting tags here would grow a
407
+ # line in a Rust answer two acceptance records quote. That every
408
+ # TypeScript ambiguity HAS one is enforced at the source instead,
409
+ # by the reason-table test that walks `exceptions_typescript` for a
410
+ # verdict built without it -- a count cannot enforce it here
411
+ # without accusing the other language of a defect.
412
+ if d.reason is not None:
413
+ reasons[d.reason] = reasons.get(d.reason, 0) + 1
414
+ hops = _masked(render.hops_line(trace, unit), render.mask)
415
+ site = site_of(trace, unit, d, render)
416
+ key = render.key(trace, unit, d, site, hops)
417
+ shape = by_key.get(key)
418
+ if shape is None:
419
+ shape = Shape(key=key, tag=d.tag, first=unit, disposition=d,
420
+ site=site, render=render, first_detail=d.detail,
421
+ first_route=hops)
422
+ by_key[key] = shape
423
+ shapes.append(shape)
424
+ shape.chains.append(unit)
425
+ # R-G6: two sets, not one masked head line. A head carries the site
426
+ # AND the error's text, so counting heads reported two errors from
427
+ # ONE site as two origins -- `corpus/rust/err_stored`'s retry loop
428
+ # raises twice at `attempt L14` with `Refused(1)` and `Refused(2)`,
429
+ # which is one origin and two messages. Neither is masked: a site
430
+ # and an error's rendering carry no ids this tool assigned.
431
+ shape.origins.add(render.at(trace, unit.origin))
432
+ shape.messages.add(_message(unit.origin))
433
+ shape.details.add(_masked(d.detail, render.mask))
434
+ shape.hops.add(hops)
435
+ return shapes, tally, reasons
436
+
437
+
438
+ def group_chains(trace, chains, idx, classify):
439
+ """`group_units` over Rust `Err` chains, as `(shapes, tally)` -- the
440
+ name AND the arity every Rust caller and every Rust test already
441
+ types, kept so this generalisation moved no byte of the answer they
442
+ pin. A Rust disposition carries no reason, so the third value is always
443
+ empty and dropping it here loses nothing (P5)."""
444
+ shapes, tally, _reasons = group_units(trace, chains, idx, classify, RUST)
445
+ return shapes, tally
446
+
447
+
448
+ def bracket(shape: Shape, max_ids: int = MAX_IDS) -> str:
449
+ """` [×4: e412, e417, e420, e443]`, or `""` for a group of one.
450
+
451
+ Two leading spaces: it is appended to the verdict line, and a verdict
452
+ that ran straight into a bracket would read as part of the sentence.
453
+ """
454
+ n = len(shape.chains)
455
+ if n == 1:
456
+ return ""
457
+ ids = ", ".join(f"e{c.origin.id}" for c in shape.chains[:max_ids])
458
+ more = f", … +{n - max_ids}" if n > max_ids else ""
459
+ return f" [×{n}: {ids}{more}]"
460
+
461
+
462
+ def _which(present: bool) -> str:
463
+ """`(first shown)` -- unless the printed member has no such line at all,
464
+ in which case saying "first shown" points at nothing (ruling R-G5). A
465
+ flag whose parenthetical is false about the block it sits under is
466
+ worse than no flag."""
467
+ return "first shown" if present else "this one has none"
468
+
469
+
470
+ def vary_lines(shape: Shape) -> list[str]:
471
+ """What the key did not look at and the members do not agree on.
472
+
473
+ Only the sets with more than one member speak. A group that varies in
474
+ nothing prints nothing, so these lines mean something when they appear.
475
+ Order: where it came from (site, then error), then what the tool said
476
+ about it (detail), then how it travelled (route).
477
+ """
478
+ lines = []
479
+ if len(shape.origins) > 1:
480
+ lines.append(f"origins: {len(shape.origins)} distinct (first shown)")
481
+ if len(shape.messages) > 1:
482
+ lines.append(f"messages: {len(shape.messages)} distinct "
483
+ "(first shown)")
484
+ if len(shape.details) > 1:
485
+ lines.append(f"details vary ({len(shape.details)} distinct; "
486
+ f"{_which(shape.first_detail is not None)})")
487
+ if len(shape.hops) > 1:
488
+ lines.append(f"routes: {len(shape.hops)} distinct "
489
+ f"({_which(shape.first_route is not None)})")
490
+ return lines
491
+
492
+
493
+ def _disambiguated(verdict: str, shape: Shape) -> str:
494
+ """The verdict with the file added to the site it names:
495
+ `(sandbox L42)` -> `(sandbox L42 in task_exec_run_test.rs)`.
496
+
497
+ A substitution rather than a rewrite, and only of the FIRST occurrence:
498
+ the sentence goes on being a sentence about the block's own named
499
+ chain, with one more fact in the parenthetical it already had. A verdict
500
+ that names no site of its own carries no such parenthetical, and then
501
+ nothing is substituted -- the block keeps today's words, because there
502
+ is no place in it to put the file that would still be true.
503
+
504
+ Anchored on ` at e<id> (` -- the SITE EVENT's own id, which is what
505
+ makes that parenthetical the site's. Every verdict that names a place
506
+ spells it that way (`absorbed by <how> at e5 (...)`, `an Err(..) arm at
507
+ e11 (...)`), and an unanchored match would fire on the first
508
+ parenthetical that happened to read the same way and put the file in a
509
+ clause it is not true of (review fix, 2026-09-05).
510
+ """
511
+ text = shape.render.site_text(shape.site)
512
+ at_site = re.compile(r"( at e\d+ \()" + re.escape(text) + r"(\))")
513
+ named = f"{text} in {shape.render.site_file(shape.site)}"
514
+ # A function replacement, not a template: a file name is data and a
515
+ # backslash in one would be read as a group reference by `re.sub`.
516
+ return at_site.sub(lambda m: m.group(1) + named + m.group(2), verdict,
517
+ count=1)
518
+
519
+
520
+ def print_shape(trace, shape: Shape, bracket_text: str | None = None,
521
+ disambiguate: bool = False) -> None:
522
+ """One shape's block: the first member's chain, printed exactly as a
523
+ lone chain would be, plus the bracket naming the group.
524
+
525
+ `bracket_text` is passed by INVOCATION mode (`exceptions_invocation`),
526
+ whose bracket names processes rather than sibling event ids -- an id
527
+ list would name events of traces the reader did not ask about. The
528
+ block itself is the same one in both modes, printed here and nowhere
529
+ else: two renderers of one block are two places for the sentences to
530
+ drift apart.
531
+
532
+ `disambiguate` is set by the caller for a shape whose site text is not
533
+ unique in this answer (`collisions`), and adds the file's basename to
534
+ the verdict's parenthetical. It is off by default and off for every
535
+ answer with nothing to tell apart, which is why the corpus, the vectors
536
+ and every block a reader has already read print the same bytes as
537
+ before (R-G12).
538
+ """
539
+ chain, d = shape.first, shape.disposition
540
+ text = bracket(shape) if bracket_text is None else bracket_text
541
+ verdict = _disambiguated(d.verdict, shape) if disambiguate else d.verdict
542
+ print(" " + fmt_event(trace, chain.origin))
543
+ print(" " + verdict + text)
544
+ if d.detail:
545
+ print(" " + d.detail)
546
+ hops = shape.render.hops_line(trace, chain)
547
+ if hops:
548
+ print(" " + hops)
549
+ for line in vary_lines(shape):
550
+ print(" " + line)
551
+
552
+
553
+ def print_shapes(trace, shapes, limit: int) -> int:
554
+ """Print up to `limit` shapes; return how many were printed.
555
+
556
+ `limit` counts SHAPES (N5): a page that clipped chains would show part
557
+ of a group and name it `×52`, which is a printed block contradicting
558
+ its own bracket.
559
+
560
+ The collision set is computed over every shape of the answer before the
561
+ first block is printed, so which blocks name their file does not depend
562
+ on how many of them fit.
563
+ """
564
+ colliding = collisions(shapes)
565
+ shown = 0
566
+ for shape in shapes:
567
+ if shown >= limit:
568
+ break
569
+ print_shape(trace, shape, disambiguate=shape.key in colliding)
570
+ shown += 1
571
+ return shown