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,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)