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,197 @@
|
|
|
1
|
+
"""Which threads a run started, and which of them the comparison saw.
|
|
2
|
+
|
|
3
|
+
Split out of `refocus_world` at that file's 800-line ceiling, along the seam
|
|
4
|
+
CARRIED-DEBT named for it: the thread bookkeeping. Everything here answers
|
|
5
|
+
one question -- how many threads were there, and whose were they -- and the
|
|
6
|
+
answers are read by three callers that print them (`refocus_report`'s
|
|
7
|
+
`threads:` line, `info_cmd`, `diff_notes`) and by `refocus_world`'s own
|
|
8
|
+
caveats. Nothing here decides a verdict or prints one.
|
|
9
|
+
|
|
10
|
+
`compared_threads` travels with them although CARRIED-DEBT's seam names only
|
|
11
|
+
the four: it is `uncompared_threads`' only helper, and leaving it behind
|
|
12
|
+
would make this module import `refocus_world` back, which is a cycle and a
|
|
13
|
+
second direction for one command's internals to travel in.
|
|
14
|
+
|
|
15
|
+
The names stay reachable as `refocus_world.<name>` -- the re-export there is
|
|
16
|
+
the same one `refocus_cmd` uses for `refocus_world` and `refocus_report`.
|
|
17
|
+
These are one command's internals across its files, not separate modules
|
|
18
|
+
with surfaces of their own.
|
|
19
|
+
"""
|
|
20
|
+
# The site-mark lookup, imported rather than rebuilt. `meta.sites` joins to
|
|
21
|
+
# `code_objects` on a workspace-relative path against an absolute one, and
|
|
22
|
+
# two implementations of that join are two ways for one trace to be read.
|
|
23
|
+
from sensorium.query.exceptions_rust import _marks as _site_marks
|
|
24
|
+
from sensorium.query.vocab import terms
|
|
25
|
+
from sensorium.store.reader import Trace
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def harness_threads(trace: Trace) -> set[int]:
|
|
29
|
+
"""The threads this trace's RECORDER started, not the program.
|
|
30
|
+
|
|
31
|
+
`cargo test` runs every `#[test]` function on a thread libtest spawns
|
|
32
|
+
for it, so a `cargo test` trace always carries one non-main thread the
|
|
33
|
+
program did not start -- and the untraced-thread caveat below fired on
|
|
34
|
+
all 61 pairs of E4 for that reason and no other (E4 section 5.2, design
|
|
35
|
+
2026-09-07 R1). A clause that cannot NOT fire is not a finding, and the
|
|
36
|
+
precedent for taking it out is one this licence already sets: the
|
|
37
|
+
recorder's own environment variables are excluded from the environment
|
|
38
|
+
comparison, by name.
|
|
39
|
+
|
|
40
|
+
A harness thread is a NON-MAIN thread whose FIRST root frame's site the
|
|
41
|
+
manifest marks `#[test]` and whose task the runtime did NOT name at a
|
|
42
|
+
spawn site. Each clause is load-bearing:
|
|
43
|
+
|
|
44
|
+
* the ROOT: a marked fn called from deeper on another thread says
|
|
45
|
+
nothing about who started that thread;
|
|
46
|
+
* the FIRST root: a thread that runs one instrumented fn to completion
|
|
47
|
+
and then another has two, and only the first is how it began;
|
|
48
|
+
* NOT spawn-named: the mark is no proof the other way. `#[test] fn` is
|
|
49
|
+
an ordinary fn to rustc, so `thread::spawn(|| a_test_fn())` puts a
|
|
50
|
+
MARKED root on a thread the PROGRAM started -- the closure holds no
|
|
51
|
+
`?`, so it opens no frame of its own -- and subtracting it GRANTED
|
|
52
|
+
this licence over a program thread until 2026-09-08 (blind spot 28,
|
|
53
|
+
design R3). `sensorium-rt` names a workspace spawn at its site
|
|
54
|
+
(`spawn@<qualname>#<k>`, or `<parent> :: spawn@...`), the recorded
|
|
55
|
+
fact that tells two identical-looking roots apart.
|
|
56
|
+
|
|
57
|
+
An `async` test fn carries no site row -- the transform classifies it
|
|
58
|
+
`async` and skips it whole, `#[tokio::test]` with it -- so it has no
|
|
59
|
+
mark and its thread is COUNTED as the program's, which claims less.
|
|
60
|
+
|
|
61
|
+
Empty for a recorder whose traces carry no site marks at all -- every
|
|
62
|
+
Python trace -- and empty unless the main thread is a RECORDED fact.
|
|
63
|
+
`main_thread_id()` never reports "the trace does not say": it falls
|
|
64
|
+
back to the thread of whichever event got id 1, which under `--focus`
|
|
65
|
+
filtering or ordinary scheduling jitter can name a worker. Subtracting
|
|
66
|
+
on a guess is the one way this rule can take a thread out of a count it
|
|
67
|
+
was never in, so `main_thread_basis()` -- "recorded", "inferred", or
|
|
68
|
+
None for a trace with no events at all -- is what the exclusion rests
|
|
69
|
+
on. Neither empty case is a harness thread that went unfound: both
|
|
70
|
+
leave every count exactly as it was, the direction that claims less.
|
|
71
|
+
"""
|
|
72
|
+
if trace.main_thread_basis() != "recorded":
|
|
73
|
+
return set()
|
|
74
|
+
main = trace.main_thread_id()
|
|
75
|
+
marks = _site_marks(trace.meta)
|
|
76
|
+
found, decided = set(), {main}
|
|
77
|
+
# `decided` holds the main thread from the start (never the harness's)
|
|
78
|
+
# and every other thread from its FIRST root: `roots()` is frame-id
|
|
79
|
+
# ordered, so a later root of a thread already decided never votes.
|
|
80
|
+
for root in trace.roots():
|
|
81
|
+
thread = root.thread_id
|
|
82
|
+
if thread in decided:
|
|
83
|
+
continue
|
|
84
|
+
decided.add(thread)
|
|
85
|
+
# A thread with no task row, or one whose name could not be read
|
|
86
|
+
# (`Task.name` is nullable by schema), carries no spawn name to
|
|
87
|
+
# read: it is decided on its root's mark alone, as every thread was
|
|
88
|
+
# before this rule.
|
|
89
|
+
#
|
|
90
|
+
# `trace.task(<thread serial>)` and not a lookup through `tasks()`:
|
|
91
|
+
# on a Rust trace the task id IS the thread serial, guaranteed at
|
|
92
|
+
# the write (`rust/cargo-sensorium/src/convert/sqlite.rs:248`:
|
|
93
|
+
# "`id` is the thread serial, not an autoincrement rowid: the Rust
|
|
94
|
+
# model has no task identity independent of the thread that ran
|
|
95
|
+
# it"). The invariant is the converter's and this reader depends on
|
|
96
|
+
# it, so it is named here rather than left to be rediscovered; a
|
|
97
|
+
# recorder that ever minted task ids of its own would make this a
|
|
98
|
+
# lookup of the wrong row and every thread would read unnamed --
|
|
99
|
+
# which claims LESS (no thread would be spawn-named, so none would
|
|
100
|
+
# be skipped) and is the direction a wrong answer here should fall.
|
|
101
|
+
task = trace.task(thread)
|
|
102
|
+
name = "" if task is None or task.name is None else task.name
|
|
103
|
+
if name.startswith("spawn@") or " :: spawn@" in name:
|
|
104
|
+
continue
|
|
105
|
+
code = trace.code(root.code_id)
|
|
106
|
+
if marks.get((code.qualname, code.file)) == "test":
|
|
107
|
+
found.add(thread)
|
|
108
|
+
return found
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def harness_exclusion(trace: Trace) -> tuple[int, str]:
|
|
112
|
+
"""How many threads this recorder started itself, and the clause that
|
|
113
|
+
NAMES them wherever one of its thread counts is printed.
|
|
114
|
+
|
|
115
|
+
The clause travels with the count on purpose. A subtraction that showed
|
|
116
|
+
only its result would put a smaller number where a larger one used to
|
|
117
|
+
be with nothing on the line to say why -- a number that looks measured
|
|
118
|
+
standing in for a fact that was removed, which is this project's own
|
|
119
|
+
bug class one level up.
|
|
120
|
+
"""
|
|
121
|
+
phrase = terms(trace).harness_thread
|
|
122
|
+
if phrase is None:
|
|
123
|
+
return 0, ""
|
|
124
|
+
n = len(harness_threads(trace))
|
|
125
|
+
if not n:
|
|
126
|
+
return 0, ""
|
|
127
|
+
return n, f" and {n} harness thread{'' if n == 1 else 's'} ({phrase})"
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def harness_note(trace: Trace) -> str:
|
|
131
|
+
"""The harness exclusion as a clause of its OWN, for a line whose counts
|
|
132
|
+
it is not one of.
|
|
133
|
+
|
|
134
|
+
`harness_exclusion`'s clause follows a count and joins it (" and 1
|
|
135
|
+
harness thread ..."); on a line that counts what was NOT compared, the
|
|
136
|
+
same words would say the harness thread is one of them. Same fact, same
|
|
137
|
+
vocabulary, a grammatical slot that does not lie. Empty where the
|
|
138
|
+
recorder starts no thread of its own.
|
|
139
|
+
"""
|
|
140
|
+
n, _clause = harness_exclusion(trace)
|
|
141
|
+
if not n:
|
|
142
|
+
return ""
|
|
143
|
+
plural, verb = ("", "is") if n == 1 else ("s", "are")
|
|
144
|
+
return (f"; {n} harness thread{plural} ({terms(trace).harness_thread}) "
|
|
145
|
+
f"{verb} not among these counts")
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def compared_threads(trace: Trace) -> set[int]:
|
|
149
|
+
"""The threads whose call shape this trace actually had compared.
|
|
150
|
+
|
|
151
|
+
NOT `fingerprints()`. The Rust converter writes exactly ONE thread row
|
|
152
|
+
-- the main thread's -- and routes every other thread's events into
|
|
153
|
+
`task_fingerprints` (`convert/frames.rs`), so a count of thread rows
|
|
154
|
+
reported every non-main Rust thread as one that "ran no traced code,
|
|
155
|
+
left no fingerprint, and was NOT compared" while its whole call shape
|
|
156
|
+
had been compared, on the very thread the code under test runs on.
|
|
157
|
+
|
|
158
|
+
A task row is followed back to its thread through the `tasks` table
|
|
159
|
+
rather than assumed to be one: in Python a task is an asyncio task and
|
|
160
|
+
many of them share a thread, so adding task rows to a thread count
|
|
161
|
+
would be the same error facing the other way. A task whose `tasks` row
|
|
162
|
+
is missing names no thread and adds none -- that reports MORE
|
|
163
|
+
uncompared threads, which is the direction that claims less.
|
|
164
|
+
"""
|
|
165
|
+
threads = set(trace.fingerprints())
|
|
166
|
+
thread_of = {task.id: task.thread_id for task in trace.tasks()}
|
|
167
|
+
for task_id in trace.task_fingerprints():
|
|
168
|
+
thread = thread_of.get(task_id)
|
|
169
|
+
if thread is not None:
|
|
170
|
+
threads.add(thread)
|
|
171
|
+
return threads
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def uncompared_threads(trace: Trace) -> int | None:
|
|
175
|
+
"""How many threads this trace records STARTING and did not compare.
|
|
176
|
+
|
|
177
|
+
None when it does not record how many threads it started: absence of
|
|
178
|
+
the record is not a record of absence, and a count derived from a
|
|
179
|
+
missing key is the one number a line about what went uncompared must
|
|
180
|
+
never print.
|
|
181
|
+
|
|
182
|
+
Harness threads are the recorder's own, so they are not among the
|
|
183
|
+
program's uncompared threads -- but only the ones NOT already compared
|
|
184
|
+
are subtracted, or a harness thread whose stream WAS compared (the
|
|
185
|
+
ordinary case: it is the thread the `#[test]` fn runs on) would come
|
|
186
|
+
off the count twice. Clamped at zero rather than printed negative: a
|
|
187
|
+
thread can leave a fingerprint without the audit hook counting its
|
|
188
|
+
creation -- a C extension's thread in Python -- and a negative here
|
|
189
|
+
would be arithmetic across two populations reported as a measurement.
|
|
190
|
+
"""
|
|
191
|
+
started = trace.meta.get("threads_started")
|
|
192
|
+
if started is None:
|
|
193
|
+
return None
|
|
194
|
+
compared = compared_threads(trace)
|
|
195
|
+
unfound_harness = harness_threads(trace) - compared
|
|
196
|
+
return max(started - len(compared - {trace.main_thread_id()})
|
|
197
|
+
- len(unfound_harness), 0)
|