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,327 @@
1
+ """What `refocus` SAYS: the stamp it writes, and the report it prints.
2
+
3
+ Split out of `refocus_cmd` at that file's 800-line ceiling, along the seam
4
+ the material has: nothing here decides anything. Every fact these four
5
+ functions print or stamp was settled by `assess`, which stays with the
6
+ verdict; `res` is read only for the VALUES `assess` has already ruled
7
+ apply. That is the whole reason the split is safe -- the terminal line,
8
+ the stamped label and the exit code still come from one reading, and this
9
+ file is where that one reading is put into words.
10
+ """
11
+ from pathlib import Path
12
+
13
+ from sensorium.exit import ANSWERED, NEGATIVE, UNSETTLED
14
+ from sensorium.query.diff_cmd import print_comparison, task_drill_lines
15
+ from sensorium.query.refocus_world import harness_note, uncompared_threads
16
+ from sensorium.query.vocab import print_blind_spots, terms
17
+ from sensorium.store import db
18
+ from sensorium.store.reader import Trace
19
+
20
+
21
+ def _stamp(path: Path, res: dict, a: dict) -> None:
22
+ """Label the new trace with its verdict AND its licence, permanently.
23
+
24
+ The licence is stamped for the same reason the verdict is: a listing
25
+ that shows a bare `verdict:MATCH` for a run whose licence was withheld
26
+ on every count is the "reads as a pedigree" failure one level down.
27
+ """
28
+ conn = db.open_trace(path)
29
+ try:
30
+ db.set_meta(conn, "refocus_verdict", a["verdict"])
31
+ # `thread_stream_parted` is False when the divergence is not a step
32
+ # of the compared thread's stream at all (the tasks parted and that
33
+ # stream did not). Writing the index anyway would persist "diverged
34
+ # at step None" as if it were a position, and the task description
35
+ # below is the real one. `res` is read only for the VALUES; whether
36
+ # they apply is `assess`'s answer, so the label and the printed line
37
+ # cannot come from two different readings.
38
+ if a["thread_stream_parted"]:
39
+ db.set_meta(conn, "refocus_diverge_index", res["index"])
40
+ db.set_meta(conn, "refocus_diverge_a", res["a_desc"])
41
+ db.set_meta(conn, "refocus_diverge_b", res["b_desc"])
42
+ elif a["verdict"] == "REFUSED":
43
+ db.set_meta(conn, "refocus_refused_reasons", res["reasons"])
44
+ if a["threads"]:
45
+ db.set_meta(conn, "refocus_thread_divergence", a["threads"])
46
+ if a["task_divergence"]:
47
+ db.set_meta(conn, "refocus_diverge_tasks", a["task_divergence"])
48
+ if a["licence"]:
49
+ db.set_meta(conn, "refocus_licence", a["licence"])
50
+ db.set_meta(conn, "refocus_licence_reasons", a["caveats"])
51
+ db.set_meta(conn, "refocus_licence_verified", a["verified"])
52
+ conn.commit()
53
+ finally:
54
+ conn.close()
55
+
56
+
57
+ def _print_thread_line(orig: Trace, new: Trace, a: dict) -> None:
58
+ """The `threads:` line, in the four shapes it comes in."""
59
+ if a["threads"]:
60
+ print(f"threads: DIVERGED -- {a['threads']}")
61
+ elif a["thread_stream_parted"]:
62
+ # Keyed on whether the compared STREAM parted, not on the verdict: a
63
+ # DIVERGED with no index is a divergence of the tasks, and the
64
+ # compared thread stream matched. Saying it "already diverged" there
65
+ # would be false, and would hide that every thread row did match.
66
+ print("threads: not compared -- the compared thread already diverged")
67
+ elif new.fingerprints():
68
+ # NOT "all N threads matched". That sentence asserted completeness
69
+ # this tool cannot have: a thread whose body is entirely stdlib
70
+ # leaves no fingerprint, so it is not among the N and was never
71
+ # compared. Say how many were compared, and say plainly when more
72
+ # existed than that.
73
+ n = len(new.fingerprints())
74
+ # `uncompared_threads` and not `threads_started + 1 - n`: that was
75
+ # arithmetic across two populations. This converter writes one
76
+ # thread row and puts every other thread in `task_fingerprints`, so
77
+ # the old sum reported EVERY non-main Rust thread as one that "ran
78
+ # no traced code" -- including the thread the code under test runs
79
+ # on, whose call shape had just been compared. None from either
80
+ # side means the count cannot be established, and then the clause
81
+ # is absent rather than derived from a key that was never written.
82
+ counts = [uncompared_threads(t) for t in (orig, new)]
83
+ unseen = None if None in counts else max(counts)
84
+ tail = (f"; {unseen} further thread(s) ran no traced code, left no "
85
+ "fingerprint, and were NOT compared" if unseen else "")
86
+ print(f"threads: {n} recorded fingerprint(s) compared"
87
+ f"{a['thread_scope']}, all matching{tail}{harness_note(new)}")
88
+ else:
89
+ print("threads: no per-thread fingerprints were recorded on either "
90
+ "side -- there was nothing to compare beyond the stream above")
91
+
92
+
93
+ def _diverged_why(a: dict) -> str:
94
+ """What this DIVERGED is attributed to, in the report's own words."""
95
+ if a["threads"]:
96
+ return "a thread other than the compared one took a different path"
97
+ if a["thread_stream_parted"]:
98
+ return "the compared thread took a different path"
99
+ if a["task_divergence"]:
100
+ # "took a different path" presumes both sides ran one. When a side
101
+ # ran no task stream at all there is no path to have differed, and
102
+ # naming which side is the whole finding.
103
+ t = a["tasks"] or {}
104
+ if t.get("n_a") == 0:
105
+ return "the rerun ran a task stream the original did not"
106
+ if t.get("n_b") == 0:
107
+ return "the original ran a task stream the rerun did not"
108
+ return "a task took a different path"
109
+ # Unreachable through `compare()`, which reports DIVERGED with no index
110
+ # only when the tasks parted. Stated rather than assumed, for the same
111
+ # reason `final_verdict` never downgrades a DIVERGED: if the two modules
112
+ # ever disagree, the honest line is the one that does not name a culprit
113
+ # it has not found.
114
+ return ("the comparison reported a divergence this report could not "
115
+ "attribute to a thread or a task")
116
+
117
+
118
+ def _match_line(new: Trace, a: dict) -> str:
119
+ """The MATCH headline. One sentence, shared with the compact report so
120
+ the two wordings cannot drift apart about what was compared."""
121
+ if a["thread_scope"]:
122
+ return ("refocus verdict: MATCH -- every recorded thread produced "
123
+ "the identical CALL/RETURN/RAISE/HANDLED sequence outside "
124
+ f"its {terms(new).stream_scope}, and every task stream "
125
+ "matched by content")
126
+ return ("refocus verdict: MATCH -- every recorded thread produced the "
127
+ "identical CALL/RETURN/RAISE/HANDLED sequence")
128
+
129
+
130
+ def _refused_line(new_name: str, orig_name: str) -> str:
131
+ return (f"refocus verdict: REFUSED -- {new_name} was recorded and is "
132
+ f"queryable, but it could NOT be verified against "
133
+ f"{orig_name}: treat it as a separate, UNVERIFIED execution")
134
+
135
+
136
+ def _compact_divergence(res: dict, a: dict) -> str | None:
137
+ """The concrete why, one line: the fingerprint step, the other
138
+ thread, or the task. Not the observer-effect paragraph."""
139
+ if a["thread_stream_parted"] and res.get("index") is not None:
140
+ return (f"at causal step {res['index']}: "
141
+ f"{res['a_desc']} / {res['b_desc']}")
142
+ if a["threads"]:
143
+ return f"threads: DIVERGED -- {a['threads']}"
144
+ if a["task_divergence"]:
145
+ return f"tasks: DIVERGED -- {a['task_divergence']}"
146
+ return None
147
+
148
+
149
+ def _print_compact_licence(orig_name: str, a: dict) -> None:
150
+ """One line. A withheld licence stays visible, with the count and the
151
+ first reason, not the catalogue. A granted one does not list every
152
+ verified fact."""
153
+ caveats = a["caveats"]
154
+ if caveats:
155
+ print(f"licence: WITHHELD -- {len(caveats)} check(s) failed; "
156
+ f"first: {caveats[0]}")
157
+ return
158
+ print(f"licence: verified against {orig_name}")
159
+
160
+
161
+ def _report_compact(_orig: Trace, new: Trace, res: dict, orig_name: str,
162
+ new_name: str, a: dict) -> int:
163
+ """The same decision as `report`, in the lines an answer can use.
164
+
165
+ Verdict, and the concrete finding. No blind-spot catalogue, no
166
+ schedule-permutation note, no observer-effect paragraph, no verified-
167
+ fact list. Nothing here re-decides: `a` and `res` are read the way
168
+ the long report reads them.
169
+ """
170
+ verdict = a["verdict"]
171
+ if verdict == "REFUSED":
172
+ print(_refused_line(new_name, orig_name))
173
+ for reason in res.get("reasons") or []:
174
+ print(f"reason: {reason}")
175
+ return UNSETTLED
176
+ if verdict == "DIVERGED":
177
+ print(f"refocus verdict: DIVERGED -- {_diverged_why(a)}")
178
+ detail = _compact_divergence(res, a)
179
+ if detail:
180
+ print(detail)
181
+ if a["world"]:
182
+ n = len(a["world"])
183
+ more = f" ({n} world difference(s))" if n > 1 else ""
184
+ print(f"world: {a['world'][0]}{more}")
185
+ return NEGATIVE
186
+ print(_match_line(new, a))
187
+ _print_compact_licence(orig_name, a)
188
+ return ANSWERED
189
+
190
+
191
+ def report(orig: Trace, new: Trace, res: dict, orig_name: str, new_name: str,
192
+ a: dict, *, compact: bool = False) -> int:
193
+ """Print the comparison and the verdict; return the exit code.
194
+
195
+ `compact` changes the wording, not the decision. The CLI defaults it
196
+ off so the long report stays what it was; the MCP tool passes it
197
+ unless the caller says false.
198
+ """
199
+ if compact:
200
+ return _report_compact(orig, new, res, orig_name, new_name, a)
201
+ # `tasks=False`: the task finding is printed below, in the words that
202
+ # are also stamped into the trace, with the drill-in commands beside
203
+ # them. Letting `diff` print its own version too gave this output two
204
+ # `tasks:` lines that said different amounts about one finding.
205
+ print_comparison(orig, new, res, orig_name, new_name, tasks=False)
206
+ # `res` belongs to `print_comparison` above and to nothing else here:
207
+ # every fact this function decides on comes from `assess`.
208
+ verdict, threads = a["verdict"], a["threads"]
209
+ task_divergence, tasks = a["task_divergence"], a["tasks"] or {}
210
+
211
+ if verdict == "REFUSED":
212
+ print("threads: not compared -- no verdict was issued")
213
+ print(_refused_line(new_name, orig_name))
214
+ # Stated here too: "on every verdict" has to include the verdict
215
+ # that says nothing, or the sentence is not true.
216
+ print_blind_spots(new)
217
+ # The second gate (X4). The program DID re-run -- the new trace
218
+ # exists and is queryable -- and what failed is the verification
219
+ # against the original. No edit to this command changes that; a
220
+ # recording the comparison can stand on does, which is what 3
221
+ # means. The pre-rerun refusals in `_refuse` keep 2.
222
+ return UNSETTLED
223
+
224
+ _print_thread_line(orig, new, a)
225
+
226
+ if task_divergence:
227
+ # The only `tasks:` line in this output, and the same sentence
228
+ # `_stamp` writes -- so what the terminal says and what `info`
229
+ # replays afterwards cannot drift apart.
230
+ print(f"tasks: DIVERGED -- {task_divergence}")
231
+ for line in task_drill_lines(tasks.get("pair"), orig_name, new_name):
232
+ print(line)
233
+ elif tasks.get("verdict") == "MATCH":
234
+ print(f"tasks: {tasks['n_b']} task stream(s) compared by content, "
235
+ "all matching; the ordering between tasks is not compared")
236
+
237
+ if verdict == "DIVERGED":
238
+ why = _diverged_why(a)
239
+ print(f"refocus verdict: DIVERGED -- {why}. {new_name} is a "
240
+ f"DIFFERENT execution than {orig_name}; it is still queryable, "
241
+ f"every `sensorium info {new_name}` says so, and nothing it "
242
+ f"shows is a fact about {orig_name}")
243
+ # Only the WORLD findings, never the trace-derived ones: differing
244
+ # output and a differing exit status are consequences of a
245
+ # divergence, and offering a consequence as a possible cause would
246
+ # send the reader looking in the wrong direction.
247
+ if a["world"]:
248
+ print("differences in the world between the two runs, any of "
249
+ "which may be why:")
250
+ for caveat in a["world"]:
251
+ print(f" - {caveat}")
252
+ print("note: a divergence can also be caused by the deeper capture "
253
+ "itself -- capturing values runs the program's own __repr__ "
254
+ "and slows the run down; the fingerprint cannot tell that "
255
+ "apart from the program genuinely taking another path")
256
+ print_blind_spots(new)
257
+ return NEGATIVE
258
+
259
+ # The headline may claim only what was compared. Under the per-task
260
+ # basis the thread rows cover what ran OUTSIDE every task, so for a run
261
+ # with tasks the unqualified sentence is false in the most misleading
262
+ # direction available: the raw per-thread sequence of an order-flipped
263
+ # rerun genuinely differs, and it is the SPLIT -- each thread outside
264
+ # its tasks, plus the task multiset -- that matched.
265
+ print(_match_line(new, a))
266
+ # The hazard E4" section 5.3 MEASURED, named where the verdict is read.
267
+ # On 1 of its 61 pairs the per-task assignment moved between the two
268
+ # runs -- the workers carried (216, 205, 151, 233, 151) events on one
269
+ # side and (216, 205, 233, 151, 151) on the other, 956 both sides --
270
+ # while the multiset of (name, hash) was identical, so the comparator
271
+ # reported MATCH. That is the comparator working exactly as designed,
272
+ # and it is also a claim this verdict does not make: "every recorded
273
+ # thread produced the identical sequence" reads as a statement about
274
+ # the run's schedule, and no printed line said otherwise.
275
+ #
276
+ # Only where more than one stream was compared, and EACH POPULATION is
277
+ # asked separately. The hazard is a permutation WITHIN one of them --
278
+ # the same shapes arriving on differently numbered members of the same
279
+ # multiset -- so one thread stream beside one task stream is not it:
280
+ # there is a single member on each side and nothing to permute. Summing
281
+ # the two reached 2 on exactly that pair and printed the note where the
282
+ # sentence above says it must not, which is arithmetic across two
283
+ # populations reported as a measurement: this project's own bug class,
284
+ # on the line that exists to bound a claim.
285
+ #
286
+ # With one member there is nothing for a schedule to have assigned
287
+ # differently, and a caveat that cannot apply is noise on every
288
+ # single-threaded pair -- the same rule that took libtest's thread out
289
+ # of the untraced-thread clause.
290
+ #
291
+ # And the NOUN is the population that fired, for the same reason the
292
+ # gate asks them separately. `stream_scope` is the task word ("asyncio
293
+ # tasks" on Python), so a two-thread, zero-task pair printed a caveat
294
+ # about tasks that pair did not have: true of the mechanism, false of
295
+ # the run in front of the reader, and unfalsifiable by anything they
296
+ # could look at. A Rust trace carries exactly one `fingerprints` row --
297
+ # the main thread's, every other thread being a task row
298
+ # (`convert/frames.rs`) -- so `threads` is unreachable there and the
299
+ # Rust sentence is the one it always was.
300
+ threads_permutable = len(new.fingerprints()) > 1
301
+ tasks_permutable = (tasks.get("n_b") or 0) > 1
302
+ if threads_permutable or tasks_permutable:
303
+ scope = terms(new).stream_scope
304
+ if threads_permutable and tasks_permutable:
305
+ carried = f"threads and {scope}"
306
+ elif threads_permutable:
307
+ carried = "threads"
308
+ else:
309
+ carried = scope
310
+ print("note: a MATCH does not say the two runs scheduled the same "
311
+ "way -- the streams are compared as a multiset of (name, "
312
+ "hash), so the same shapes carried by differently numbered "
313
+ f"{carried} match, and which carried which is "
314
+ "recorded and never compared")
315
+ if a["caveats"]:
316
+ print("licence: WITHHELD -- this MATCH is about call shape, and "
317
+ "these checks say it is not a statement about the run as a "
318
+ "whole:")
319
+ for caveat in a["caveats"]:
320
+ print(f" - {caveat}")
321
+ else:
322
+ print(f"licence: verified against {orig_name} on exactly these "
323
+ "points, and no others:")
324
+ for fact in a["verified"]:
325
+ print(f" - {fact}")
326
+ print_blind_spots(new)
327
+ return ANSWERED