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.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- 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
|