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,683 @@
1
+ """`exceptions` for `lang = rust`: what became of every `Err` that travelled.
2
+
3
+ WHY THIS IS A SEPARATE MODULE
4
+ -----------------------------
5
+ An `Err` is a VALUE being returned, not an exception unwinding, and almost
6
+ nothing the Python rules know transfers. `exceptions_cmd.Index` reads
7
+ ``exc["oid"]`` (Rust has no object identity), it lists RAISE events only (so
8
+ an `Err` returned by ``return Err(..)`` and absorbed by a caller's ``.ok()``
9
+ would come back as "no exceptions recorded"), and its rule 2 -- "a handler
10
+ frame that returned normally swallowed it" -- would report SWALLOWED for
11
+ every frame that re-returned an `Err` without ``?``. Each of those is a
12
+ confident wrong answer, which is why `exceptions` refused a Rust trace
13
+ outright until these rules existed (design R9).
14
+
15
+ WHAT THIS MODULE DECIDES, AND WHAT IT REFUSES TO
16
+ ------------------------------------------------
17
+ It decides DISPOSITIONS and nothing else. Chain IDENTITY -- which recorded
18
+ `Err` continues which, how many frames it crossed, whether the type changed
19
+ on the way, whether it was born in instrumented code -- is minted by the
20
+ converter's chain machine (`rust/cargo-sensorium/src/convert/chains`, design
21
+ §2a) and rides the events as ``chain``; how a chain ENDED rides its LAST
22
+ event as ``chain.terminal``. Those are facts about a record stream. This
23
+ module reads them and recomputes none of them: two places deriving one
24
+ verdict is two places for it to drift, and the converter's own suite is
25
+ where the machine is pinned.
26
+
27
+ ``terminal`` is deliberately not spelled in verdict words.
28
+ ``swallowed_candidate`` says a sink absorbed the chain and its holder frame
29
+ then returned ok, which is what a SWALLOWED verdict is made OF. The verdict
30
+ is issued here, with the wording that says how much the recording actually
31
+ supports.
32
+
33
+ THE FIVE DISPOSITIONS (design R8)
34
+ ---------------------------------
35
+ ``swallowed`` a written sink absorbed the chain and its frame returned ok.
36
+ The only accusation this command makes, and the one E6 gates.
37
+ ``panicked`` the frame holding the chain unwound. The verdict says that,
38
+ never that the panic happened BECAUSE of the `Err`.
39
+ ``returned-to-harness``
40
+ the chain left a frame the manifest marks ``test`` or
41
+ ``main`` -- it went back to libtest or out of `fn main`.
42
+ ``propagated`` still open when the thread ended, on a frame that is neither.
43
+ Only reachable where the thread was still live when the
44
+ recording ended (`live_threads`) or its frames were not all
45
+ instrumented, and the verdict says so -- never "INCOMPLETE",
46
+ which `info` keeps for a recording that never finalized.
47
+ ``ambiguous`` THE DEFAULT, for everything else and for every terminal these
48
+ rules do not know: a merged window, a bound-and-escaped arm,
49
+ an ok close with no sink, a sink whose frame then failed
50
+ anyway, a chain that left a spawned thread into a
51
+ `JoinHandle`. Nothing reaches SWALLOWED by falling through.
52
+
53
+ WHERE THE TRACE CANNOT SAY
54
+ --------------------------
55
+ There is no error identity on the wire, so a chain is followed by
56
+ ``(holder frame, type, Debug text)``: two `Err`s of one type with identical
57
+ text in one window are one chain, and a window holding two DIFFERENT `Err`s
58
+ is `merged` -- reported as ambiguous, never as a swallow. A truncated text
59
+ is no identity at all and matching falls back to the type alone, which can
60
+ only ever merge two chains, never split one.
61
+
62
+ The shapes the transformer does not probe (``let ... else``,
63
+ ``while let Err(..)``, ``.err()``, ``matches!``, or-patterns, let-chains,
64
+ `.is_err()`/`.is_ok()`) record nothing, so an `Err` they absorb reads
65
+ ambiguous -- `rust/HONESTY.md` names them. A `?` site the transformer could
66
+ not REACH is worse than unprobed and is reported at the top of the output
67
+ from ``meta.partial``: its silence would otherwise read as "nothing
68
+ happened there".
69
+ """
70
+ import shlex
71
+ from pathlib import Path
72
+
73
+ from sensorium.exit import ANSWERED, UNSETTLED
74
+ from sensorium.query import caps
75
+ from sensorium.query.exceptions_cmd import Disposition
76
+ from sensorium.query.fmt import fmt_exc, more_note
77
+
78
+ TAG_ORDER = ("swallowed", "panicked", "returned-to-harness", "propagated",
79
+ "ambiguous")
80
+
81
+ # The literal token `SWALLOWED` is printed by ONE sentence in this module --
82
+ # `_swallowed`'s verdict -- and by nothing else, not even by prose saying a
83
+ # shape is never one. E6's cross-case collector counts printed SWALLOWED
84
+ # lines and compares the set whole (design R15), so a detail line reading
85
+ # "never SWALLOWED" would enter that count as a false accusation nobody
86
+ # made. Every other mention is spelled "a swallow".
87
+
88
+ # How many `partial` rows the header names before it starts counting. The
89
+ # list is one row per unreachable `?` site across every registered unit --
90
+ # order 400 on a real workspace -- and a header that scrolled the answer off
91
+ # the screen would be worse than the silence it exists to break.
92
+ PARTIAL_SHOWN = 3
93
+
94
+
95
+ class Chain:
96
+ """Every event of one `Err` chain, in trace order.
97
+
98
+ Keyed by ``(thread, chain.serial)``: chain serials are minted PER THREAD
99
+ (from ``1 << 32``), so two threads legitimately carry the same number
100
+ and merging them would report two programs' errors as one.
101
+ """
102
+
103
+ def __init__(self, key, events):
104
+ self.key = key
105
+ self.events = events
106
+
107
+ @property
108
+ def origin(self):
109
+ return self.events[0]
110
+
111
+ @property
112
+ def last(self):
113
+ return self.events[-1]
114
+
115
+ @property
116
+ def terminal(self):
117
+ """How the chain ended, read off its LAST event and nowhere else.
118
+
119
+ Absent is a real answer: a chain the machine never closed carries
120
+ no terminal, and inventing one here would put a verdict in the
121
+ converter's mouth.
122
+ """
123
+ return _chain(self.last).get("terminal")
124
+
125
+ @property
126
+ def born_outside(self) -> bool:
127
+ return _chain(self.origin).get("origin") == "outside"
128
+
129
+ @property
130
+ def hops(self) -> int:
131
+ """The furthest hop any of this chain's events reached. Read, not
132
+ counted: an event that absorbs a chain without crossing a frame
133
+ carries the hop it happened AT, so `len(events)` is not it."""
134
+ return max((_chain(e).get("hop") or 1) for e in self.events)
135
+
136
+
137
+ def _chain(event) -> dict:
138
+ return ((event.payload or {}).get("chain")) or {}
139
+
140
+
141
+ def _how(event) -> str:
142
+ return (event.payload or {}).get("how") or "?"
143
+
144
+
145
+ def _site(trace, e) -> tuple:
146
+ """The site an event IS: `(file, line, qualname)` -- the code object's
147
+ file, the event's own line, and the code object's qualname.
148
+
149
+ The identity, not the rendering. Two `sandbox` helpers in two test files
150
+ each holding a `let _ =` at L42 print the same words and are not the
151
+ same place, and the first rung-4 measurement keyed on the words: 18 of
152
+ the workspace's chains were booked under a sibling file while every
153
+ count stayed right (ruling R-G12, `docs/planning/acceptance/
154
+ 2026-09-05-sensorium-rung4-entry-grain.md` §4.3/§5.1). A code object
155
+ this trace does not carry is `("?", line, "?")` -- the same `?` `_at`
156
+ printed before there was a triple, so a site with no code object is
157
+ still one site and not a crash.
158
+ """
159
+ code = trace.code(e.code_id) if e.code_id is not None else None
160
+ return ((code.file if code is not None else "?"), e.line,
161
+ (code.qualname if code is not None else "?"))
162
+
163
+
164
+ def site_text(site) -> str:
165
+ """`qualname L<line>` -- the way every verdict in this module names a
166
+ place, and the only spelling of it: `_at` renders through here, so the
167
+ text the grouper compares for a COLLISION cannot drift from the text the
168
+ verdict prints."""
169
+ _file, line, qualname = site
170
+ return f"{qualname} L{line}"
171
+
172
+
173
+ def site_file(site) -> str:
174
+ """The site's file, basename only. What a colliding block adds to its
175
+ verdict (`sandbox L42 in task_exec_run_test.rs`): the full path is in
176
+ the trace for anyone who wants it, and the basename is what tells two
177
+ same-named helpers apart on one line."""
178
+ return Path(site[0]).name
179
+
180
+
181
+ def _at(trace, e) -> str:
182
+ return site_text(_site(trace, e))
183
+
184
+
185
+ class Index:
186
+ """Everything the disposition rules read, gathered in one pass.
187
+
188
+ Selection is by ``exc.kind == "err"`` and never by ``type == "panic"``
189
+ (design R7): a workspace error type spelled `panic` is an `Err` like any
190
+ other, and a panic RAISE is not a chain at all. The panics are counted
191
+ rather than dropped -- an answer of "no exceptions recorded" about a run
192
+ that panicked is a false negative.
193
+ """
194
+
195
+ def __init__(self, trace):
196
+ self.trace = trace
197
+ meta = trace.meta
198
+ self.incomplete = bool(meta.get("incomplete"))
199
+ self.partial = meta.get("partial")
200
+ self.marks = _marks(meta)
201
+ self.panics = 0
202
+ groups: dict = {}
203
+ for e in trace.events(kind=("RAISE", "HANDLED")):
204
+ exc = (e.payload or {}).get("exc") or {}
205
+ kind = exc.get("kind")
206
+ if kind == "panic":
207
+ self.panics += 1
208
+ continue
209
+ if kind != "err":
210
+ continue
211
+ serial = _chain(e).get("serial")
212
+ # A chain object a converter failed to write leaves the event
213
+ # its own chain of one rather than dropping it: an unreported
214
+ # `Err` is the one outcome this command must never produce.
215
+ key = (e.thread_id, serial) if serial is not None else ("e", e.id)
216
+ groups.setdefault(key, []).append(e)
217
+ self.chains = sorted((Chain(k, v) for k, v in groups.items()),
218
+ key=lambda c: c.origin.id)
219
+
220
+ def frame_of(self, e):
221
+ return (self.trace.frame(e.frame_id)
222
+ if e.frame_id is not None else None)
223
+
224
+ def unwound_holder(self, e):
225
+ """The frame that unwound while holding this chain.
226
+
227
+ The holder is not on the wire, and it is not always the frame the
228
+ chain's last event fired in -- a chain hops UP when its frame closes
229
+ `err`, and the close is a RETURN, which is no event of the chain's.
230
+ But every frame between the last event's frame and the holder closed
231
+ by RETURNING (that is what `err`/`none`/`ok` are), so the INNERMOST
232
+ frame that unwound, walking outward from the last event's frame, is
233
+ the holder. Derived rather than assumed, and `None` where the walk
234
+ finds nothing -- in which case the verdict quotes no panic.
235
+ """
236
+ f = self.frame_of(e)
237
+ seen = 0
238
+ while f is not None and seen < 512: # a cycle is a corrupt trace
239
+ if f.closed_by == "unwind" and f.unwind_exc:
240
+ return f
241
+ f = (self.trace.frame(f.parent_id)
242
+ if f.parent_id is not None else None)
243
+ seen += 1
244
+ return None
245
+
246
+ def harness_holder(self, e):
247
+ """The frame a chain that ended at THREAD_END was sitting in, as
248
+ `(frame, mark, still_open)`; `(None, None, False)` where there is no
249
+ frame to name.
250
+
251
+ NOT "the innermost MARKED ancestor", which is the fix-round-1 bug:
252
+ a `#[test] fn t()` calling a bin crate's `main()` that re-returns an
253
+ `Err` puts the chain's last event inside `main` -- marked `main` --
254
+ while §2a moved the holder OUT of `main` the moment it closed `err`,
255
+ into `t`. Naming the innermost mark reported the binary's entry
256
+ point for a chain the test harness received.
257
+
258
+ The converter's own rule (`chains`, M4) is the one followed here:
259
+ the holder is the frame the chain SITS in whenever that frame is
260
+ still on the stack, and the frame it LEFT once the holder is gone.
261
+ A frame still on the stack at THREAD_END is one with no close
262
+ recorded, so the search is for the innermost ancestor-or-self that
263
+ is still open; with every ancestor closed, the frame it left is the
264
+ last event's own -- which is where an `Err` returned out of a
265
+ `#[test]` fn puts it.
266
+
267
+ The mark is then taken from THAT frame and no other. Walking on to
268
+ find a mark is what produced the wrong answer, so an unmarked holder
269
+ earns the no-mark verdict rather than a borrowed claim.
270
+ """
271
+ f = self.frame_of(e)
272
+ holder, seen = None, 0
273
+ while f is not None and seen < 512:
274
+ if f.closed_by is None and f.return_event_id is None:
275
+ holder = f
276
+ break
277
+ f = (self.trace.frame(f.parent_id)
278
+ if f.parent_id is not None else None)
279
+ seen += 1
280
+ still_open = holder is not None
281
+ if holder is None:
282
+ holder = self.frame_of(e)
283
+ if holder is None:
284
+ return None, None, False
285
+ code = (self.trace.code(holder.code_id)
286
+ if holder.code_id is not None else None)
287
+ mark = self.marks.get((code.qualname, code.file)) if code else None
288
+ return holder, mark, still_open
289
+
290
+
291
+ def _marks(meta) -> dict:
292
+ """`(qualname, absolute file)` -> `"test"` / `"main"`, from `meta.sites`.
293
+
294
+ The site table's `file` is workspace-relative and a trace's
295
+ `code_objects.file` is absolute, so the join is a path-segment suffix
296
+ (`"/w/demo/src/lib.rs"` ends with `"/demo/src/lib.rs"`) rather than a
297
+ bare `in`, which would let `oo/src/lib.rs` match `foo/src/lib.rs`. The
298
+ dict is keyed lazily: `Index.marked_holder` asks with the absolute path
299
+ it has, so the lookup is built as a callable-shaped dict of exactly the
300
+ pairs the site table declares -- see `_MarkTable`.
301
+ """
302
+ rows = meta.get("sites") or []
303
+ return _MarkTable([r for r in rows
304
+ if r.get("kind") in (None, "fn", "closure")
305
+ and (r.get("test") or r.get("main"))])
306
+
307
+
308
+ class _MarkTable:
309
+ """A lookup whose keys are `(qualname, absolute file)` pairs it has
310
+ never seen: `get` resolves the suffix join on demand. Two rows of one
311
+ qualname that disagree resolve to NO mark rather than to whichever was
312
+ listed first -- a mark this table cannot pin down is one the verdict
313
+ must not claim."""
314
+
315
+ def __init__(self, rows):
316
+ self._rows = rows
317
+
318
+ def get(self, key, default=None):
319
+ qualname, file = key
320
+ found = {("main" if r.get("main") else "test") for r in self._rows
321
+ if r.get("qualname") == qualname
322
+ and _same_file(file, r.get("file") or "")}
323
+ return found.pop() if len(found) == 1 else default
324
+
325
+
326
+ def _same_file(absolute: str, relative: str) -> bool:
327
+ return bool(relative) and (absolute == relative
328
+ or absolute.endswith("/" + relative))
329
+
330
+
331
+ # -- the disposition table (design R8) --------------------------------------
332
+ # The `how` values that ABSORB an `Err` -- the sinks of design R2 plus a
333
+ # handling arm. `_absorbed` names the site only for these: a terminal that
334
+ # says a chain was absorbed can ride any event a converter chooses to put it
335
+ # on, and naming a `?` as the thing that swallowed an `Err` would be this
336
+ # command inventing a site from a key it merely happened to read.
337
+ ABSORBING_HOWS = ("sink_ok", "sink_unwrap_or", "sink_let_underscore",
338
+ "arm_handled")
339
+
340
+
341
+ def _absorbed(trace, h) -> str:
342
+ if _how(h) in ABSORBING_HOWS:
343
+ return f"absorbed by {_how(h)} at e{h.id} ({_at(trace, h)})"
344
+ return f"absorbed at e{h.id} ({_at(trace, h)})"
345
+
346
+
347
+ def _swallowed(trace, chain, idx) -> Disposition:
348
+ """The one accusation this command makes, and the whole reason its bar
349
+ is high: a WRITTEN sink absorbed the chain and the frame holding it then
350
+ returned ok. The sink is the chain's last event, so the frame it fired
351
+ in IS the holder (§2a admits an absorb only where the two are one)."""
352
+ h = chain.last
353
+ fid = h.frame_id
354
+ where = f" in f{fid}" if fid is not None else ""
355
+ # R8, amended 2026-09-04 (Task 7's `join_handle`): the chain machine is
356
+ # PER THREAD, so a HANDLED that opens no chain means only that no chain
357
+ # was open ON THIS THREAD -- the `Err` may have been made in dependency
358
+ # code, or in an instrumented frame on another thread and carried across
359
+ # a `JoinHandle`. The wording before the amendment named dependency
360
+ # code outright, and asserted that about both.
361
+ #
362
+ # Amended again 2026-09-08 (blind spot R16 (v)): a THIRD shape reaches
363
+ # here. An `Err` born in an instrumented CALLEE and handed to this frame
364
+ # by value closes its chain when that callee returns, so the sink here
365
+ # matches no open chain either -- and the sentence said it was born
366
+ # outside this thread's instrumented frames when it had been born inside
367
+ # one, a frame away, sending a reader out of the workspace to look for
368
+ # an error the workspace raised. What the record holds is that no chain
369
+ # was open where it was absorbed; where it was born is exactly what it
370
+ # does not say, so the reading it does support leads and the two shapes
371
+ # it may be follow.
372
+ detail = ("no chain of this thread was open where it was absorbed -- "
373
+ "born outside this thread's instrumented frames, or handed to "
374
+ f"this one by value from one of them; absorbed at {_how(h)}"
375
+ if chain.born_outside else None)
376
+ return Disposition(
377
+ "swallowed",
378
+ f"SWALLOWED -- {_absorbed(trace, h)}{where}, which returned ok",
379
+ detail, site=_site(trace, h))
380
+
381
+
382
+ def _panicked(trace, chain, idx) -> Disposition:
383
+ f = idx.unwound_holder(chain.last)
384
+ if f is None:
385
+ return Disposition(
386
+ "panicked", "panicked -- the frame holding it unwound",
387
+ "no unwound frame is recorded on this chain's own frame or any "
388
+ "of its callers, so the panic cannot be quoted")
389
+ return Disposition(
390
+ "panicked",
391
+ f"panicked -- the frame holding it unwound "
392
+ f"(f{f.id}, {fmt_exc(f.unwind_exc)})",
393
+ f"the trace says f{f.id} unwound while holding this Err, not that "
394
+ "the Err caused the panic")
395
+
396
+
397
+ _MARK_WORDS = {"test": "a #[test] fn", "main": "the bin crate's fn main"}
398
+
399
+
400
+ def _returned_to_harness(trace, chain, idx) -> Disposition:
401
+ """The chain went back to libtest or out of `fn main`.
402
+
403
+ Two verbs, because two things happen. A frame that CLOSED handed the
404
+ `Err` out of itself -- "it left f3". A frame still on the stack when the
405
+ thread ended never returned at all, and the chain is sitting in it --
406
+ "it came to rest in f1", with the detail saying the recording stopped
407
+ before that frame finished. Printing "left" there would claim a return
408
+ this trace never saw.
409
+ """
410
+ f, mark, still_open = idx.harness_holder(chain.last)
411
+ if f is None or mark is None:
412
+ return Disposition(
413
+ "returned-to-harness",
414
+ "returned to the harness -- it left a frame the recording marks "
415
+ "as a test or main entry point",
416
+ "the site table carries no row naming which of the two, so the "
417
+ "disposition stands without the claim")
418
+ q = trace.code(f.code_id).qualname
419
+ if still_open:
420
+ return Disposition(
421
+ "returned-to-harness",
422
+ f"returned to the harness -- it came to rest in f{f.id} ({q}), "
423
+ f"which the manifest marks as {_MARK_WORDS[mark]}",
424
+ f"f{f.id} had not returned when the recording ended, so what the "
425
+ "harness did with the Err is the next thing that would have "
426
+ "happened, not something this trace watched")
427
+ return Disposition(
428
+ "returned-to-harness",
429
+ f"returned to the harness -- it left f{f.id} ({q}), which the "
430
+ f"manifest marks as {_MARK_WORDS[mark]}")
431
+
432
+
433
+ def _propagated(trace, chain, idx) -> Disposition:
434
+ return Disposition(
435
+ "propagated",
436
+ f"propagated -- {chain.hops} hops, and still open when the thread "
437
+ "ended",
438
+ "a chain still open at the end of a thread means the thread was "
439
+ "still live when the recording ended (`live_threads`) or its frames "
440
+ "were not all instrumented; every hop it took is listed below")
441
+
442
+
443
+ #: The one sentence the tool prints under an escaped arm. It is a QUOTATION
444
+ #: of §11's SWALLOWED definition (design N2, 2026-09-05), which lives in
445
+ #: `rust/HONESTY-ERR-FLOW.md` since 2026-09-06 -- §11 still names what it
446
+ #: always named, one file away:
447
+ #: reading the error -- a guard, a predicate -- does not carry it out of the
448
+ #: arm; only a value derived from it leaving the arm does.
449
+ ESCAPED_DETAIL = ("a bound error that is stored, returned or moved out of the arm "
450
+ "is not a swallow; an arm that only reads it (a guard, a "
451
+ "predicate), formats or logs it and continues is one")
452
+
453
+
454
+ def _escaped(trace, chain, idx) -> Disposition:
455
+ """Two shapes wear one terminal, and the `how` of the last event says
456
+ which: an `arm_ambiguous` HANDLED bound the error to a name and let the
457
+ name escape, and anything else is a frame that returned ok with nothing
458
+ recorded absorbing what it held.
459
+
460
+ Only the MOVE is ambiguous. An arm that borrows the error to format it
461
+ and then carries on is an `arm_handled` and reaches `_swallowed`: the
462
+ failure never got past that arm, and the log is where it went
463
+ (`rust/HONESTY-ERR-FLOW.md` §11, the definition's one home).
464
+ `corpus/rust/err_stored` and `corpus/rust/logged_arm` are the two sides
465
+ of that line.
466
+ """
467
+ e = chain.last
468
+ if _how(e) == "arm_ambiguous":
469
+ return Disposition(
470
+ "ambiguous",
471
+ f"ambiguous -- an Err(..) arm at e{e.id} ({_at(trace, e)}) bound "
472
+ "it to a name and let the name escape",
473
+ ESCAPED_DETAIL, site=_site(trace, e))
474
+ return Disposition(
475
+ "ambiguous",
476
+ "ambiguous -- the frame holding it returned ok with no sink recorded",
477
+ "it left the grammar this recorder watches (rust/HONESTY-ERR-FLOW.md "
478
+ "§11 and rust/HONESTY-BLIND-SPOTS.md items 15-26 name the shapes "
479
+ "that are not probed); no sink recorded is not evidence that "
480
+ "nothing absorbed it")
481
+
482
+
483
+ def _merged(trace, chain, idx) -> Disposition:
484
+ return Disposition(
485
+ "ambiguous",
486
+ "ambiguous -- it shared a frame's window with another, different Err",
487
+ "identity across hops is (type, Debug text) and a window holding two "
488
+ "distinct Errs cannot be split, so a merged window is never reported "
489
+ "as a swallow")
490
+
491
+
492
+ def _handled_then_failed(trace, chain, idx) -> Disposition:
493
+ h = chain.last
494
+ fid = h.frame_id
495
+ where = f" in f{fid}" if fid is not None else ""
496
+ tail = f"f{fid} then failed anyway" if fid is not None else (
497
+ "its frame then failed anyway")
498
+ return Disposition(
499
+ "ambiguous",
500
+ f"ambiguous -- {_absorbed(trace, h)}{where}, but {tail}",
501
+ "handled, then the frame failed for another reason -- the "
502
+ "cleanup-then-fail blind spot (design R8): a genuine swallow in a "
503
+ "frame that later fails reads ambiguous, not a swallow",
504
+ site=_site(trace, h))
505
+
506
+
507
+ def _left_thread(trace, chain, idx) -> Disposition:
508
+ return Disposition(
509
+ "ambiguous",
510
+ "ambiguous -- it left its thread into a JoinHandle; whether it was "
511
+ "ever read is not recorded",
512
+ "the parent may have unwrapped it, logged it or dropped the handle; "
513
+ "a spawned thread's return value leaves no record of being read")
514
+
515
+
516
+ RULES = {
517
+ "swallowed_candidate": _swallowed,
518
+ "panicked": _panicked,
519
+ "returned_to_harness": _returned_to_harness,
520
+ "propagated": _propagated,
521
+ "ambiguous_escaped": _escaped,
522
+ "merged": _merged,
523
+ "handled_then_failed": _handled_then_failed,
524
+ "left_thread": _left_thread,
525
+ }
526
+
527
+
528
+ def classify(trace, chain, idx) -> Disposition:
529
+ """What the recording supports about one chain -- and nothing more.
530
+
531
+ Everything the table does not decide is AMBIGUOUS, including a terminal
532
+ a newer converter invented. Falling through to a verdict is how a tool
533
+ ends up making an accusation nobody wrote a rule for.
534
+ """
535
+ terminal = chain.terminal
536
+ if terminal is None:
537
+ return Disposition(
538
+ "ambiguous",
539
+ "ambiguous -- the recording records no ending for this chain",
540
+ "chain.terminal rides a chain's last event and this one carries "
541
+ "none, so the converter's machine never closed it")
542
+ rule = RULES.get(terminal)
543
+ if rule is None:
544
+ return Disposition(
545
+ "ambiguous",
546
+ f"ambiguous -- this recording ends the chain with {terminal!r}, "
547
+ "which these rules do not know",
548
+ "a terminal a newer converter wrote and these rules do not "
549
+ "decide reads ambiguous by design, never a swallow")
550
+ return rule(trace, chain, idx)
551
+
552
+
553
+ # -- rendering --------------------------------------------------------------
554
+ def _hops_line(trace, chain) -> str | None:
555
+ """The chain's whole journey on one line, each stop naming the site that
556
+ recorded it. R8: the head prints the ORIGIN's type and each hop its own,
557
+ with a type change labelled `translated` -- so a hop that changed the
558
+ error type carries the new type here and nowhere else.
559
+
560
+ A one-event chain gets no line: it would repeat the head verbatim.
561
+ """
562
+ if len(chain.events) < 2:
563
+ return None
564
+ parts = []
565
+ for e in chain.events:
566
+ part = f"e{e.id} {_at(trace, e)} {_how(e)}"
567
+ if _chain(e).get("translated"):
568
+ exc = (e.payload or {}).get("exc") or {}
569
+ part += f" (translated to {exc.get('type', '?')})"
570
+ parts.append(part)
571
+ return "hops: " + " -> ".join(parts)
572
+
573
+
574
+ def _header(trace, idx) -> None:
575
+ caps.print_incomplete(
576
+ trace, "an Err whose fate was recorded after the cut is not below, "
577
+ "and its absence here is not evidence it had none")
578
+ _print_panics(idx.panics)
579
+ _print_partial(idx.partial)
580
+
581
+
582
+ def _print_panics(panics: int) -> None:
583
+ """An answer of "no exceptions recorded" about a run that panicked is a
584
+ false negative, and a tally with no panic in it reads as one even when
585
+ chains ARE listed. One spelling, shared with invocation mode, which
586
+ prints the SUM over its members."""
587
+ if not panics:
588
+ return
589
+ # `event(s)`, one word, and it repairs a real ambiguity: this counts
590
+ # panic RAISE/HANDLED events and the tally two lines down counts CHAINS
591
+ # -- `panics: 8` beside `panicked 2` was two different questions under
592
+ # one word. The `panics: ` prefix is kept: two acceptance readers key
593
+ # their line on it.
594
+ print(f"panics: {panics} event(s) recorded -- this command judges Err "
595
+ "flow; a panic is a frame's unwind, printed by `tree` and `frame`, "
596
+ "and a failed test that panicked is listed by `failures`")
597
+
598
+
599
+ def _print_partial(rows, wheres=None, hint="sensorium info") -> None:
600
+ """`meta.partial` (design R6): `?` sites the transformer could not
601
+ reach. Printed BEFORE the answer because it qualifies the whole of it --
602
+ an `Err` raised at one of these sites is recorded by nothing, so its
603
+ absence from the list below says nothing about the program.
604
+
605
+ `wheres` is invocation mode's parallel list of where each site was seen
606
+ -- a run id, or `"<k> processes"` for one several members carry. There
607
+ the list is a union across processes, and a row that did not say where
608
+ it came from would name a site the reader cannot go and look at. `None`
609
+ in single-run mode, where the process is the ref the reader already
610
+ typed. `hint` is the continuation for the rows the cap hides, which
611
+ that mode points at the first hidden row's process.
612
+ """
613
+ if not rows:
614
+ return
615
+ noun = "?-site" if len(rows) == 1 else "?-sites"
616
+ print(f"partial: {len(rows)} {noun} the transformer could not reach -- "
617
+ "an Err raised at one is recorded by nothing and appears nowhere "
618
+ "below")
619
+ for i, r in enumerate(rows[:PARTIAL_SHOWN]):
620
+ where = f" in {wheres[i]}" if wheres else ""
621
+ print(f" {r.get('qualname', '?')} {r.get('file', '?')}:"
622
+ f"{r.get('line', '?')} ({r.get('reason', '?')}){where}")
623
+ if len(rows) > PARTIAL_SHOWN:
624
+ print(f" ... {len(rows) - PARTIAL_SHOWN} more ({hint})")
625
+
626
+
627
+ def run(trace, args, after: int) -> int:
628
+ """`exceptions` on a Rust trace. `exceptions_cmd.run` has already
629
+ validated `--limit`, resolved `--after` to the event id `after`, and
630
+ opened the trace; the capability gate is the first thing that happens
631
+ here, before any rule reads an event."""
632
+ refusal = caps.require(trace, "err_flow", "exceptions")
633
+ if refusal:
634
+ # The command is spelled correctly and the trace is readable: the
635
+ # recorder declares it wrote no err-flow record, so the reader's
636
+ # next move is a recording made by one that does.
637
+ print(f"REFUSED: {refusal}")
638
+ return UNSETTLED
639
+ idx = Index(trace)
640
+ _header(trace, idx)
641
+ if not idx.chains:
642
+ # `caps.none_status`: "none" only where the recording is whole. An
643
+ # empty answer on a run that stopped mid-flight reports where the
644
+ # RECORDING ended, not what the program did.
645
+ note = (" (see TRUNCATED above)"
646
+ if trace.meta.get("trace_truncated") else "")
647
+ print(f"no exceptions recorded{note}")
648
+ return caps.none_status(trace)
649
+
650
+ scope = [c for c in idx.chains if c.origin.id > after]
651
+ skipped = len(idx.chains) - len(scope)
652
+ if skipped:
653
+ print(f"raised ({len(scope)} of {len(idx.chains)}; {skipped} earlier "
654
+ f"chain(s) skipped by --after e{after}):")
655
+ else:
656
+ print(f"raised ({len(scope)}):")
657
+
658
+ # One block per SHAPE, not per chain (design N3): `--after` has already
659
+ # chosen the CHAINS in scope, and the groups form over exactly those.
660
+ #
661
+ # Local: `exceptions_group` imports `_at` and `_hops_line` from this
662
+ # module, so a module-level import here would be a cycle.
663
+ from sensorium.query.exceptions_group import group_chains, print_shapes
664
+ shapes, tally = group_chains(trace, scope, idx, classify)
665
+ shown = print_shapes(trace, shapes, args.limit)
666
+ # Counted over every chain in scope, not just the printed ones and not
667
+ # per shape: the tally never shrinks because a page was clipped, and it
668
+ # stays comparable line-for-line with every record already written (N5).
669
+ print("dispositions: " + ", ".join(f"{t} {tally[t]}" for t in TAG_ORDER
670
+ if tally.get(t)))
671
+ # Paging RAISES THE LIMIT rather than naming an event to resume after:
672
+ # `--after` cuts chains, and a cursor that cut a group in half would
673
+ # re-show it as a partial block still labelled with the whole count.
674
+ # The reader's OWN `--after` is carried through (ruling R-G7): dropping
675
+ # it made the continuation answer over a wider scope than the question
676
+ # asked, which is a hint that lies about what it will show.
677
+ scoped = f"--after e{after} " if after else ""
678
+ note = more_note(len(shapes), shown,
679
+ f"sensorium exceptions {shlex.quote(args.run)} "
680
+ f"{scoped}--limit {len(shapes)}")
681
+ if note:
682
+ print(note)
683
+ return ANSWERED