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,748 @@
1
+ """Compare two runs' causal streams and pinpoint the first divergence.
2
+
3
+ Causal stream = (file, qualname, kind) per CAUSAL_KINDS event (CALL / RETURN
4
+ / RAISE / HANDLED) on one thread. Values, timing, and LINE events are
5
+ excluded by construction (see fingerprint.py), so a MATCH means the same
6
+ *shape* of execution -- the same sequence of calls, returns, raises and
7
+ handles -- not that the two runs are "the same" in every sense. It says
8
+ nothing about argument values, return values, wall-clock timing, per-line
9
+ state, or any thread other than the one compared.
10
+
11
+ WHICH THREAD "THE ONE COMPARED" ACTUALLY IS
12
+ --------------------------------------------
13
+ `Trace.main_thread_id()` prefers a value the recorder writes at boot time
14
+ (`meta["main_thread_ident"]`); traces recorded before that key existed fall
15
+ back to "the thread of whichever event got id 1", a heuristic that a
16
+ worker thread starting before the main thread's own first *traced* event
17
+ (under `--focus`/`--window` filtering, or ordinary scheduling jitter) can
18
+ silently defeat. `Trace.main_thread_basis()` says which case a trace is in
19
+ -- `"recorded"` or `"inferred"` -- and `diff` reads it: the header names the
20
+ actual thread id compared and its basis, a MATCH's own verdict line only
21
+ says "the main thread" when both sides are `"recorded"`, and an inferred
22
+ side gets an explicit note rather than a silent guess dressed as a fact.
23
+
24
+ REFUSAL, NOT A HEDGE
25
+ --------------------
26
+ A run whose recording died mid-flight (killed process, failed `install()`)
27
+ has a causal stream that may simply STOP -- not because the program took a
28
+ different path, but because nothing after that point was ever recorded.
29
+ Comparing against it with the ordinary algorithm would report DIVERGED at
30
+ the truncation point: a confident, false claim that the two programs took
31
+ different paths, when the truth is "this trace has nothing to say past
32
+ here." `meta["incomplete"]` marks exactly this.
33
+
34
+ `meta["late_writes"]` is a related, quieter hazard: it counts writes that
35
+ arrived after the database sealed and is a LOWER BOUND (a live thread that
36
+ never got to flush its tail is not counted at all). A non-zero value means
37
+ events are missing from the stream -- possibly causal ones -- so a verdict
38
+ against that trace is unsafe for the same reason.
39
+
40
+ A THIRD WAY TO HAVE NOTHING TO SAY
41
+ -----------------------------------
42
+ Two EMPTY causal streams are also equal, and the ordinary algorithm reports
43
+ MATCH for them with exactly the confidence it reports MATCH for a thousand
44
+ matching events. That is reachable without any damage to the recording at
45
+ all: a target that resolves outside the run's root (reached through `..`, or
46
+ an installed console script), or `--include`/`--exclude` that match nothing,
47
+ records a complete, healthy trace of zero traced events. A verdict over
48
+ nothing is not a verdict, so it is refused too. One empty side is a
49
+ different matter -- that is a real difference between the two runs, and
50
+ stays DIVERGED.
51
+
52
+ TASKS ARE NOT THREADS, AND THEIR ORDER IS NOT CONTENT
53
+ -----------------------------------------------------
54
+ Under the per-task fingerprint basis a thread's causal stream is the events
55
+ that ran in NO task, and every asyncio task has a stream of its own. The
56
+ two are compared differently on purpose. A thread stream is compared step
57
+ by step, because the order of events on one thread is the program's own
58
+ doing. Task streams are compared as a MULTISET of (name, hash): the event
59
+ loop decides when each task gets to run, so which task ran first is a
60
+ scheduling fact, not a fact about the program -- comparing the interleaving
61
+ would manufacture a DIVERGED out of two runs that did exactly the same work.
62
+
63
+ A name is content here, not a label: `task-A` matches `task-A`, and a task
64
+ with no name of its own only ever matches another unnamed one. `asyncio`
65
+ names every task it is not given a name for `Task-<N>` from a process-global
66
+ counter, so that "name" IS creation order -- it is read as no name at all
67
+ (Ruling 4), and `--task` refuses it rather than pretend it identifies
68
+ anything.
69
+
70
+ Two traces recorded under different bases are refused outright when either
71
+ ran a task: one side's thread stream contains the task events and the
72
+ other's does not, so the two streams are not the same kind of thing and a
73
+ verdict comparing them would be about the definition, not the program.
74
+
75
+ `compare()` therefore has three possible verdicts, not two: MATCH, DIVERGED,
76
+ and REFUSED. REFUSED means "no verdict could be issued" -- it is the honest
77
+ alternative to guessing. This is deliberately load-bearing for `refocus`,
78
+ which reuses `compare()` unchanged: a refocus built on an incomplete, lossy,
79
+ or empty recording must refuse exactly the same way, so the check lives here
80
+ once rather than being re-implemented (and possibly forgotten) at each call
81
+ site.
82
+ """
83
+ import re
84
+ from collections import Counter
85
+
86
+ from sensorium import paths
87
+ from sensorium.exit import ANSWERED, NEGATIVE, UNSETTLED
88
+ from sensorium.query.caps import print_truncated
89
+ from sensorium.query.help import RUN_A_HELP, RUN_B_HELP
90
+ from sensorium.query.moves import (Moves, desc, detect_moves, for_b,
91
+ modulo_location, print_key_line,
92
+ print_moves_section, project, task_hashes)
93
+ from sensorium.query.vocab import PYTHON, terms
94
+ from sensorium.store.reader import Trace
95
+ # The honesty-note layer, split out at this file's 800-line ceiling.
96
+ # Re-exported so `diff_cmd.<name>` keeps resolving: these are one command's
97
+ # internals across its files, not separate modules with surfaces of their
98
+ # own.
99
+ from sensorium.query.diff_notes import ( # noqa: F401 (re-exported)
100
+ _argv_note, _thread_header, _thread_notes, safety_notes)
101
+
102
+ CAUSAL = ("CALL", "RETURN", "RAISE", "HANDLED")
103
+
104
+
105
+ def first_divergence(a: list, b: list) -> int | None:
106
+ """Index of the first element where `a` and `b` differ on (file,
107
+ qualname, kind) -- the leading three slots of each causal-stream tuple;
108
+ a trailing event id is ignored if present. `None` means one is a prefix
109
+ of the other and both prefixes are equal in length (i.e. truly
110
+ identical); otherwise, if lengths differ with no earlier mismatch, the
111
+ index returned is the length of the shorter one (where it ran out)."""
112
+ for i, (x, y) in enumerate(zip(a, b)):
113
+ if x[:3] != y[:3]:
114
+ return i
115
+ if len(a) != len(b):
116
+ return min(len(a), len(b))
117
+ return None
118
+
119
+
120
+ def _unsafe_reasons(trace: Trace, label: str) -> list[str]:
121
+ """Why `trace` (labelled A or B) must not be handed a MATCH/DIVERGED
122
+ verdict. Empty means the trace's causal stream is safe to trust."""
123
+ m = trace.meta
124
+ reasons = []
125
+ if m.get("incomplete"):
126
+ reasons.append(
127
+ f"{label} is INCOMPLETE: recording ended without a finalize "
128
+ "pass (process killed mid-record, or install() failed) -- its "
129
+ "causal stream can stop at any point with no signal that it "
130
+ "did, so a MATCH or DIVERGED verdict against it would be a "
131
+ "confident false claim, not an approximation")
132
+ late = trace.dropped_writes()
133
+ if late:
134
+ reasons.append(
135
+ f"{label} dropped >={late} trace write(s) after its database "
136
+ "sealed (late_writes is a LOWER BOUND -- a thread that never "
137
+ "got to flush its tail is not counted at all): events, "
138
+ "possibly causal ones, are missing from its stream, so a "
139
+ "verdict against it is unsafe for the same reason as an "
140
+ "incomplete trace")
141
+ return reasons
142
+
143
+
144
+ def _refused(reasons: list[str]) -> dict:
145
+ return {"verdict": "REFUSED", "index": None, "a_event": None,
146
+ "b_event": None, "a_desc": None, "b_desc": None,
147
+ "reasons": reasons, "a_stream": None, "b_stream": None,
148
+ "tasks": None, "moves": None}
149
+
150
+
151
+ _DEFAULT_NAME = re.compile(r"^Task-\d+\Z")
152
+
153
+
154
+ def _unnamed(name: str | None, words=PYTHON) -> bool:
155
+ """Whether `name` identifies a unit of work or merely numbers it.
156
+
157
+ `asyncio` names every task it is not given a name for `Task-<N>` from a
158
+ process-global counter, so such a name encodes creation order and
159
+ nothing else -- exactly what this comparison must not compare, since
160
+ `gather(*coros)` and one-task-per-request servers create tasks in
161
+ data-dependent order (Ruling 4).
162
+
163
+ A language that mints no such names (`Terms.default_name_note is None`)
164
+ has no numbering to read a name AS: a Rust test called `Task-1` would be
165
+ a name its program chose, and dropping it would erase content this
166
+ comparison exists to compare. `words` defaults to the Python table so
167
+ every existing caller and test reads exactly as before."""
168
+ if name is None:
169
+ return True
170
+ return (words.default_name_note is not None
171
+ and _DEFAULT_NAME.match(name) is not None)
172
+
173
+
174
+ def _shapes(trace: Trace, moves: Moves | None = None) -> Counter:
175
+ """`Trace.task_shapes()` with asyncio's default `Task-N` names read as
176
+ no name. The reader owns the multiset; this owns the one thing that is
177
+ a comparison policy and not a fact about the trace, so the raw name
178
+ stays in the table and in `info` -- it is dropped for the comparison,
179
+ not everywhere.
180
+
181
+ With `moves` (a Moves object, its mapping empty for the B side) the
182
+ shapes are RE-HASHED from each task's stream, projected through it:
183
+ `--ignore-moves` must hash both sides one way, and the stored rows were
184
+ hashed over a root-relative file."""
185
+ out: Counter = Counter()
186
+ words = terms(trace)
187
+ if moves is None:
188
+ for (name, h), k in trace.task_shapes().items():
189
+ out[(None if _unnamed(name, words) else name, h)] += k
190
+ return out
191
+ for name, h in task_hashes(trace, moves).values():
192
+ out[(None if _unnamed(name, words) else name, h)] += 1
193
+ return out
194
+
195
+
196
+ def _shape_difference(a: Counter, b: Counter):
197
+ """(only_a, only_b): the (name, hash, count) entries one multiset has
198
+ and the other lacks. Unnamed tasks carry name None and therefore only
199
+ ever match unnamed tasks -- a name is content here, not a label."""
200
+ def rows(c):
201
+ return sorted(((n, h, k) for (n, h), k in c.items()),
202
+ key=lambda r: (r[0] is None, r[0] or "", r[1]))
203
+ return rows(a - b), rows(b - a)
204
+
205
+
206
+ def _basis_reasons(trace_a: Trace, trace_b: Trace) -> list[str]:
207
+ """Two traces recorded under different fingerprint bases define their
208
+ thread streams differently; if either ran a task the comparison would
209
+ put task events on one side only. No task anywhere: the definitions
210
+ coincide and nothing is refused."""
211
+ ba, bb = trace_a.fingerprint_basis, trace_b.fingerprint_basis
212
+ if ba == bb or not (trace_a.tasks() or trace_b.tasks()):
213
+ return []
214
+ return ["the two traces were recorded under different fingerprint "
215
+ f"bases (A: {ba}, B: {bb}): the per-thread side's thread stream "
216
+ "includes its task events, which this version compares "
217
+ "separately, so the two are not the same kind of stream -- "
218
+ "re-record the older side with this version to compare them"]
219
+
220
+
221
+ def _task_row_reasons(trace: Trace, label: str) -> list[str]:
222
+ """Why a trace that RAN tasks but recorded none of their fingerprints
223
+ cannot be compared at all.
224
+
225
+ It is not the same thing as a trace with no tasks. The per-task basis is
226
+ a meta marker, so `causal_stream()` narrows this trace's thread stream
227
+ to the events that ran in no task whether or not the task rows made it
228
+ to disk -- and with no task fingerprints to compare, everything those
229
+ tasks did drops out of the comparison silently. What is left is the
230
+ module scaffolding, and a MATCH on it reads as a verdict on the run.
231
+
232
+ Traces in exactly this state exist: until this arc the writer's
233
+ `INSERT ... SELECT` over an unflushed `tasks` table wrote zero rows for
234
+ every recording made through the CLI. A cleanly finished recording no
235
+ longer produces the state -- every minted task serial gets its
236
+ fingerprint when it is minted (Ruling 9) and the rows are written in one
237
+ transaction at uninstall -- but an unclean death still can: a run killed
238
+ after its first batch flush has `tasks` rows and no `task_fingerprints`
239
+ rows (beside `incomplete`), and a callback still in flight at uninstall
240
+ can mint a serial after the snapshot. So the check stays for two
241
+ reasons: files already on disk, and recordings that did not finish.
242
+ """
243
+ tasks = trace.tasks()
244
+ if (trace.fingerprint_basis != "per-task" or not tasks
245
+ or trace.task_fingerprints()):
246
+ return []
247
+ return [f"{label} ran {len(tasks)} {terms(trace).task_noun_plural} but "
248
+ "recorded no task "
249
+ "fingerprints (its per-thread stream excludes their events), so "
250
+ "the tasks cannot be compared and the thread stream alone would "
251
+ "say less than it seems -- re-record it with this version"]
252
+
253
+
254
+ def _pair(trace_a, trace_b, ta, tb, name, by_order=False,
255
+ moves=None) -> dict | None:
256
+ """Two task streams and their first differing step; `None` when they do
257
+ not actually differ (same shape, different serial numbering) -- there is
258
+ nothing to show, and showing a step anyway would invent a difference.
259
+
260
+ Projected under `--ignore-moves` like every other compared stream: the
261
+ raw streams part at the first moved CALL, and reporting THAT as the
262
+ task's first difference would point at the move the flag exists to
263
+ look past."""
264
+ sa, sb = trace_a.task_stream(ta), trace_b.task_stream(tb)
265
+ if moves:
266
+ sa, sb = project(sa, moves), project(sb, for_b(moves))
267
+ i = first_divergence(sa, sb)
268
+ if i is None:
269
+ return None
270
+ a_step = sa[i] if i < len(sa) else None
271
+ b_step = sb[i] if i < len(sb) else None
272
+ return {"name": name, "index": i, "a_task": ta, "b_task": tb,
273
+ "by_order": by_order,
274
+ "a_event": a_step[3] if a_step else None,
275
+ "b_event": b_step[3] if b_step else None,
276
+ "a_desc": desc(a_step, moves) if a_step else "(stream ended)",
277
+ "b_desc": desc(b_step) if b_step else "(stream ended)"}
278
+
279
+
280
+ def _first_pair_sharing_a_name(trace_a, trace_b, only_a, only_b,
281
+ moves=None) -> dict | None:
282
+ """For the first name present on both 'only' lists, the two task streams
283
+ and their first differing step -- None when no name is shared (then
284
+ every unmatched stream is simply listed)."""
285
+ names_b = {n for n, _h, _k in only_b if n is not None}
286
+ for name, ha, _k in only_a:
287
+ if name is None or name not in names_b:
288
+ continue
289
+ hb = next(h for n, h, _c in only_b if n == name)
290
+ ta = next(t for t, (n, h) in task_hashes(trace_a, moves).items()
291
+ if n == name and h == ha)
292
+ tb = next(t for t, (n, h) in task_hashes(trace_b, for_b(moves)).items()
293
+ if n == name and h == hb)
294
+ pair = _pair(trace_a, trace_b, ta, tb, name, moves=moves)
295
+ if pair is not None:
296
+ return pair
297
+ return None
298
+
299
+
300
+ def _lowest_unmatched_unnamed(trace: Trace, rows, moves=None) -> int | None:
301
+ """The unnamed task with the lowest serial whose shape went unmatched.
302
+ Which of several same-shaped tasks is "the" unmatched one is not
303
+ knowable -- this picks by creation order, and every caller says so."""
304
+ wanted = {h for n, h, _k in rows if n is None}
305
+ return min((t for t, (n, h) in task_hashes(trace, moves).items()
306
+ if _unnamed(n) and h in wanted), default=None)
307
+
308
+
309
+ def _first_unnamed_pair(trace_a, trace_b, only_a, only_b,
310
+ moves=None) -> dict | None:
311
+ """Ruling 4c: when the unmatched streams carry no name on either side
312
+ there is nothing to match them on, so the drill-in pairs the first
313
+ unmatched unnamed stream on each side by ascending task serial. That is
314
+ a guide to look at, not a claim that the two are the same task, and the
315
+ printed line says exactly that."""
316
+ ta = _lowest_unmatched_unnamed(trace_a, only_a, moves)
317
+ tb = _lowest_unmatched_unnamed(trace_b, only_b, for_b(moves))
318
+ if ta is None or tb is None:
319
+ return None
320
+ return _pair(trace_a, trace_b, ta, tb, None, by_order=True, moves=moves)
321
+
322
+
323
+ def compare_tasks(trace_a: Trace, trace_b: Trace,
324
+ moves: Moves | None = None) -> dict:
325
+ """Tasks compared as a multiset of (name, hash): order-independent, so a
326
+ different interleaving cannot manufacture a DIVERGED, and two tasks
327
+ sharing a name are matched by content. verdict None = no task on either
328
+ side (nothing to say)."""
329
+ a, b = (_shapes(trace_a, moves),
330
+ _shapes(trace_b, for_b(moves))) # Ruling 4 normalisation
331
+ n_a, n_b = a.total(), b.total()
332
+ if not n_a and not n_b:
333
+ return {"verdict": None, "only_a": [], "only_b": [], "pair": None,
334
+ "n_a": 0, "n_b": 0}
335
+ only_a, only_b = _shape_difference(a, b)
336
+ if not only_a and not only_b:
337
+ return {"verdict": "MATCH", "only_a": [], "only_b": [], "pair": None,
338
+ "n_a": n_a, "n_b": n_b}
339
+ pair = (_first_pair_sharing_a_name(trace_a, trace_b, only_a, only_b,
340
+ moves)
341
+ or _first_unnamed_pair(trace_a, trace_b, only_a, only_b, moves))
342
+ return {"verdict": "DIVERGED", "only_a": only_a, "only_b": only_b,
343
+ "pair": pair, "n_a": n_a, "n_b": n_b}
344
+
345
+
346
+ def compare(trace_a: Trace, trace_b: Trace,
347
+ moves: Moves | None = None) -> dict:
348
+ """Compare the main-thread causal streams of two traces.
349
+
350
+ Returns a dict with `verdict` in {"MATCH", "DIVERGED", "REFUSED"}.
351
+
352
+ MATCH / DIVERGED also carry `index`, `a_event`, `b_event`, `a_desc`,
353
+ `b_desc` (all `None` on MATCH; `index` is the divergence position and
354
+ the rest describe the two sides' next step on DIVERGED), plus the full
355
+ `a_stream` / `b_stream` used, for callers that want more context.
356
+
357
+ `tasks` carries `compare_tasks()`'s own result (`None` when REFUSED, and
358
+ a `verdict` of `None` inside it when neither side ran a task). A pair
359
+ can diverge on the tasks alone: the verdict is then DIVERGED with
360
+ `index` -- and `a_event`/`b_event`/`a_desc`/`b_desc` -- left `None`,
361
+ because the divergence is not a step of the thread stream those keys
362
+ describe. A caller reading `index` to locate a divergence must handle
363
+ that `None` rather than assume DIVERGED means "on this stream".
364
+
365
+ REFUSED means no verdict could be issued, and comes in two shapes that
366
+ share one contract (`reasons` says which, everything else is `None`):
367
+ the streams could not be TRUSTED, so they were never read; or they were
368
+ read and held nothing to compare. Both are the honest alternative to a
369
+ confident answer -- the second one because two empty streams are equal,
370
+ and calling that MATCH is a verdict about nothing.
371
+ """
372
+ reasons = (_unsafe_reasons(trace_a, "A") + _unsafe_reasons(trace_b, "B")
373
+ + _basis_reasons(trace_a, trace_b)
374
+ + _task_row_reasons(trace_a, "A")
375
+ + _task_row_reasons(trace_b, "B"))
376
+ if reasons:
377
+ return _refused(reasons)
378
+ sa = (project(trace_a.causal_stream(), moves) if moves
379
+ else trace_a.causal_stream())
380
+ sb = (project(trace_b.causal_stream(), for_b(moves)) if moves
381
+ else trace_b.causal_stream())
382
+ tasks = compare_tasks(trace_a, trace_b, moves)
383
+ if not sa and not sb and tasks["verdict"] is None:
384
+ # Two empty streams are equal, and `first_divergence` would duly
385
+ # report MATCH -- a verdict about nothing, delivered with the same
386
+ # confidence as a verdict about a thousand events. One empty side is
387
+ # different: that is a real, reportable difference between the runs,
388
+ # and stays DIVERGED.
389
+ return _refused([
390
+ "neither trace recorded a single causal event on the compared "
391
+ "thread, so there was nothing to compare. A MATCH here would be "
392
+ "a verdict about nothing. This usually means the target's code "
393
+ "was never traced at all: it resolves outside the run's root "
394
+ "(a target reached through `..`, or an installed console "
395
+ "script), or --include/--exclude filtered everything out"])
396
+ i = first_divergence(sa, sb)
397
+ if i is None:
398
+ # The thread streams are identical. That is not the whole run: a
399
+ # task that took another path is a divergence of this pair, and
400
+ # `index` stays None because it is not a step of THIS stream.
401
+ return {"verdict": ("DIVERGED" if tasks["verdict"] == "DIVERGED"
402
+ else "MATCH"),
403
+ "index": None, "a_event": None,
404
+ "b_event": None, "a_desc": None, "b_desc": None,
405
+ "reasons": [], "a_stream": sa, "b_stream": sb,
406
+ "tasks": tasks, "moves": moves}
407
+ a_step = sa[i] if i < len(sa) else None
408
+ b_step = sb[i] if i < len(sb) else None
409
+ return {
410
+ "verdict": "DIVERGED",
411
+ "index": i,
412
+ "a_event": a_step[3] if a_step else None,
413
+ "b_event": b_step[3] if b_step else None,
414
+ "a_desc": desc(a_step, moves) if a_step else "(stream ended)",
415
+ "b_desc": desc(b_step) if b_step else "(stream ended)",
416
+ "reasons": [],
417
+ "a_stream": sa, "b_stream": sb,
418
+ "tasks": tasks, "moves": moves,
419
+ }
420
+
421
+
422
+ def _task_choices(trace: Trace) -> str:
423
+ """What `--task` could have been given on this side."""
424
+ fps = trace.task_fingerprints()
425
+ words = terms(trace)
426
+ named = sorted({n for n, _h, _c in fps.values()
427
+ if not _unnamed(n, words)})
428
+ numbered = sum(1 for n, _h, _c in fps.values() if _unnamed(n, words))
429
+ have = ", ".join(named) if named else "no task with a name of its own"
430
+ if numbered:
431
+ have += f"; plus {numbered} {words.numbered_task_note}"
432
+ return have
433
+
434
+
435
+ def _task_named(trace: Trace, label: str, name: str):
436
+ """(task_id, []) for the one task called `name`, or (None, [why not])."""
437
+ fps = trace.task_fingerprints()
438
+ hits = sorted(t for t, (n, _h, _c) in fps.items() if n == name)
439
+ if len(hits) == 1:
440
+ return hits[0], []
441
+ if len(hits) > 1:
442
+ return None, [f"'{name}' names {len(hits)} tasks on {label}; a name "
443
+ "must pick exactly one task to compare -- picking one "
444
+ "of them would be picking by creation order, which is "
445
+ "what comparing tasks by name exists to avoid"]
446
+ if not fps and trace.fingerprint_basis != "per-task":
447
+ # Not "it has no task stream": a per-thread trace can be full of
448
+ # task-tagged events, and saying otherwise describes the recording
449
+ # as emptier than it is. What is missing is the table this version
450
+ # resolves a NAME through.
451
+ return None, [
452
+ f"{label} recorded {len(trace.tasks())} "
453
+ f"{terms(trace).task_noun_plural} and no "
454
+ "task_fingerprints rows: this version resolves task names "
455
+ "through task_fingerprints, which the recording's version did "
456
+ "not write -- re-record it to compare by name"]
457
+ return None, [f"no task named '{name}' on {label} "
458
+ f"({label} has: {_task_choices(trace)})"]
459
+
460
+
461
+ def compare_task_streams(trace_a: Trace, trace_b: Trace, name: str,
462
+ moves: Moves | None = None) -> dict:
463
+ """`compare()` for one named asyncio task instead of the thread streams.
464
+
465
+ Same keys, plus `a_task` / `b_task` (the task ids compared). The name
466
+ must pick exactly one task on each side: no task by that name, two tasks
467
+ sharing it, or asyncio's own `Task-N` numbering are all REFUSED rather
468
+ than resolved by creation order -- see `_unnamed`.
469
+ """
470
+ unresolved = {"a_task": None, "b_task": None}
471
+ # Read on A's table: the argument is one string compared against both
472
+ # sides, and a language that mints no default names has no note to
473
+ # print -- there the name is looked up like any other.
474
+ note = terms(trace_a).default_name_note
475
+ if note and _DEFAULT_NAME.match(name):
476
+ return {**_refused([note.format(name=name)]), **unresolved}
477
+ # These come first and alone: a trace whose task rows never reached the
478
+ # disk has no task to name, and "no task named 'task-A' on A" would
479
+ # describe the symptom as if it were the program's doing.
480
+ reasons = (_unsafe_reasons(trace_a, "A") + _unsafe_reasons(trace_b, "B")
481
+ + _task_row_reasons(trace_a, "A")
482
+ + _task_row_reasons(trace_b, "B"))
483
+ if reasons:
484
+ return {**_refused(reasons), **unresolved}
485
+ ia, why_a = _task_named(trace_a, "A", name)
486
+ ib, why_b = _task_named(trace_b, "B", name)
487
+ reasons = why_a + why_b
488
+ if reasons:
489
+ return {**_refused(reasons), **unresolved}
490
+ found = {"a_task": ia, "b_task": ib}
491
+ sa, sb = trace_a.task_stream(ia), trace_b.task_stream(ib)
492
+ if moves:
493
+ sa, sb = project(sa, moves), project(sb, for_b(moves))
494
+ if not sa and not sb:
495
+ return {**_refused(
496
+ [f"task '{name}' recorded no causal event on either side, so "
497
+ "there was nothing to compare -- a MATCH here would be a "
498
+ "verdict about nothing"]), **found}
499
+ i = first_divergence(sa, sb)
500
+ if i is None:
501
+ return {"verdict": "MATCH", "index": None, "a_event": None,
502
+ "b_event": None, "a_desc": None, "b_desc": None,
503
+ "reasons": [], "a_stream": sa, "b_stream": sb,
504
+ "tasks": None, "moves": moves, **found}
505
+ a_step = sa[i] if i < len(sa) else None
506
+ b_step = sb[i] if i < len(sb) else None
507
+ return {
508
+ "verdict": "DIVERGED",
509
+ "index": i,
510
+ "a_event": a_step[3] if a_step else None,
511
+ "b_event": b_step[3] if b_step else None,
512
+ "a_desc": desc(a_step, moves) if a_step else "(stream ended)",
513
+ "b_desc": desc(b_step) if b_step else "(stream ended)",
514
+ "reasons": [],
515
+ "a_stream": sa, "b_stream": sb,
516
+ "tasks": None, "moves": moves, **found,
517
+ }
518
+
519
+
520
+ def _print_refusal(res) -> None:
521
+ print("verdict: REFUSED -- cannot issue a MATCH/DIVERGED verdict")
522
+ for reason in res["reasons"]:
523
+ print(f" {reason}")
524
+
525
+
526
+ def _print_divergence(res, name_a, name_b, context) -> None:
527
+ """The first differing step of two streams, with the common run-up and
528
+ the two commands that show it in full."""
529
+ i = res["index"]
530
+ print(f"verdict: DIVERGED at causal step {i}")
531
+ moves = res.get("moves") # A's stream is projected; name A's files
532
+ for step in res["a_stream"][max(0, i - context):i]:
533
+ print(f" common {desc(step, moves)}")
534
+ print(f" A: {res['a_desc']}")
535
+ print(f" B: {res['b_desc']}")
536
+ if res["a_event"]:
537
+ print(f"drill into A: sensorium tree {name_a} "
538
+ f"--around e{res['a_event']}")
539
+ if res["b_event"]:
540
+ print(f"drill into B: sensorium tree {name_b} "
541
+ f"--around e{res['b_event']}")
542
+
543
+
544
+ def _print_thread_match(trace_a, trace_b, res) -> None:
545
+ """The thread streams are identical. Whether that is the run's verdict
546
+ depends on the tasks: a task that took another path is a divergence of
547
+ this pair, and calling the whole thing MATCH would be a verdict on the
548
+ half that happened to agree."""
549
+ n = len(res["a_stream"])
550
+ if res["verdict"] == "DIVERGED":
551
+ print("verdict: " + ("the thread stream held no causal events on "
552
+ "either side" if not n else
553
+ f"MATCH on the thread stream ({n} events)")
554
+ + "; DIVERGED on the tasks (below)")
555
+ return
556
+ if not n:
557
+ # Reachable only because a task ran: two empty streams with no task
558
+ # on either side are refused outright. "Identical causal streams (0
559
+ # events)" would be the verdict about nothing this command refuses
560
+ # everywhere else, dressed as agreement.
561
+ #
562
+ # "modulo location" belongs here too, and was missing: the TASK
563
+ # streams below were compared through the same projection, so a
564
+ # verdict reached because code objects were paired across a move
565
+ # said `MATCH` flat on this branch and `MATCH modulo location` on
566
+ # every other -- one leniency, printed on one branch and silent on
567
+ # the one where the tasks carry the whole verdict.
568
+ lenient = " modulo location" if modulo_location(res.get("moves")) \
569
+ else ""
570
+ print(f"verdict: MATCH{lenient} -- no causal event ran outside a "
571
+ "task on either side, so the thread streams held nothing to "
572
+ "compare; the tasks below carry the whole verdict")
573
+ return
574
+ exact = (trace_a.main_thread_basis() == "recorded"
575
+ and trace_b.main_thread_basis() == "recorded")
576
+ where = "the main thread" if exact else "the thread named above"
577
+ if modulo_location(res.get("moves")):
578
+ nm = len(res["moves"].moved)
579
+ print(f"verdict: MATCH modulo location -- identical causal streams "
580
+ f"({n} events) once {nm} moved code object(s) are paired by "
581
+ f"qualname on {where}; values, timing, and LINE events were "
582
+ "not compared")
583
+ return
584
+ print(f"verdict: MATCH -- identical causal streams ({n} events): "
585
+ "the same sequence of (file, qualname, kind) for "
586
+ f"CALL/RETURN/RAISE/HANDLED on {where}; values, "
587
+ "timing, and LINE events were not compared")
588
+
589
+
590
+ def _fmt_shapes(rows) -> str:
591
+ return ", ".join(f"{n if n is not None else '(unnamed)'} "
592
+ f"{h[:12]}{'' if k == 1 else f' x{k}'}"
593
+ for n, h, k in rows) or "-"
594
+
595
+
596
+ def _print_tasks(res, name_a, name_b) -> None:
597
+ """The task section: what the multiset comparison found, and -- when a
598
+ pair can be picked out -- the first step where the two streams parted."""
599
+ t = res.get("tasks")
600
+ if not t or t["verdict"] is None:
601
+ return
602
+ if t["verdict"] == "MATCH":
603
+ print(f"tasks: {t['n_a']} task stream(s) on each side, compared by "
604
+ "content as (name, hash): all matched; the ordering between "
605
+ "tasks is not compared")
606
+ return
607
+ print(f"tasks: DIVERGED -- {t['n_a']} task stream(s) on A, {t['n_b']} "
608
+ f"on B; only in A: {_fmt_shapes(t['only_a'])}; only in B: "
609
+ f"{_fmt_shapes(t['only_b'])}; the ordering between tasks is not "
610
+ "compared")
611
+ p = t["pair"]
612
+ if not p:
613
+ return
614
+ guide = (" (paired by creation order -- a guide, not a match)"
615
+ if p["by_order"] else "")
616
+ print(f"first difference inside {p['name'] or '(unnamed)'} "
617
+ f"(A task t{p['a_task']}, B task t{p['b_task']}) at causal step "
618
+ f"{p['index']}{guide}:")
619
+ print(f" A: {p['a_desc']}")
620
+ print(f" B: {p['b_desc']}")
621
+ for line in task_drill_lines(p, name_a, name_b):
622
+ print(line)
623
+
624
+
625
+ def task_drill_lines(pair, name_a, name_b) -> list[str]:
626
+ """The `sensorium tree --around` command for each side of a task pair's
627
+ first difference, or [] when there is no pair to drill into.
628
+
629
+ Shared rather than duplicated: `refocus` prints the task finding in its
630
+ own words (the same sentence it stamps into the trace) and still owes
631
+ the reader these two commands.
632
+ """
633
+ if not pair:
634
+ return []
635
+ out = []
636
+ if pair["a_event"]:
637
+ out.append(f"drill into A: sensorium tree {name_a} "
638
+ f"--around e{pair['a_event']}")
639
+ if pair["b_event"]:
640
+ out.append(f"drill into B: sensorium tree {name_b} "
641
+ f"--around e{pair['b_event']}")
642
+ return out
643
+
644
+
645
+ def print_comparison(trace_a, trace_b, res, name_a, name_b, context=3,
646
+ tasks=True) -> None:
647
+ """`diff`'s full comparison. `tasks=False` omits the task section for a
648
+ caller that reports the task finding itself -- `refocus` does, in the
649
+ words it also stamps into the trace, and two `tasks:` lines saying
650
+ different amounts about one finding read as two findings."""
651
+ print(_thread_header("A", name_a, trace_a))
652
+ print(_thread_header("B", name_b, trace_b))
653
+ print_key_line(res.get("moves"))
654
+ for note in safety_notes(trace_a, trace_b):
655
+ print(f"note: {note}")
656
+ if res["verdict"] == "REFUSED":
657
+ _print_refusal(res)
658
+ return
659
+ if res["index"] is None:
660
+ _print_thread_match(trace_a, trace_b, res)
661
+ else:
662
+ _print_divergence(res, name_a, name_b, context)
663
+ if tasks:
664
+ _print_tasks(res, name_a, name_b)
665
+ print_moves_section(res.get("moves"))
666
+
667
+
668
+ def print_task_comparison(trace_a, trace_b, res, name_a, name_b, task,
669
+ context=3) -> None:
670
+ """`--task NAME`: one task stream per side, and nothing else claimed."""
671
+ if res["verdict"] == "REFUSED":
672
+ print(f"A {name_a}, B {name_b}: compared: task {task} -- "
673
+ "not resolved")
674
+ _print_refusal(res)
675
+ return
676
+ print(f"A {name_a}: compared: task {task} (t{res['a_task']})")
677
+ print(f"B {name_b}: compared: task {task} (t{res['b_task']})")
678
+ print_key_line(res.get("moves"))
679
+ for note in _argv_note(trace_a, trace_b):
680
+ print(f"note: {note}")
681
+ print(f"note: only task {task} was compared -- nothing is claimed here "
682
+ "about the thread streams, the other tasks, or the order any of "
683
+ "them ran in")
684
+ if res["verdict"] != "MATCH":
685
+ _print_divergence(res, name_a, name_b, context)
686
+ elif modulo_location(res.get("moves")):
687
+ nm = len(res["moves"].moved)
688
+ print(f"verdict: MATCH modulo location -- identical causal streams "
689
+ f"({len(res['a_stream'])} events) once {nm} moved code "
690
+ f"object(s) are paired by qualname inside task {task}; values, "
691
+ "timing, and LINE events were not compared")
692
+ else:
693
+ print(f"verdict: MATCH -- identical causal streams "
694
+ f"({len(res['a_stream'])} events): the same sequence of "
695
+ "(file, qualname, kind) for CALL/RETURN/RAISE/HANDLED inside "
696
+ f"task {task}; values, timing, and LINE events were not "
697
+ "compared")
698
+ print_moves_section(res.get("moves"))
699
+
700
+
701
+ def add_parser(sub) -> None:
702
+ p = sub.add_parser(
703
+ "diff", help="first causal divergence between two runs",
704
+ description="Aligns the two causal streams and names the first "
705
+ "event where they part, with drill-in commands; "
706
+ "MATCH or DIVERGED, or REFUSED when no verdict "
707
+ "exists.",
708
+ epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
709
+ p.add_argument("run_a", help=RUN_A_HELP)
710
+ p.add_argument("run_b", help=RUN_B_HELP)
711
+ p.add_argument("--context", type=int, default=3,
712
+ help="common causal steps to show before a divergence")
713
+ p.add_argument("--task", default=None, metavar="NAME",
714
+ help="compare one recorded task's stream by name instead "
715
+ "of the thread streams; what a task IS is the "
716
+ "recorder's own, and `info` names the ones a run "
717
+ "has")
718
+ p.add_argument("--ignore-moves", action="store_true",
719
+ help="pair a function that left one file with the same-"
720
+ "named function that appeared in another, then "
721
+ "compare; the pairing is printed with the verdict")
722
+ p.set_defaults(func=run)
723
+
724
+
725
+ def run(args) -> int:
726
+ pa, pb = paths.find_trace(args.run_a), paths.find_trace(args.run_b)
727
+ ta, tb = Trace.open(pa), Trace.open(pb)
728
+ print_truncated(ta)
729
+ print_truncated(tb)
730
+ moves = detect_moves(ta, tb) if args.ignore_moves else None
731
+ if args.task:
732
+ res = compare_task_streams(ta, tb, args.task, moves)
733
+ print_task_comparison(ta, tb, res, pa.stem, pb.stem, args.task,
734
+ args.context)
735
+ else:
736
+ res = compare(ta, tb, moves)
737
+ print_comparison(ta, tb, res, pa.stem, pb.stem, args.context)
738
+ # A refusal is not a bad call: the command was well formed and the
739
+ # traces were readable. What it says is that no comparison could be
740
+ # made against THESE recordings -- incomplete, dropped writes, empty on
741
+ # both sides, mismatched fingerprint bases, tasks with no fingerprints,
742
+ # a name that picks none or two -- and every one of those is fixed by
743
+ # recording again, which is what 3 means (X5). The `error:` exits in
744
+ # `cli.main` keep 2: an unreadable trace or an unresolvable ref IS the
745
+ # call being wrong.
746
+ if res["verdict"] == "REFUSED":
747
+ return UNSETTLED
748
+ return ANSWERED if res["verdict"] == "MATCH" else NEGATIVE