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,756 @@
1
+ """`refocus` on a TypeScript trace: re-run the whole harness invocation,
2
+ then compare ONE container of it.
3
+
4
+ `refocus_cmd` owns the command and `refocus_rust` is the shape this file
5
+ follows; what is here is the ONE thing a TypeScript recording does
6
+ differently, and it is not the thing Rust's file is about. A Rust refocus
7
+ cannot re-run in this process either, but what it asks the driver for is one
8
+ build of one target, and the driver hands back one trace. A vitest
9
+ invocation is a POOL: `npx vitest run src/config` starts a harness that
10
+ starts as many worker containers as it likes, each recording its own trace,
11
+ and the reader asked about exactly one of them. So this branch re-runs the
12
+ whole invocation -- there is no way to ask a harness for one container
13
+ without changing what it does -- and then has to say WHICH of the traces
14
+ that came back is the pair, and what it is claiming about the rest.
15
+
16
+ Everything else -- the comparator, the verdict, the assessment, the report,
17
+ the stamps, the licence, the environment rule -- is called unchanged, from
18
+ `refocus_cmd`, `refocus_report` and `refocus_world`. Three verdict
19
+ vocabularies for one question is how three languages would come to disagree
20
+ about what MATCH means (design 2026-09-07, G2).
21
+
22
+ WHAT THIS FILE MAY REFUSE, AND WHY EACH REFUSAL IS BEFORE THE RE-RUN
23
+ ---------------------------------------------------------------------
24
+ A suite costs minutes and has side effects of its own. Every condition that
25
+ would make the answer meaningless is therefore checked BEFORE anything is
26
+ launched, and each one exits 2 (`BAD_CALL`, "fix the call") rather than 3,
27
+ for the reason `_refuse` states: nothing ran, so the reader's next move is a
28
+ different command. The seven, in the order design 2026-09-13 section 2.3
29
+ fixes:
30
+
31
+ 1. `--window` -- this recorder has no per-activation gate at all. Accepting
32
+ the flag and ignoring it would report a narrowing that never happened.
33
+ 2. the original was recorded at `--tier off` -- it holds no causal stream,
34
+ so the comparison the re-run is FOR could not be made whatever came
35
+ back. Cheap to check and the fix is a re-recording, not a flag.
36
+ 3. no `harness_command` -- a trace from a driver before the key existed.
37
+ There is nothing to re-run, and guessing a command is guessing.
38
+ 4. no `harness_cwd` -- sensorium ts 0.13.0 or earlier. The command's own
39
+ arguments are relative to the directory it was TYPED in, which is a
40
+ third directory beside the container's `cwd` and the plan's `root`
41
+ (design section 2.2); without it the re-run has nowhere to start.
42
+ 5. `harness_cwd` gone -- the same fact the Python branch checks about `cwd`
43
+ and the Rust branch about `workspace_root`.
44
+ 6. `root` gone -- the project the plan was made against. A harness cwd that
45
+ still exists over a project that does not is a different fact and gets a
46
+ different sentence.
47
+ 7. the container was a REUSED WORKER -- it ran more than one test file, so
48
+ "which container of the re-run is its pair" has no answer at all. This is
49
+ the one Rust has no counterpart for; `test_files_run` below is the half
50
+ of it that the harness does not report.
51
+
52
+ The sentences carry no `REFUSED:` prefix of their own: `_refuse` prints
53
+ `error: cannot refocus <run>: <sentence>`, and two announcements of one
54
+ refusal read as two refusals. Everything after the design's prefix is
55
+ verbatim, `; nothing was re-run` included.
56
+
57
+ THE PAIR IS FOUND IN THE STORE, BY TEST FILE, AND NEVER PARSED
58
+ ---------------------------------------------------------------
59
+ The driver prints a `run:` line per container. Reading the new run ids off
60
+ them would put a load-bearing link in this process's memory only, and a
61
+ changed print would break `refocus` silently (design 2026-09-07, G3). So the
62
+ driver stamps `refocus_of` into every trace of the invocation and
63
+ `find_pair` asks the STORE which traces carry it; the `run:` lines go to the
64
+ terminal and decide nothing.
65
+
66
+ Linked is not the same as PAIRED, and that is this branch's own problem. A
67
+ suite of 372 test files re-runs as 372 linked traces, of which the reader
68
+ asked about one. `pair_key` is what picks it: the container's `test_file`
69
+ where it has one, its whole `argv` where it ran no test file at all (a
70
+ `node --test` process, a script), and a key of its own -- matching nothing
71
+ -- for a reused worker that ran several. The rest are SIBLINGS -- counted on the pair line and
72
+ stamped as a count, never compared, and `runs` lists them under the new
73
+ invocation with no verdict, which is exactly what they have. A count rather
74
+ than a list of ids because the invocation id already names them and 371 ids
75
+ is not something a reader follows.
76
+
77
+ The timestamp filter in `find_pair` is not belt-and-braces, for the reason
78
+ `refocus_rust.find_pair` gives at length: without it the SECOND refocus of
79
+ one original finds the first one's traces as well as its own, and "more than
80
+ one candidate" is a refusal -- so a second refocus of any run would fail
81
+ permanently. A trace that records no readable `start_ts` is EXCLUDED rather
82
+ than assumed recent: it cannot be shown to be this re-run's.
83
+
84
+ NOTHING IS CAPTURED, AND NOTHING PRINTED IS PARSED
85
+ ---------------------------------------------------
86
+ All three streams are inherited. The Rust branch captures stdout so it can
87
+ echo the driver's `run:` lines after a rebuild that printed nothing for
88
+ minutes; a test suite prints continuously and the person who asked for a
89
+ refocus is watching it -- a captured suite is a suite that appears to hang.
90
+ No timeout, for the reason the other two branches give: a suite's length is
91
+ the caller's to judge, and a timeout that killed one half way would leave
92
+ the store in exactly the state ("no trace linked to this run") this file
93
+ reports as REFUSED.
94
+ """
95
+ import os
96
+ import sqlite3
97
+ import subprocess
98
+ import sys
99
+ import time
100
+ from pathlib import Path
101
+
102
+ from sensorium import paths, redact
103
+ # The two verdict paths this branch shares with the Rust one. Imported, not
104
+ # copied: both print sentences with no language in them -- "the re-run
105
+ # happened and produced no comparable pair" is one verdict with one exit
106
+ # code, and "these checks could not run" is one finding about a pair --
107
+ # and two spellings of one sentence is how two branches come to report the
108
+ # same fact differently (ruling P2, 2026-09-13).
109
+ from sensorium.query.refocus_rust import _refused_after_rerun
110
+ # The licence and world code at its shared home. `env_of` takes this
111
+ # branch's own `is_recorder_key` because which variables are the recorder's
112
+ # bookkeeping is the one part of the environment rule that is per-language;
113
+ # everything done with the answer is shared.
114
+ from sensorium.query.refocus_world import (_source_state, env_of,
115
+ print_unverifiable, relicense,
116
+ stamp_unverifiable,
117
+ unverifiable_checks)
118
+ from sensorium.store import db
119
+ from sensorium.store.reader import Trace
120
+
121
+ #: The meta key holding how many OTHER containers of the re-run invocation
122
+ #: were linked to the original. Stamped on the pair alone (design section
123
+ #: 2.4): it is a fact about the comparison, and a sibling has no comparison.
124
+ SIBLINGS_KEY = "refocus_siblings"
125
+
126
+ #: What a test file's name looks like to this reader. vitest's own default
127
+ #: `include` is `**/*.{test,spec}.?(c|m)[jt]s?(x)`, so the two infixes are
128
+ #: the harness's own convention and not this tool's invention.
129
+ _TEST_INFIXES = (".test.", ".spec.")
130
+
131
+
132
+ #: Every `SENSORIUM_` name `sensorium ts run` puts into the harness's
133
+ #: environment, and no other. ONE source, unlike the Rust branch's three:
134
+ #: `ts/driver.py::_env` builds the whole environment in one function, and
135
+ #: `tests/test_refocus_typescript_recorder_keys.py` parses that function and
136
+ #: holds this set equal to what it sets -- so a variable the driver starts
137
+ #: handing down without a line here fails loudly rather than quietly
138
+ #: widening what a licence stops checking. `SENSORIUM_REDACT_KEY` is added
139
+ #: there rather than found, because `_env` sets it through `redact.KEY_VAR`
140
+ #: and no literal spells it.
141
+ RECORDER_KEYS = frozenset({
142
+ "SENSORIUM_FOCUS",
143
+ "SENSORIUM_INVOCATION",
144
+ "SENSORIUM_MANIFEST_DIR",
145
+ "SENSORIUM_MAX_BYTES",
146
+ "SENSORIUM_MAX_CALLS",
147
+ "SENSORIUM_MAX_EVENTS",
148
+ "SENSORIUM_SPOOL",
149
+ "SENSORIUM_TIER",
150
+ "SENSORIUM_TS_PKG",
151
+ "SENSORIUM_TS_ROOT",
152
+ redact.KEY_VAR,
153
+ })
154
+
155
+
156
+ def is_recorder_key(name: str) -> bool:
157
+ """Whether this variable is the RECORDER's own bookkeeping.
158
+
159
+ The same judgement `_UNCOMPARED_ENV` makes about `SENSORIUM_DIR`, and
160
+ for the same measured reason -- reporting the tool's own footprint as a
161
+ change the world made is noise, not honesty. Here it is not optional:
162
+ THREE of these differ on every refocus by construction --
163
+ `SENSORIUM_INVOCATION` is minted per invocation, and `SENSORIUM_SPOOL`
164
+ and `SENSORIUM_MANIFEST_DIR` are both derived from a fresh spool
165
+ directory per invocation (`ts/driver.py`'s `_env`). A fourth,
166
+ `SENSORIUM_FOCUS`, differs whenever the call deepens the focus: a
167
+ refocus that repeats the original's own `--focus` leaves it identical.
168
+ Compared, those fire on EVERY TypeScript refocus that widens focus --
169
+ and a check that always fires says nothing.
170
+
171
+ The rest carry the SAME fact across the pair -- `SENSORIUM_TS_PKG`,
172
+ `SENSORIUM_TS_ROOT` and `SENSORIUM_TIER` are the package, the project
173
+ root and the depth the re-run inherits -- so nothing is lost by
174
+ exempting them.
175
+
176
+ `SENSORIUM_REDACT_KEY` is the eighth, and it stays for a reason of its
177
+ own: every recorder DELETES it from what it records (`redact.env`), so
178
+ a pair of current traces never holds it -- but a trace converted before
179
+ rule v1 existed does, and comparing it against a re-run that does not
180
+ would report the tool's own key as a change the world made.
181
+
182
+ A LIST AND NOT A PREFIX (R33, 2026-09-14)
183
+ -----------------------------------------
184
+ This was `name.startswith("SENSORIUM_")`, and the argument for it was
185
+ that every variable this recorder sets is under one prefix. True, and
186
+ beside the point: the prefix also claims every variable the recorder
187
+ does NOT set. E16 part A measured what that costs on the Rust branch,
188
+ whose predicate had the identical shape -- a pre-registered
189
+ `SENSORIUM_E16_TOKEN` in the recorded program's environment was removed
190
+ before anything was compared, so a re-run whose value had been rotated
191
+ still earned a full licence (§2, H3). Nothing about that reading was
192
+ about Rust; §1 simply exercised this branch's env clause through
193
+ `tests/test_refocus_redaction.py` rather than live, so this half went
194
+ unmeasured rather than uninfected.
195
+
196
+ So: `RECORDER_KEYS` above, pinned to `_env`, and everything else --
197
+ `SENSORIUM_NO_REDACT`, `SENSORIUM_REDACT_NAMES`,
198
+ `SENSORIUM_REDACT_ALLOW`, which `_env` passes on untouched because what
199
+ a recording was made under is the user's statement, and any
200
+ `SENSORIUM_`-shaped name a person exports -- is the user's and is
201
+ compared like any other variable.
202
+
203
+ The names are printed on the line beside the count rather than hidden
204
+ behind it, which is the rule the shell list follows too: an exemption a
205
+ reader cannot see is a silent one.
206
+ """
207
+ return name in RECORDER_KEYS
208
+
209
+
210
+ # -- what the trace says its tests ran in ----------------------------------
211
+ def _relative_to_root(path: str, root) -> str:
212
+ """`path` under `root`, or `path` exactly as it was recorded.
213
+
214
+ Root-relative where it CAN be, because `meta.test_file` and
215
+ `meta.test_files` are the harness's own spelling and that spelling is
216
+ relative to the project root: two spellings of one file would read as
217
+ two files and refuse a container that ran one. As recorded otherwise --
218
+ a file outside the root has no relative spelling, and inventing one
219
+ (`../../x.test.ts`) would name a path neither the trace nor the harness
220
+ ever used.
221
+ """
222
+ if not root:
223
+ return path
224
+ try:
225
+ return str(Path(path).relative_to(root))
226
+ except ValueError:
227
+ return path
228
+
229
+
230
+ def test_files_run(trace: Trace) -> list[str]:
231
+ """The distinct test files this container's tests ROOTED in, sorted.
232
+
233
+ Ruling P3, condition (b), and it exists because the harness does not
234
+ report the fact condition (a) reads. Under vitest 4.1.9 `--no-isolate
235
+ --maxWorkers 1` ONE container runs both test files, but the setup file's
236
+ top-level `rt.fileStart(...)` runs once under a shared module cache, so
237
+ the trace records `test_file` (singular, the first file) and never
238
+ `test_files`. The trace still KNOWS: a test is a task, its root frame is
239
+ the callback vitest invoked, and that frame's code object names the file
240
+ it was written in.
241
+
242
+ A task ROOT frame is a depth-0 frame whose CALL ran inside a task --
243
+ read through the reader's own accessors (`frames`, `event`, `code`), the
244
+ same path `frame_cmd` takes to name a frame's task, because a second SQL
245
+ spelling of "which task is this frame in" is a second answer waiting to
246
+ disagree with the first.
247
+
248
+ Only files whose name carries `.test.` or `.spec.` are counted, and that
249
+ is the BOUND blind spot 42 states: a second test file whose callbacks
250
+ all root in a shared helper is invisible here, and the container pairs
251
+ by its first file. Counting every distinct root file instead would
252
+ refuse every suite that keeps its assertions in a helper -- a refusal on
253
+ a single-file container is the worse of the two errors, because the
254
+ reader can do nothing about it.
255
+ """
256
+ root = trace.meta.get("root")
257
+ files = set()
258
+ for frame in trace.frames():
259
+ if frame.depth != 0:
260
+ continue
261
+ call = trace.event(frame.call_event_id)
262
+ if call is None or call.task_id is None:
263
+ continue
264
+ path = trace.code(frame.code_id).file
265
+ if any(infix in os.path.basename(path) for infix in _TEST_INFIXES):
266
+ files.add(_relative_to_root(path, root))
267
+ return sorted(files)
268
+
269
+
270
+ # -- may this recording be re-run at all? ----------------------------------
271
+ def refusal(meta: dict, args, trace: Trace) -> str | None:
272
+ """Why re-running this TypeScript recording would be illegitimate.
273
+
274
+ Order is the design's and is load-bearing in one direction: the cheap,
275
+ always-answerable questions about the CALL come first, then the ones
276
+ about the world, then the one about the harness's own scheduling --
277
+ so a call that is wrong in two ways is told about the one the reader can
278
+ act on soonest.
279
+
280
+ `trace` is required rather than defaulted: refusal 7 is derived from the
281
+ trace's own frames, and a call site that passed only the metadata would
282
+ silently skip the check that the harness this refusal exists for is the
283
+ only one that needs.
284
+ """
285
+ if getattr(args, "window", None) is not None:
286
+ return ("--window is not available for a TypeScript trace (the "
287
+ "recorder has no per-activation gate); nothing was re-run")
288
+ run = meta.get("run_id") or "this run"
289
+ if (meta.get("env") or {}).get("SENSORIUM_TIER") == "off":
290
+ return (f"run {run} was recorded at --tier off and holds no causal "
291
+ "stream to compare against; nothing was re-run")
292
+ if not meta.get("harness_command"):
293
+ return (f"run {run} records no harness command to re-run (recorded "
294
+ "by a driver before the key existed); nothing was re-run")
295
+ cwd = meta.get("harness_cwd")
296
+ if not cwd:
297
+ return (f"run {run} records no working directory to re-run from "
298
+ "(recorded by sensorium ts 0.13.0 or earlier); nothing was "
299
+ "re-run")
300
+ if not os.path.isdir(cwd):
301
+ return f"directory {cwd} no longer exists; nothing was re-run"
302
+ root = meta.get("root")
303
+ # Absent `root` is not checked: the key arrived with the same driver
304
+ # `harness_cwd` did, so a trace that has one has both, and a refusal on
305
+ # its absence would be a second sentence for the fact refusal 4 already
306
+ # reported.
307
+ if root and not os.path.isdir(root):
308
+ return f"project root {root} no longer exists; nothing was re-run"
309
+ # BOTH readings, and the LARGER of them (ruling P11): the converter's
310
+ # own report where it made one, the trace's own task roots always. A
311
+ # converter that lists the file starts sees files whose tests rooted in
312
+ # a helper, which the frames cannot -- and a converter that UNDER-
313
+ # reports (the vitest shape ruling P3 was written for reports one file
314
+ # for two) must not be able to mask what the frames plainly show.
315
+ # Neither reading may lower the other's count, so neither is trusted
316
+ # over the other; the refusal fires on the evidence that saw more.
317
+ declared = meta.get("test_files") or []
318
+ n = max(len(declared), len(test_files_run(trace)))
319
+ if n >= 2:
320
+ return (f"run {run} ran {n} test files in one container (a reused "
321
+ "worker); which container of a re-run would be its pair is "
322
+ "the harness's scheduling, not a fact; nothing was re-run")
323
+ return None
324
+
325
+
326
+ # -- the re-run ------------------------------------------------------------
327
+ def rerun_argv(meta: dict, requested_focus, run_id: str) -> list[str]:
328
+ """The invocation that re-records this run's whole suite, deeper.
329
+
330
+ `sys.executable -m sensorium`, never a `sensorium` on PATH: the re-run
331
+ must be recorded by THIS sensorium, and a name on the path could resolve
332
+ to another version entirely -- the pair would then be compared across
333
+ two recorders, which is the one thing the verdict may not rest on.
334
+
335
+ `--refocus-of` is what makes the new traces findable afterwards, so it is
336
+ first and unconditional. `--tier` is the ORIGINAL's, read from its
337
+ recorded environment: omitted when the key is absent, so the driver's own
338
+ default applies rather than this file asserting one. The focus list is
339
+ `refocus_cmd._merged_focus`'s -- the original's values then the caller's,
340
+ never fewer than the original's -- and reusing that function is the
341
+ point: "a refocus only ever captures MORE" must mean the same thing in
342
+ all three languages.
343
+
344
+ `harness_command` goes last, after a bare `--`, and verbatim: it is the
345
+ tokens as they were typed, and the `--` is what stops the driver reading
346
+ the harness's own flags as its own.
347
+ """
348
+ from sensorium.query.refocus_cmd import _merged_focus
349
+
350
+ argv = [sys.executable, "-m", "sensorium", "ts", "run",
351
+ "--refocus-of", run_id]
352
+ tier = (meta.get("env") or {}).get("SENSORIUM_TIER")
353
+ if tier:
354
+ argv += ["--tier", str(tier)]
355
+ for value in _merged_focus(meta, requested_focus):
356
+ argv += ["--focus", value]
357
+ return argv + ["--", *[str(a) for a in meta["harness_command"]]]
358
+
359
+
360
+ def _launch(argv: list[str], cwd: str, store: Path) -> tuple[float, object]:
361
+ """Run the harness from the directory it was typed in, under the
362
+ original's store.
363
+
364
+ `SENSORIUM_DIR` is the resolved ABSOLUTE store of the original, for the
365
+ reason `refocus_cmd._pin_trace_store` states one level up: a relative
366
+ value would follow the child into the project and write the new traces
367
+ where `find_pair` -- and `sensorium runs` -- will never look. Nothing
368
+ else is set or stripped, so the environment the re-run executed under is
369
+ the caller's, and the two traces' own recorded environments are what the
370
+ licence check compares afterwards.
371
+
372
+ No stream is captured. The harness's output is what a person waiting on
373
+ a suite is watching, and the driver's own `run:` lines print live with
374
+ it; a captured suite is a suite that appears to hang. Nothing printed is
375
+ parsed -- the pair comes out of the store.
376
+ """
377
+ launched_at = time.time()
378
+ proc = subprocess.run(
379
+ argv, cwd=cwd, env={**os.environ, "SENSORIUM_DIR": str(store)})
380
+ return launched_at, proc
381
+
382
+
383
+ # -- the pair --------------------------------------------------------------
384
+ def pair_key(meta: dict) -> tuple:
385
+ """What identifies "the same container" across the two invocations.
386
+
387
+ The test file where there is one: a worker's slot, pid and thread are
388
+ all whatever the pool handed it, and the file it ran is the only thing
389
+ about a container that the reader asked about. Its whole `argv`
390
+ otherwise -- a `node --test` process or a plain script carries no
391
+ `test_file`, and its command line is what it is.
392
+
393
+ A REUSED WORKER has a key of its own, and it matches nothing: design
394
+ section 2.4's second bullet says an argv-keyed original pairs with a
395
+ candidate that "carries neither `test_file` nor `test_files` and whose
396
+ argv equals the original's", so a container that ran several files is
397
+ not that candidate however its command line reads. Falling through to
398
+ the argv key instead would pair a no-test-file original with a container
399
+ running two files -- the very shape refusal 7 will not let a reader ASK
400
+ about, admitted through the back door of the re-run. `("test_files",
401
+ ...)` equals neither an original's `test_file` key nor its argv key, so
402
+ such a container lands among the siblings: counted, named, compared to
403
+ nothing.
404
+
405
+ A falsy `test_file` falls through deliberately: null or empty is not a
406
+ file, and `("test_file", None)` would pair two containers on the
407
+ strength of both failing to record one. The same for an empty
408
+ `test_files`.
409
+ """
410
+ if meta.get("test_file"):
411
+ return ("test_file", meta["test_file"])
412
+ if meta.get("test_files"):
413
+ return ("test_files", *[str(f) for f in meta["test_files"]])
414
+ return ("argv", *[str(a) for a in (meta.get("argv") or [])])
415
+
416
+
417
+ def _key_text(key: tuple) -> str:
418
+ """The key as a refusal names it, in the reader's own vocabulary."""
419
+ if key[0] == "test_file":
420
+ return key[1]
421
+ return "argv " + " ".join(key[1:])
422
+
423
+
424
+ def find_pair(traces_dir, run_id: str, launched_at: float,
425
+ key: tuple) -> tuple[list[str], list[str]]:
426
+ """(the candidates, the siblings) this re-run produced, in name order.
427
+
428
+ A trace is LINKED on two counts, and BOTH are necessary: it names
429
+ `run_id` in `refocus_of` (the driver stamped it, so the link is durable
430
+ and the same one `info` prints), and its own recording started at or
431
+ after `launched_at` (so an EARLIER refocus of the same original is not
432
+ mistaken for this one -- see the module docstring).
433
+
434
+ A linked trace is then a CANDIDATE when its `pair_key` equals the
435
+ original's, and a SIBLING otherwise. The split is what makes a suite
436
+ refocusable at all: every container of the invocation is linked, and
437
+ counted as candidates they would be "more than one" on every re-run of
438
+ every suite with two test files in it.
439
+ """
440
+ linked = []
441
+ for path in sorted(Path(traces_dir).glob("*.db")):
442
+ try:
443
+ conn = db.open_trace(path)
444
+ except (OSError, sqlite3.DatabaseError, db.TraceFormatError):
445
+ # A file this process cannot open is not a trace the driver
446
+ # just wrote. Skipped rather than reported: the answer this
447
+ # function owes is "which traces are linked", and a store may
448
+ # hold a half-written or newer-format file for its own reasons.
449
+ continue
450
+ try:
451
+ of = db.get_meta(conn, "refocus_of")
452
+ started = db.get_meta(conn, "start_ts")
453
+ meta = db.all_meta(conn)
454
+ finally:
455
+ conn.close()
456
+ if of != run_id:
457
+ continue
458
+ if not isinstance(started, (int, float)) or started < launched_at:
459
+ continue
460
+ linked.append((path.stem, pair_key(meta)))
461
+
462
+ candidates = [name for name, k in linked if k == key]
463
+ siblings = [name for name, k in linked if k != key]
464
+ return candidates, siblings
465
+
466
+
467
+ def siblings_note(n: int) -> str:
468
+ """The clause that says what the re-run produced beside the pair.
469
+
470
+ One sentence, used wherever the outcome of the lookup is announced --
471
+ on the pair line and again by `info` after the terminal has scrolled --
472
+ because a reader told about the same fact in two wordings has to work
473
+ out whether they are the same fact. It names the count AND what is being
474
+ claimed about them, which is nothing: they were re-run, and no
475
+ comparison was made of any of them.
476
+ """
477
+ return f"siblings in the re-run: {n} (not compared; UNVERIFIED)"
478
+
479
+
480
+ def stamp_siblings(path: Path, n: int) -> None:
481
+ """Write the sibling COUNT into the pair's trace.
482
+
483
+ Stamped even when it is zero, for `stamp_unverifiable`'s reason one key
484
+ over: `0` says the lookup ran over this invocation and found the pair
485
+ alone, while an ABSENT key says the trace was written before the count
486
+ existed. A key that only appears sometimes cannot tell a later reader
487
+ which of the two it is looking at.
488
+
489
+ The ids are NOT stamped: the new invocation id already names them --
490
+ `runs` groups by it -- and a list of 371 run ids is not a thing a reader
491
+ follows.
492
+ """
493
+ conn = db.open_trace(path)
494
+ try:
495
+ db.set_meta(conn, SIBLINGS_KEY, n)
496
+ conn.commit()
497
+ finally:
498
+ conn.close()
499
+
500
+
501
+ # -- the verdict -----------------------------------------------------------
502
+ def _harness_exit(meta: dict) -> str:
503
+ """One invocation's ending, as the driver WAITED for it.
504
+
505
+ `harness_exit`, never the container's `exit_status`: a vitest worker is
506
+ killed by its pool and its own exit is unwitnessed (`exit_status_basis:
507
+ unwitnessed`, null on every trace this recorder writes), so printing
508
+ that would put a `?` on both sides of a line whose whole job is to say
509
+ how the two runs ended. The basis travels with the number, because "0"
510
+ learned by waiting and "0" read off a self-report are different claims.
511
+ """
512
+ ending = meta.get("harness_exit")
513
+ if not isinstance(ending, dict):
514
+ return "?"
515
+ basis = ending.get("basis") or "?"
516
+ if ending.get("signal"):
517
+ return f"signal {ending['signal']} ({basis})"
518
+ status = ending.get("status")
519
+ return f"{'?' if status is None else status} ({basis})"
520
+
521
+
522
+ def _ending(meta: dict, key: str) -> dict | None:
523
+ """The `key` ending this trace RECORDED, or None for no record at all.
524
+
525
+ A non-dict is read as absent for `_harness_exit`'s reason one function
526
+ up: what a later reader must not do is treat a value it cannot read as
527
+ a value that agreed.
528
+ """
529
+ ending = meta.get(key)
530
+ return ending if isinstance(ending, dict) else None
531
+
532
+
533
+ def _harness_side(ending: dict) -> str:
534
+ """One harness's ending, as the DIFFERING clause names it.
535
+
536
+ `exit <status>` or `signal <name>`, because the two are exclusive: a
537
+ process killed by a signal chose no status, and printing `exit None`
538
+ for it would name a number nobody set.
539
+ """
540
+ if ending.get("signal"):
541
+ return f"signal {ending['signal']}"
542
+ status = ending.get("status")
543
+ return f"exit {'?' if status is None else status}"
544
+
545
+
546
+ def _container_side(ending: dict) -> str:
547
+ """One container's self-report, as the DIFFERING clause names it.
548
+
549
+ A signal by its bare name and a code as `exit <code>`, which is the
550
+ asymmetry the record has: a container reports the signal it was killed
551
+ with as a NAME (`SIGTERM`), and its own chosen code as a number. A
552
+ record carrying neither is said rather than dropped -- `info`'s
553
+ `_self_reported_line` makes the same distinction, because a missing
554
+ key means "no EXIT record" and this is not that.
555
+ """
556
+ if ending.get("code") is not None:
557
+ return f"exit {ending['code']}"
558
+ if ending.get("signal") is not None:
559
+ return str(ending["signal"])
560
+ return "neither a code nor a signal"
561
+
562
+
563
+ def _agreed_harness(was: dict, now: dict) -> str:
564
+ """The ending BOTH invocations reached, as the verified fact names it.
565
+
566
+ The status bare (`0`) rather than `exit 0`, because the fact's own
567
+ words already say what the number is. The basis travels with it for
568
+ `_harness_exit`'s reason -- "0" learned by waiting and "0" read off a
569
+ self-report are different claims -- and is `?` when the two sides do
570
+ not agree on it: `basis` is `waited` on every trace this recorder
571
+ writes, and a later recorder that learned one ending another way must
572
+ not have this sentence claim its side was waited for.
573
+ """
574
+ basis = was.get("basis") if was.get("basis") == now.get("basis") else None
575
+ if was.get("signal"):
576
+ shown = f"signal {was['signal']}"
577
+ else:
578
+ status = was.get("status")
579
+ shown = "?" if status is None else str(status)
580
+ return f"harness exit equal ({shown}, {basis or '?'})"
581
+
582
+
583
+ def exit_clauses(orig_meta: dict,
584
+ new_meta: dict) -> tuple[list[str], list[str]]:
585
+ """(caveats, facts) about how the two invocations and their two
586
+ containers ended.
587
+
588
+ The branch's own clauses, and they exist because the SHARED one cannot
589
+ be about this recorder. `_licence_caveats` compares `exit_status`,
590
+ which a vitest container never witnesses: the pool kills its workers,
591
+ the converter writes null with basis `unwitnessed` on every trace, and
592
+ null compared with null is equal -- so on a TypeScript pair that clause
593
+ is silent, and silence in a licence check reads as agreement. It is
594
+ left exactly as it is (it is Python's and Rust's, where the status IS
595
+ witnessed); what is added here are the two endings somebody really did
596
+ observe.
597
+
598
+ Both are compared, because they answer different questions. The DRIVER
599
+ waited for the harness, so `harness_exit` is the invocation's ending
600
+ and the only one with a basis; the CONTAINER reported its own ending on
601
+ the way out (`exit_self_reported`), which is a fact about the worker
602
+ the comparison is actually of. A pair whose harnesses agree and whose
603
+ containers do not ran the same suite to the same total and killed one
604
+ worker differently, which is a difference the licence may not sit on.
605
+
606
+ An ABSENT record is a caveat and never a fact, on each side by name:
607
+ "not recorded" is not "ended the same way", and which side was not
608
+ witnessed is the reader's next question. Equality is over status AND
609
+ signal (and code and signal for the container) rather than over the
610
+ dicts, so a key a later driver writes beside them cannot read as two
611
+ invocations ending differently: `HarnessExit` already carries two wall
612
+ clocks that its `meta()` strips today, and a driver that stopped
613
+ stripping them would otherwise withhold every licence it granted.
614
+
615
+ ONE fact when everything agreed, not two: how the two runs ended is one
616
+ question, and a reader told the answer twice has to work out whether it
617
+ is the same answer.
618
+ """
619
+ caveats = []
620
+ was = _ending(orig_meta, "harness_exit")
621
+ now = _ending(new_meta, "harness_exit")
622
+ for label, ending in (("the original", was), ("the rerun", now)):
623
+ if ending is None:
624
+ caveats.append(f"{label}'s harness exit was not recorded")
625
+ if was is not None and now is not None and (
626
+ (was.get("status"), was.get("signal"))
627
+ != (now.get("status"), now.get("signal"))):
628
+ caveats.append("the two invocations' harnesses ended differently: "
629
+ f"{_harness_side(was)} originally, "
630
+ f"{_harness_side(now)} on the rerun")
631
+ said_was = _ending(orig_meta, "exit_self_reported")
632
+ said_now = _ending(new_meta, "exit_self_reported")
633
+ for label, ending in (("the original", said_was), ("the rerun", said_now)):
634
+ if ending is None:
635
+ caveats.append(f"{label}'s container reported no ending")
636
+ if said_was is not None and said_now is not None and (
637
+ (said_was.get("code"), said_was.get("signal"))
638
+ != (said_now.get("code"), said_now.get("signal"))):
639
+ caveats.append("the two containers reported different endings: "
640
+ f"{_container_side(said_was)} originally, "
641
+ f"{_container_side(said_now)} on the rerun")
642
+ if caveats:
643
+ return caveats, []
644
+ return [], [f"{_agreed_harness(was, now)}; container endings equal"]
645
+
646
+
647
+ def _verify(args, orig: Trace, orig_name: str, meta: dict, new_id: str,
648
+ source_caveat, source_fact, siblings: list[str]) -> int:
649
+ """Compare the pair, assess it, stamp it, report it."""
650
+ from sensorium.query.diff_cmd import compare
651
+ from sensorium.query.refocus_cmd import _stamp, assess, report
652
+
653
+ new_path = (paths.traces_dir() / f"{new_id}.db").resolve()
654
+ new = Trace.open(new_path)
655
+ env_line, env_caveat, env_fact = env_of(meta, new, is_recorder_key)
656
+ # The two endings, as findings about the WORLD the pair ran in --
657
+ # alongside the source and the environment, and for the same reason
658
+ # `assess` takes those from the caller: they are established outside the
659
+ # traces' own call streams, and only this branch knows where its
660
+ # recorder wrote them.
661
+ exit_caveats, exit_facts = exit_clauses(meta, new.meta)
662
+ world_verified = [f for f in (source_fact, env_fact, *exit_facts) if f]
663
+ res = compare(orig, new)
664
+ a = assess(orig, new, res,
665
+ [c for c in (source_caveat, env_caveat, *exit_caveats) if c],
666
+ world_verified)
667
+ checks = unverifiable_checks(orig, new)
668
+ a = relicense(a, orig, new, world_verified)
669
+ _stamp(new_path, res, a)
670
+ stamp_unverifiable(new_path, checks)
671
+ stamp_siblings(new_path, len(siblings))
672
+
673
+ print("--- verdict ---")
674
+ # The pair line, and the only place a reader is told what ELSE the
675
+ # re-run produced: which trace the verdict is about and which traces it
676
+ # is not about are one fact, so they are one line. The invocation is on
677
+ # it because that is what `runs` groups the siblings under -- the reader
678
+ # who wants to see them has the id in front of them.
679
+ print(f"run: {new_id} invocation: {new.meta.get('invocation')} "
680
+ f"{siblings_note(len(siblings))}")
681
+ print(f"trace: {new_path}")
682
+ print(env_line)
683
+ print(f"exit: rerun {_harness_exit(new.meta)} original "
684
+ f"{_harness_exit(meta)}")
685
+ # `report` prints the blind-spot block, this recorder's own lines
686
+ # included (`vocab.blind_spots`); what follows it is the pair's own
687
+ # unrun checks, which are findings about THIS pair rather than about the
688
+ # recorder, and are stamped as well as printed.
689
+ code = report(orig, new, res, orig_name, new_id, a,
690
+ compact=bool(getattr(args, "compact", False)))
691
+ print_unverifiable(checks)
692
+ return code
693
+
694
+
695
+ def run(args, orig: Trace, orig_name: str, meta: dict) -> int:
696
+ """The TypeScript branch of `sensorium refocus`, whole."""
697
+ from sensorium.query.refocus_cmd import (_merged_focus, _pin_trace_store,
698
+ _refuse)
699
+
700
+ problem = refusal(meta, args, orig)
701
+ if problem:
702
+ return _refuse(orig_name, problem, orig)
703
+
704
+ # Pinned and resolved BEFORE the child is launched, for
705
+ # `_pin_trace_store`'s reason: a relative SENSORIUM_DIR would resolve
706
+ # against the project the harness runs in, not against the directory
707
+ # this command was invoked from, and the new traces would land where
708
+ # the pair lookup never looks.
709
+ _pin_trace_store()
710
+ store = paths.trace_root().resolve()
711
+ traces = paths.traces_dir().resolve()
712
+ cwd = meta["harness_cwd"]
713
+ run_id = meta.get("run_id") or orig_name
714
+ argv = rerun_argv(meta, args.focus, run_id)
715
+
716
+ # The original's source digests are ABSOLUTE (`ts/build.py`'s `_on_file`
717
+ # records the resolved path), so they re-hash from any directory and
718
+ # there is nothing to chdir for. Checked before the re-run, as the other
719
+ # branches check it: a source that has changed is worth knowing before
720
+ # a suite is spent on it.
721
+ source, source_caveat, source_fact = _source_state(meta)
722
+
723
+ # The command as a person would type it, not as this process runs it:
724
+ # `argv[:3]` is the interpreter and `-m sensorium`, which is the next
725
+ # line's business, and a reader who wants to run it again themselves
726
+ # should be able to copy this one.
727
+ print(f"refocus-of: {orig_name} cmd: "
728
+ + " ".join(["sensorium", *argv[3:]]))
729
+ print(f"via: {sys.executable} -m sensorium")
730
+ print(f"cwd: {cwd}")
731
+ print(f"focus: {', '.join(_merged_focus(meta, args.focus))} window: -")
732
+ print(source)
733
+ print("--- rerunning (the harness's own output follows; the driver's "
734
+ "run: lines print with it) ---")
735
+ launched_at, proc = _launch(argv, cwd, store)
736
+
737
+ key = pair_key(meta)
738
+ ids, siblings = find_pair(traces, run_id, launched_at, key)
739
+ if not ids:
740
+ # The count is of what WAS linked, so a reader can tell "the suite
741
+ # never ran" from "the suite ran and this container was not in it"
742
+ # -- a filter, a `--maxWorkers` change, a file that no longer
743
+ # exists. The harness's exit is named beside it for the same reason.
744
+ return _refused_after_rerun(
745
+ orig, f"the re-run produced {len(siblings)} trace(s) linked to "
746
+ f"{run_id} and none ran {_key_text(key)} (harness exit "
747
+ f"{proc.returncode}); see the harness's output above")
748
+ if len(ids) > 1:
749
+ return _refused_after_rerun(
750
+ orig, f"the re-run produced {len(ids)} traces linked to "
751
+ f"{run_id} that each ran {_key_text(key)} "
752
+ f"({', '.join(ids)}); two containers of one invocation "
753
+ "claiming one test file is a fact about the harness this "
754
+ "tool will not guess through")
755
+ return _verify(args, orig, orig_name, meta, ids[0], source_caveat,
756
+ source_fact, siblings)