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,394 @@
1
+ r"""JavaScript `util.inspect` text: read one way, written one way, one table.
2
+
3
+ The sibling of `rust_debug`, and for the same reason. A `dbg` capture is
4
+ what a probe got out of the language's own formatter -- TEXT, and the only
5
+ thing a recorder can get for a value it will not decompose. Two commands
6
+ have to make sense of that text and they must not disagree: `watch --expr`
7
+ READS it (`read_inspect`, the value the text spells) and `flow --value`
8
+ WRITES it (`inspect_text`, the rendering a literal would have). An escape
9
+ undone in one and re-applied differently in the other reports a sighting
10
+ that the predicate at the same site then denies, so both live here, over one
11
+ table.
12
+
13
+ WHAT IS PINNED, AND HOW IT WAS ESTABLISHED
14
+ ------------------------------------------
15
+ By GENERATION, not by reading JavaScript's specification and hoping. Every
16
+ spelling below came out of `dbg()` -- the one function every capture this
17
+ recorder puts on the wire goes through -- under node v24.16.0 with the
18
+ recorder's own inspect options, and is committed as
19
+ `typescript/test/fixtures/inspect-table.json`
20
+ (`typescript/test/fixtures/gen-inspect-table.mjs` regenerates it).
21
+ `tests/test_js_inspect.py` holds this module to that file row by row. Four
22
+ of the rows would have been guessed wrong:
23
+
24
+ 5.0 -> "5" (JavaScript has one number type; Rust's
25
+ Debug prints `2.0` for 2.0 -- A12's
26
+ opposite, and deliberate)
27
+ 1e21 -> "1e+21" (`1e-7` keeps its sign and drops the pad;
28
+ `0.000001` is written out in full)
29
+ -0 -> "-0" (`String(-0)` is "0"; inspect is not String)
30
+ "a\vb" -> "'a\\x0Bb'" (node names \n \t \r \b \f and NOTHING else;
31
+ every other control character, DEL and the
32
+ C1 block are \xHH in UPPERCASE hex, while
33
+ U+2028, U+00A0 and the rest are printable
34
+ to node and are not escaped at all)
35
+ "it's \"x\" ${y}" (a backtick would quote it, but a template
36
+ -> "'it\\'s \"x\" ${y}'" HOLE rules the backtick out)
37
+
38
+ THE TWO DIRECTIONS ARE INVERSES ON THE LITERAL DOMAIN
39
+ -----------------------------------------------------
40
+ Design amendment A11, applied to the second dialect: `read_inspect` parses
41
+ exactly what `inspect_text` can spell, so `resolve(dbg(inspect_text(L))) ==
42
+ L` for every literal `L` a command accepts. The domain is integers BELOW
43
+ 2**53, floats in every spelling `Number::toString` produces, `true`/`false`,
44
+ `null`, and quoted strings up to the recorder's 100-character string cap.
45
+
46
+ The bound on integers is JavaScript's own and not a shortfall here. From
47
+ 2**53 up there is no distinct number to round-trip TO: `2**60` and
48
+ `2**60 + 1` are one double, which prints `1152921504606847000`, so a search
49
+ for either sights every capture of that double and reads back as the value
50
+ JavaScript actually held. What is written is the double; what is read back
51
+ is the double; the integer typed at the command line is the only thing that
52
+ can differ from it, and it differed from it inside the program too.
53
+
54
+ TWO THINGS NEITHER DIRECTION DOES
55
+ ---------------------------------
56
+ Guess, and compare a prefix. `read_inspect` hands back the text itself
57
+ whenever the text spells no literal (an object, a function, a `Map`,
58
+ a `Date`), because the text is what the trace holds; `inspect_text` returns
59
+ None for a target that has no JavaScript spelling, and a capture then
60
+ matches nothing rather than matching approximately.
61
+
62
+ A string past inspect's own `maxStringLength` is the prefix case, and it is
63
+ the one place this dialect cannot read truncation off the capture's `trunc`
64
+ flag: inspect cut the STRING long before the 200-byte wire cap looked at
65
+ the rendering, so `trunc` is false and the only evidence is the
66
+ `... N more characters` tail inspect appends outside the closing quote.
67
+ Reading that tail as TRUNCATED, and refusing to spell one (plan P7), is
68
+ what keeps a prefix from being compared as a value.
69
+ """
70
+ import math
71
+ import re
72
+ from decimal import Decimal
73
+
74
+ from sensorium.query.expr import TRUNCATED, UNDEFINED, _DbgText
75
+
76
+ #: Inspect's own string cap, from the recorder's options (`src/dbg.mjs`).
77
+ #: A longer string is cut by inspect before the wire cap is applied.
78
+ MAX_STRING = 100
79
+
80
+ #: Where an integer stops being its own shortest spelling. Below 2**53 every
81
+ #: integer is exactly a double and its digits ARE the shortest text that
82
+ #: reads back as that double, so writing them out is what JavaScript prints.
83
+ #: At or above it the two part company -- `2**60` is exactly representable
84
+ #: and JavaScript still prints `1152921504606847000`, because the doubles
85
+ #: there are 256 apart and the shortest text that lands on this one has
86
+ #: three fewer significant digits than the value does. Measured (ruling
87
+ #: R34): `String(2**60)` is `1152921504606847000`, not `...846976`, and
88
+ #: `String(123456789012345680000)` keeps the `680000` tail that the exact
89
+ #: expansion `...683968` loses.
90
+ EXACT_INT = 2 ** 53
91
+
92
+ # The three floats JavaScript spells as words rather than digits, and the
93
+ # one zero that carries a sign into its rendering.
94
+ _WORD_FLOATS = {"NaN": float("nan"), "Infinity": math.inf,
95
+ "-Infinity": -math.inf}
96
+ # A BigInt, an integer, and a float -- a decimal POINT, an EXPONENT, or
97
+ # both. The BigInt is tried first (its `n` would otherwise be text), then
98
+ # the integer, so `5` is an int and never a float.
99
+ _BIGINT = re.compile(r"-?\d+n")
100
+ _INT = re.compile(r"-?\d+")
101
+ _FLOAT = re.compile(r"-?\d+(\.\d+)?[eE][-+]?\d+|-?\d+\.\d+")
102
+ #: What inspect appends OUTSIDE the closing quote when it cut the string.
103
+ #: Public as the ONE definition of that tail: `_body` reads it to tell a cut
104
+ #: string from a whole one, `is_clipped` answers off it, and the TypeScript
105
+ #: converter counts blind spot 36 through `is_clipped` rather than spelling a
106
+ #: second regex of its own in `ts/build.py`.
107
+ INSPECT_MORE = re.compile(r"\.\.\. \d+ more characters?\Z")
108
+ #: The three quotes inspect chooses between, in the order it chooses them.
109
+ QUOTES = "'\"`"
110
+
111
+ # Read wider than written, on purpose. `\v` and `\0` never appear in a text
112
+ # this recorder wrote (node spells them `\x0B` and `\x00`), and they are
113
+ # read anyway: undoing an escape the writer did not have to make is
114
+ # harmless, refusing one is not -- the rule `rust_debug` states for `\'`.
115
+ _UNESCAPE = {"n": "\n", "t": "\t", "r": "\r", "b": "\b", "f": "\f",
116
+ "v": "\v", "0": "\0", "\\": "\\", "'": "'", '"': '"', "`": "`"}
117
+ # The five node NAMES. Everything else unprintable is `\xHH`; see `_escape`.
118
+ _ESCAPE = {"\\": "\\\\", "\n": "\\n", "\t": "\\t", "\r": "\\r",
119
+ "\b": "\\b", "\f": "\\f"}
120
+ _HEX = "0123456789abcdefABCDEF"
121
+ #: Sentinel: the text is a quoted string whose rendering inspect cut.
122
+ _CLIPPED = object()
123
+
124
+
125
+ def js_number(x) -> str:
126
+ """How JavaScript spells this number: ECMAScript's `Number::toString`.
127
+
128
+ Ported rather than approximated, because `repr` disagrees with it in
129
+ five places a reader would meet on the first run: `2.0` (JavaScript has
130
+ one number type and prints `2`), `1e+20` (JavaScript writes the digits
131
+ out to 1e21), `1e-05` (no pad, and written out down to 1e-6), `-0.0`,
132
+ and every integer from 2**53 up (`2**60` prints `1152921504606847000`,
133
+ the shortest digits that read back as that double, not the exact
134
+ `1152921504606846976`).
135
+
136
+ The argument is a JavaScript NUMBER: a float, or an int small enough to
137
+ be one exactly. `inspect_text` converts anything larger to the double
138
+ JavaScript would hold before calling here, because `repr` of a Python
139
+ int is its exact expansion and exact is the wrong answer up there.
140
+
141
+ Handed a raw `int` >= 2**53 anyway, this returns its EXACT digits --
142
+ `js_number(2**60)` is `1152921504606846976`, where the same value as a
143
+ float is `1152921504606847000` -- because the integer shortcut below
144
+ reads `int` before the shortest-round-trip placement can. No caller
145
+ does that; the conversion is `inspect_text`'s job and it does it. The
146
+ behaviour is named here so a second caller knows it must convert too.
147
+ """
148
+ if x != x:
149
+ return "NaN"
150
+ if x == math.inf:
151
+ return "Infinity"
152
+ if x == -math.inf:
153
+ return "-Infinity"
154
+ if x == 0:
155
+ # `-0` is a rendering, not a value: `String(-0)` is "0" and
156
+ # `util.inspect(-0)` is `-0`, and what a capture holds is the
157
+ # inspect text.
158
+ return "-0" if math.copysign(1.0, x) < 0 else "0"
159
+ sign = "-" if x < 0 else ""
160
+ m = abs(x)
161
+ if (isinstance(m, int) or m.is_integer()) and m < EXACT_INT:
162
+ # Below 2**53 the exact expansion IS the shortest round-trip, so
163
+ # this is a shortcut and not a second answer. Above it the value
164
+ # takes the placement below, where the digits come from `repr` --
165
+ # `inspect_text` hands such an int here as the FLOAT JavaScript
166
+ # holds it as, because `repr` of a Python int is exact and exact is
167
+ # the wrong answer there (ruling R34).
168
+ return sign + str(int(m))
169
+ # The shortest digits that read back as this number, and where the point
170
+ # goes among them -- the spec's `n` (the point's position) and `k` (how
171
+ # many digits there are). `repr` is Python's shortest round-trip, which
172
+ # is JavaScript's too. `normalize` strips the trailing zero `repr` puts
173
+ # on an integral float (`9007199254740992.0`), which the spec's `s` may
174
+ # not carry: with it, `k` would exceed `n` and an integer would be
175
+ # placed as `9007199254740992.0`.
176
+ t = Decimal(repr(m)).normalize().as_tuple()
177
+ digits = "".join(str(d) for d in t.digits)
178
+ k = len(digits)
179
+ n = t.exponent + k
180
+ if k <= n <= 21:
181
+ # ECMAScript's first placement: an integral value written out, with
182
+ # the zeros the shortest digits do not carry. This is the path every
183
+ # integral value from 2**53 up to 1e21 takes -- `1152921504606847`
184
+ # + `000` -- and the reason the shortcut above stops where it does.
185
+ body = digits + "0" * (n - k)
186
+ elif 0 < n <= 21:
187
+ body = digits[:n] + "." + digits[n:]
188
+ elif -6 < n <= 0:
189
+ body = "0." + "0" * -n + digits
190
+ else:
191
+ e = n - 1
192
+ body = (digits[0] + ("." + digits[1:] if k > 1 else "")
193
+ + "e" + ("+" if e >= 0 else "-") + str(abs(e)))
194
+ return sign + body
195
+
196
+
197
+ def _escape(ch: str, quote: str) -> str:
198
+ """One character as inspect writes it inside `quote`.
199
+
200
+ NOT `str.isprintable()`, which is what the Rust dialect uses: node
201
+ escapes the C0 controls, DEL and the C1 block and nothing else, so
202
+ U+2028, U+00A0 and U+200B -- all unprintable to Python -- are written
203
+ literally. Measured; a `\\u2028` here would spell a text this recorder
204
+ never writes.
205
+ """
206
+ if ch == quote:
207
+ return "\\" + ch
208
+ esc = _ESCAPE.get(ch)
209
+ if esc is not None:
210
+ return esc
211
+ o = ord(ch)
212
+ if o < 0x20 or 0x7F <= o <= 0x9F:
213
+ return f"\\x{o:02X}"
214
+ return ch
215
+
216
+
217
+ def quote_js(s: str) -> str:
218
+ """A string as inspect quotes it: single, else double where the text
219
+ holds a single quote, else backticks where it holds both -- and single
220
+ with `\\'` escaped where no quote is free.
221
+
222
+ A template HOLE rules the backtick out as surely as a backtick does:
223
+ measured, `it\'s "x" ${y}` comes back single-quoted, because a backtick
224
+ around it would read as an interpolation rather than as text. A lone `$`
225
+ is not a hole and does not.
226
+ """
227
+ if "'" not in s:
228
+ quote = "'"
229
+ elif '"' not in s:
230
+ quote = '"'
231
+ elif "`" not in s and "${" not in s:
232
+ quote = "`"
233
+ else:
234
+ quote = "'"
235
+ return quote + "".join(_escape(ch, quote) for ch in s) + quote
236
+
237
+
238
+ def inspect_text(target) -> str | None:
239
+ """How `util.inspect` would spell this literal, or None if it would not.
240
+
241
+ None is the honest answer for anything with no JavaScript spelling (an
242
+ `ObjTarget`, an over-long string): a capture then matches it nowhere,
243
+ rather than matching something adjacent.
244
+ """
245
+ if target is None:
246
+ return "null"
247
+ if isinstance(target, bool): # before int: a bool IS an int
248
+ return "true" if target else "false"
249
+ if isinstance(target, int):
250
+ if abs(target) < EXACT_INT:
251
+ return str(target)
252
+ # JavaScript has one number type and it is a double: an integer
253
+ # this large is HELD as the nearest double and printed as that
254
+ # double's shortest digits, so writing the exact expansion here
255
+ # would spell a text no recorder ever wrote (ruling R34). Past the
256
+ # double's own range there is no number left to print, and
257
+ # JavaScript says so with a word.
258
+ try:
259
+ return js_number(float(target))
260
+ except OverflowError:
261
+ return "-Infinity" if target < 0 else "Infinity"
262
+ if isinstance(target, float):
263
+ return js_number(target)
264
+ if isinstance(target, str):
265
+ if len(target) > MAX_STRING:
266
+ # What the recorder wrote for such a string is a PREFIX with a
267
+ # tail, and a prefix equals nothing (plan P7). Spelling the tail
268
+ # here would report a sighting of characters never recorded.
269
+ return None
270
+ return quote_js(target)
271
+ return None
272
+
273
+
274
+ def _body(text: str):
275
+ """What is inside inspect's quotes: the body, `_CLIPPED` where inspect
276
+ cut the string, or None where this text is not a quoted string.
277
+
278
+ The closing quote is what tells a cut string from a string whose
279
+ CONTENT ends `... 50 more characters`: inspect appends its tail after
280
+ the quote, so the second one ends with a quote and the first does not.
281
+ """
282
+ m = INSPECT_MORE.search(text)
283
+ head = text[:m.start()] if m else text
284
+ if not (len(head) >= 2 and head[0] == head[-1] and head[0] in QUOTES):
285
+ return None
286
+ return _CLIPPED if m else head[1:-1]
287
+
288
+
289
+ def is_clipped(text: str) -> bool:
290
+ """Whether this capture's text is a string `util.inspect` CUT.
291
+
292
+ The tail rule the TypeScript converter counts blind spot 36 by. A string
293
+ past inspect's own 100-character cap is cut by the FORMATTER, long
294
+ before the 200-byte wire cap looks at the rendering, so the capture's
295
+ `trunc` flag is `false` and this text is the only witness there is.
296
+
297
+ The closing quote is what decides it, which is why this is a function
298
+ and not a bare `INSPECT_MORE.search`: inspect appends its tail AFTER the
299
+ quote, so a string whose own CONTENT ends `... 50 more characters` still
300
+ ends with a quote and was kept whole, and a text that spells something
301
+ other than a string is not a cut string however it ends.
302
+ """
303
+ return _body(text) is _CLIPPED
304
+
305
+
306
+ def read_inspect(text: str):
307
+ """The value an inspect text spells: int, float, bool, None, the
308
+ UNDEFINED marker, str, TRUNCATED, or the text itself.
309
+
310
+ The caller has already dealt with the WIRE truncation -- a rendering
311
+ clipped at 200 bytes is not a rendering. Inspect's own string cut is
312
+ this function's to notice, because nothing else can see it.
313
+ """
314
+ if text == "null":
315
+ return None
316
+ if text == "undefined":
317
+ # JavaScript's second absence, and not Python's: a name bound to
318
+ # `undefined` is bound, which `x == null` must not answer yes for.
319
+ return UNDEFINED
320
+ if text in ("true", "false"):
321
+ return text == "true"
322
+ if text in _WORD_FLOATS:
323
+ return _WORD_FLOATS[text]
324
+ if text == "-0":
325
+ # Before the integer rule, which would read it as the int 0 and
326
+ # lose the sign the rendering carries.
327
+ return -0.0
328
+ if _BIGINT.fullmatch(text):
329
+ # A BigInt is an arbitrary-precision integer, and Python's int is
330
+ # the same thing: `x == 123` answers at a site that holds `123n`.
331
+ return int(text[:-1])
332
+ if _INT.fullmatch(text):
333
+ return int(text)
334
+ if _FLOAT.fullmatch(text):
335
+ return float(text)
336
+ body = _body(text)
337
+ if body is _CLIPPED:
338
+ return TRUNCATED
339
+ if body is not None:
340
+ return unescape_inspect(body)
341
+ return _DbgText(text)
342
+
343
+
344
+ def unescape_inspect(inner: str) -> str:
345
+ r"""The characters an inspect string's body stands for.
346
+
347
+ Hand-written rather than `codecs.decode(.., "unicode_escape")`, which
348
+ decodes latin-1 and so turns every non-ASCII character node printed
349
+ literally into mojibake -- `'café'` would come back as `café` and
350
+ compare unequal to the string the program held.
351
+
352
+ An escape this table does not know is left EXACTLY as it was read: a
353
+ reader comparing against text sees the same characters the trace holds,
354
+ rather than a silent reinterpretation of them.
355
+ """
356
+ out: list[str] = []
357
+ i, n = 0, len(inner)
358
+ while i < n:
359
+ ch = inner[i]
360
+ if ch != "\\" or i + 1 >= n:
361
+ out.append(ch)
362
+ i += 1
363
+ continue
364
+ nxt = inner[i + 1]
365
+ if nxt in _UNESCAPE:
366
+ out.append(_UNESCAPE[nxt])
367
+ i += 2
368
+ continue
369
+ if nxt == "x":
370
+ digits = inner[i + 2:i + 4]
371
+ if len(digits) == 2 and all(c in _HEX for c in digits):
372
+ out.append(chr(int(digits, 16)))
373
+ i += 4
374
+ continue
375
+ elif nxt == "u" and inner[i + 2:i + 3] == "{":
376
+ end = inner.find("}", i + 3)
377
+ digits = inner[i + 3:end] if end != -1 else ""
378
+ if digits and all(c in _HEX for c in digits):
379
+ try:
380
+ out.append(chr(int(digits, 16)))
381
+ except ValueError:
382
+ pass # beyond U+10FFFF: leave it read
383
+ else:
384
+ i = end + 1
385
+ continue
386
+ elif nxt == "u":
387
+ digits = inner[i + 2:i + 6]
388
+ if len(digits) == 4 and all(c in _HEX for c in digits):
389
+ out.append(chr(int(digits, 16)))
390
+ i += 6
391
+ continue
392
+ out.append(ch)
393
+ i += 1
394
+ return "".join(out)
@@ -0,0 +1,254 @@
1
+ """Query-time rename detection for `diff --ignore-moves`.
2
+
3
+ A behaviour-preserving refactor that moves a function to another file
4
+ changes the `file` of every one of its events, and the causal stream is
5
+ compared on (file, qualname, kind), so the plain verdict is DIVERGED at the
6
+ first moved CALL (observed 2026-09-01 on bloomery's Python-trio split: the
7
+ verification fell back to comparing `info` counts by eye).
8
+
9
+ This module pairs code objects that LEFT one file on side A with the
10
+ same-named code objects that APPEARED in another file on side B -- and
11
+ only when that pairing is the only one possible. A qualname that is A-only
12
+ under two files, or B-only under two files, is not paired: it is listed as
13
+ unpaired and its events keep their recorded keys, so any divergence inside
14
+ it is still a divergence. Nothing here changes what is stored; the stored
15
+ fingerprints are untouched and `diff` without the flag reads them as before.
16
+
17
+ A file's own `<module>` code object is never paired: it is file identity,
18
+ not a function, and a split creates new files whose import-time frame exists
19
+ on one side BY CONSTRUCTION. Those frames are listed in `one_sided_modules`
20
+ and dropped from both compared streams -- the module body's OWN steps and
21
+ nothing else, which includes a RAISE or HANDLED that ran directly in it.
22
+ What module-level code CALLS is still compared, so an import-time side
23
+ effect that reaches a function still diverges.
24
+ """
25
+ from collections import defaultdict
26
+ from dataclasses import dataclass, replace
27
+
28
+ from sensorium.record.fingerprint import Fingerprint
29
+
30
+ Key = tuple[str, str] # (file, qualname)
31
+
32
+ MODULE = "<module>" # the qualname CPython gives module-level code
33
+
34
+
35
+ @dataclass(frozen=True)
36
+ class Moves:
37
+ mapping: dict[Key, Key] # A key -> B key, unique pairs only
38
+ moved: list[tuple[str, str, str]] # (qualname, file_a, file_b)
39
+ added: list[Key] # B-only, not paired
40
+ removed: list[Key] # A-only, not paired
41
+ unpaired: list[str] # qualnames refused for ambiguity
42
+ one_sided_modules: list[tuple[str, str]] # ("A"|"B", file), <module> only
43
+
44
+
45
+ def detect_moves(trace_a, trace_b) -> Moves:
46
+ """Pair A-only (file, qualname) keys with B-only ones by qualname, and
47
+ only where that pairing is unique on BOTH sides. Everything refused --
48
+ for ambiguity, or for having no counterpart at all -- is reported
49
+ rather than dropped, because an unreported refusal reads as a MATCH."""
50
+ ka = {(c.file, c.qualname) for c in trace_a.codes()}
51
+ kb = {(c.file, c.qualname) for c in trace_b.codes()}
52
+ only_a, only_b = ka - kb, kb - ka
53
+ one_sided_modules = sorted(
54
+ [("A", f) for f, q in only_a if q == MODULE]
55
+ + [("B", f) for f, q in only_b if q == MODULE])
56
+ by_q_a: dict[str, list[str]] = defaultdict(list)
57
+ by_q_b: dict[str, list[str]] = defaultdict(list)
58
+ for f, q in only_a:
59
+ if q != MODULE:
60
+ by_q_a[q].append(f)
61
+ for f, q in only_b:
62
+ if q != MODULE:
63
+ by_q_b[q].append(f)
64
+ mapping: dict[Key, Key] = {}
65
+ moved, unpaired = [], []
66
+ for q in sorted(by_q_a):
67
+ if q not in by_q_b:
68
+ continue
69
+ fa, fb = by_q_a[q], by_q_b[q]
70
+ if len(fa) == 1 and len(fb) == 1:
71
+ mapping[(fa[0], q)] = (fb[0], q)
72
+ moved.append((q, fa[0], fb[0]))
73
+ else:
74
+ # Two files could each be the destination (or the origin), and
75
+ # picking one would hide a divergence inside the other.
76
+ unpaired.append(q)
77
+ paired_b = set(mapping.values())
78
+ removed = sorted(k for k in only_a if k not in mapping and k[1] != MODULE)
79
+ added = sorted(k for k in only_b if k not in paired_b and k[1] != MODULE)
80
+ return Moves(mapping, moved, added, removed, unpaired, one_sided_modules)
81
+
82
+
83
+ def project(stream, moves: Moves) -> list[tuple]:
84
+ """Drop the `<module>` steps of files that exist on one side only, then
85
+ rewrite each remaining (file, qualname, kind, eid) step through
86
+ `moves.mapping`; unmapped steps pass through unchanged.
87
+
88
+ "Dropped" is every step whose code object IS that `<module>` -- its CALL
89
+ and RETURN, and a RAISE or HANDLED that ran directly in the module body.
90
+ Its own steps are not compared; what it called is.
91
+
92
+ The B side is projected too, through a `Moves` whose mapping is empty:
93
+ the dropping is symmetric (a one-sided file's frames must leave BOTH
94
+ streams), the rewriting is not (it names A's keys with B's files)."""
95
+ dropped = {f for _side, f in moves.one_sided_modules}
96
+ if not moves.mapping and not dropped:
97
+ return list(stream)
98
+ out = []
99
+ for file, qual, kind, eid in stream:
100
+ if qual == MODULE and file in dropped:
101
+ continue
102
+ file, qual = moves.mapping.get((file, qual), (file, qual))
103
+ out.append((file, qual, kind, eid))
104
+ return out
105
+
106
+
107
+ def for_b(moves: Moves | None) -> Moves | None:
108
+ """The same `Moves` as seen from the B side: one-sided module frames
109
+ still dropped, nothing rewritten. `mapping` names A's keys with B's
110
+ files, so applying it to B would rewrite keys that already ARE B's."""
111
+ return None if moves is None else replace(moves, mapping={})
112
+
113
+
114
+ def hash_stream(stream) -> str:
115
+ """The same rolling hash the recorder uses, over a query-time stream.
116
+ Both sides of a `--ignore-moves` comparison are hashed here, never one
117
+ side here and the other from the stored row: the recorder hashes a
118
+ root-relative file, this hashes what `code_objects` holds."""
119
+ fp = Fingerprint()
120
+ for file, qual, kind, _eid in stream:
121
+ fp.update(file, qual, kind)
122
+ return fp.hexdigest()
123
+
124
+
125
+ MOVE_LIST_CAP = 12
126
+
127
+
128
+ def _base(file: str) -> str:
129
+ """The file's basename: this section lists files by name, and the
130
+ absolute path is already on the header and divergence lines."""
131
+ return file.rsplit("/", 1)[-1]
132
+
133
+
134
+ def short(key) -> str:
135
+ file, qual = key
136
+ return f"{_base(file)}:{qual}"
137
+
138
+
139
+ def desc(step, moves: Moves | None = None) -> str:
140
+ """One causal step rendered for a reader: `e12 CALL f (/w/a.py)`.
141
+
142
+ `moves` is passed on the A SIDE ONLY, and it undoes the projection for
143
+ the printed line. `project()` rewrites A's key to B's file so the two
144
+ streams can be compared; rendering that projected tuple printed a file
145
+ A never recorded -- the 2026-09-02 acceptance run said `A: e454 CALL
146
+ StampAuditTests (.../test_recompute_v2_verdicts.py)` for a step A
147
+ recorded in `test_recompute_v2.py`, at the one line the reader is told
148
+ to drill into. The recorded file is what the drill-in command opens, so
149
+ it is what the line names, and the file it was paired with is appended
150
+ rather than dropped: the pairing is why the two steps are compared at
151
+ all. Nothing here changes what was compared -- the comparison ran on
152
+ the projected keys, and this only renames them back for print.
153
+
154
+ The lookup is exact: `mapping`'s values are keys present on B and
155
+ absent from A, so an A-side step carrying one can only have got it from
156
+ the projection, and each qualname contributes at most one pair.
157
+ """
158
+ file, qual, kind, eid = step
159
+ paired = ""
160
+ if moves is not None and moves.mapping:
161
+ src = {v: k for k, v in moves.mapping.items()}.get((file, qual))
162
+ if src is not None:
163
+ paired = f" (paired with {_base(file)})"
164
+ file = src[0]
165
+ return f"e{eid} {kind:<7} {qual} ({file}){paired}"
166
+
167
+
168
+ def modulo_location(moves: Moves | None) -> bool:
169
+ """Whether a move-aware verdict was reached through any leniency at all.
170
+
171
+ With nothing paired and no one-sided module frame the projected streams
172
+ ARE the recorded ones, and "MATCH modulo location ... once 0 moved code
173
+ object(s) are paired" describes a licence never exercised -- on two
174
+ identical traces it read as a hedge over an exact agreement."""
175
+ return bool(moves and (moves.moved or moves.one_sided_modules))
176
+
177
+
178
+ def _listed(items, render=str) -> str:
179
+ """`items` rendered, capped, and MARKED when the cap cut something. A
180
+ truncated list with nothing to say it was truncated reads as the whole
181
+ list -- the silent under-report this block exists to prevent."""
182
+ shown = ", ".join(render(i) for i in items[:MOVE_LIST_CAP])
183
+ over = len(items) - MOVE_LIST_CAP
184
+ return f"{shown}, ... +{over} more" if over > 0 else shown
185
+
186
+
187
+ def print_key_line(moves: Moves | None) -> None:
188
+ """The key a move-aware verdict was reached through, printed under the
189
+ headers so the verdict below is never read as a comparison of the keys
190
+ AS RECORDED. Pairing is by qualname alone -- `kind` is part of the
191
+ comparison key, not of the criterion. No-op when not move-aware."""
192
+ if not moves:
193
+ return
194
+ print(f"key: (file, qualname, kind), with {len(moves.moved)} code "
195
+ "object(s) paired across a move by qualname -- see moves below")
196
+
197
+
198
+ def print_moves_section(moves: Moves | None) -> None:
199
+ """The `moves:` block under a verdict; no-op when there is none, so
200
+ every print path can call it unconditionally. A bare `moves:` header
201
+ with nothing under it -- what two identical traces produced -- reads as
202
+ a list that was cut off, so the empty case says it is empty."""
203
+ if not moves:
204
+ return
205
+ if not (moves.moved or moves.added or moves.removed or moves.unpaired
206
+ or moves.one_sided_modules):
207
+ print("moves: none -- no code object was on one side only")
208
+ return
209
+ print("moves:")
210
+ print_moves(moves)
211
+
212
+
213
+ def print_moves(moves: Moves) -> None:
214
+ """What was paired, what was not, and why -- printed on every verdict
215
+ under --ignore-moves, so a MATCH never hides how it was reached."""
216
+ for qual, fa, fb in moves.moved[:MOVE_LIST_CAP]:
217
+ print(f" moved: {qual} {_base(fa)} -> {_base(fb)}")
218
+ if len(moves.moved) > MOVE_LIST_CAP:
219
+ print(f" ... +{len(moves.moved) - MOVE_LIST_CAP} more moved")
220
+ if moves.removed:
221
+ print(" removed (only in A): " + _listed(moves.removed, short))
222
+ if moves.added:
223
+ print(" added (only in B): " + _listed(moves.added, short))
224
+ if moves.unpaired:
225
+ print(" unpaired (same name in several files on one side, not "
226
+ "paired; a divergence inside them is reported as one): "
227
+ + _listed(moves.unpaired))
228
+ if moves.one_sided_modules:
229
+ only_a = [_base(f) for s, f in moves.one_sided_modules if s == "A"]
230
+ only_b = [_base(f) for s, f in moves.one_sided_modules if s == "B"]
231
+ print(f" module frames not compared: "
232
+ f"{len(moves.one_sided_modules)} (files only in B: "
233
+ f"{', '.join(only_b) or '-'}; only in A: "
234
+ f"{', '.join(only_a) or '-'}) -- a new file's own import-time "
235
+ "frame exists on one side by construction; its own steps are "
236
+ "not compared; what it called is")
237
+
238
+
239
+ def task_hashes(trace,
240
+ moves: Moves | None) -> dict[int, tuple[str | None, str]]:
241
+ """{task_id: (name, hash)} on the basis the comparison counts on: the
242
+ STORED hash when comparing as recorded, a query-time hash over the
243
+ projected stream under `--ignore-moves`.
244
+
245
+ The two bases are not interchangeable -- the recorder hashed a
246
+ root-relative file, this hashes what `code_objects` holds -- so a task
247
+ looked up by a hash from the other basis is simply not found. Every
248
+ site that turns a hash back into a task id therefore reads it from
249
+ here, with the same `moves` the shapes were counted with."""
250
+ fps = trace.task_fingerprints()
251
+ if moves is None:
252
+ return {t: (n, h) for t, (n, h, _c) in fps.items()}
253
+ return {t: (n, hash_stream(project(trace.task_stream(t), moves)))
254
+ for t, (n, _h, _c) in fps.items()}