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,537 @@
1
+ """`refocus` on a Rust trace: re-invoke `cargo sensorium`, then compare.
2
+
3
+ `refocus_cmd` owns the command; this file owns the ONE thing a Rust
4
+ recording does differently -- it cannot be re-run in this process. A Python
5
+ refocus imports the target and runs it under a deeper recorder; a Rust
6
+ refocus has to ask the driver to rebuild the crate with a `--focus` spliced
7
+ in, from the workspace root, and then FIND the trace that came back. Every
8
+ other part of the command -- the comparator, the verdict, the assessment,
9
+ the report, the stamps -- is `refocus_cmd`'s and is called here unchanged,
10
+ because two verdict vocabularies for one question is how the two languages
11
+ would come to disagree about what MATCH means (design 2026-09-07, G2).
12
+
13
+ WHAT THIS FILE MAY REFUSE, AND WHY EACH REFUSAL IS BEFORE THE RE-RUN
14
+ ---------------------------------------------------------------------
15
+ A cargo rebuild has side effects and costs minutes. Every condition that
16
+ would make the answer meaningless is therefore checked BEFORE anything is
17
+ launched, and each one exits 2 (`BAD_CALL`, "fix the call") rather than 3,
18
+ for the reason `_refuse` states: nothing ran, so the reader's next move is a
19
+ different command. The five, in the order design 2026-09-07 section 2.3
20
+ fixes:
21
+
22
+ 1. `--window` -- rung 4 gives Rust LINE events under `--focus` and no
23
+ window gate at all. Accepting the flag and ignoring it would report a
24
+ narrowing that never happened.
25
+ 2. the invocation ran more than one process -- `cargo test` on a crate with
26
+ two test binaries produces two traces, and "which one is the re-run of
27
+ this trace" has no answer. A single-target selector is what makes it one.
28
+ 3. no `workspace_root` -- a trace from cargo-sensorium 0.4.0 or earlier. It
29
+ records no directory to re-run from, and guessing one is guessing.
30
+ 4. `workspace_root` gone -- the same fact the Python branch checks about
31
+ `cwd`, one level up.
32
+ 5. no driver -- there is nothing to re-run WITH.
33
+
34
+ The sentences carry no `REFUSED:` prefix of their own: `_refuse` prints
35
+ `error: cannot refocus <run>: <sentence>`, and two announcements of one
36
+ refusal read as two refusals. Everything after the design's prefix is
37
+ verbatim, `; nothing was re-run` included.
38
+
39
+ THE PAIR IS FOUND IN THE STORE, NEVER PARSED OUT OF THE DRIVER'S OUTPUT
40
+ -----------------------------------------------------------------------
41
+ The driver prints a `run:` line per process. Reading the new run id off it
42
+ would put a load-bearing link in this process's memory only, and a changed
43
+ print would break `refocus` silently (design 2026-09-07, G3: two approaches
44
+ were rejected for exactly this). Instead the driver stamps `refocus_of` into
45
+ every trace of the invocation, and `find_pair` asks the STORE which traces
46
+ carry it. The `run:` lines are printed back to the reader and decide
47
+ nothing.
48
+
49
+ The timestamp filter in `find_pair` is not belt-and-braces. The second
50
+ refocus of one original would otherwise find the FIRST one's trace as well
51
+ as its own, and "more than one" is a refusal -- so without the filter a
52
+ second refocus of any run fails permanently. `start_ts` is the process's own
53
+ CLOCK_REALTIME start (`convert/mod.rs`: `start_realtime_ns / 1e9`), the same
54
+ wall clock `time.time()` reads, so the comparison is between like and like.
55
+ A trace that records no `start_ts` is EXCLUDED rather than assumed recent:
56
+ it cannot be shown to be this re-run's.
57
+
58
+ Not every linked trace is a CANDIDATE, and that is the third filter (design
59
+ 2026-09-07 §3, ruling R2). A re-run whose test runs an instrumented program
60
+ spawns a second recorded process, and the driver stamps `refocus_of` on
61
+ every trace of the invocation, so the store holds two links where the
62
+ reader made one re-run. Counted as candidates they are "more than one",
63
+ which is a REFUSAL advising a single-target selector at a caller whose
64
+ selector was already single. A linked trace whose `ppid` is ANOTHER linked
65
+ trace's `pid` is therefore a child run: it is not the pair -- the pair is
66
+ the process the reader recorded and asked about -- but it is named on the
67
+ pair line, stamped into the pair's trace, and still listed by `runs`. A
68
+ child that is itself the interesting process is not lost, only unpaired:
69
+ `runs` names it and `refocus` can be asked about it directly.
70
+
71
+ NO TIMEOUT
72
+ ----------
73
+ Deliberate, and design 2026-09-07 section 2.3 says so: Python's `refocus`
74
+ has none, a cargo build's length is the user's to judge, and a timeout that
75
+ killed a rebuild half way would leave the store in exactly the state
76
+ ("no trace linked to this run") that this file reports as REFUSED. The
77
+ child's stderr is not captured, so a build that is slow is a build the
78
+ reader can watch.
79
+ """
80
+ import os
81
+ import sqlite3
82
+ import subprocess
83
+ import sys
84
+ import time
85
+ from pathlib import Path
86
+
87
+ from sensorium import paths, redact
88
+ from sensorium.driver import cargo_sensorium
89
+ from sensorium.exit import UNSETTLED
90
+ # The licence code this file used to own, at its shared home now that a
91
+ # third recorder needs it. Aliased to the private names its call sites
92
+ # already use: what moved is where the rule lives, not what this branch
93
+ # says. `_is_recorder_key` below is the one piece that did NOT move -- it
94
+ # names cargo's own variables, which is the only part of the environment
95
+ # check that is this language's.
96
+ from sensorium.query.refocus_world import (UNVERIFIABLE_KEY, _source_state,
97
+ env_of,
98
+ print_unverifiable as
99
+ _print_unverifiable,
100
+ relicense as _relicense,
101
+ stamp_unverifiable as
102
+ _stamp_unverifiable,
103
+ unverifiable_checks)
104
+ from sensorium.query.vocab import print_blind_spots
105
+ from sensorium.store import db
106
+ from sensorium.store.reader import Trace
107
+
108
+ #: The run ids the pair lookup put aside as this re-run's own child
109
+ #: processes. Beside the verdict rather than inside it: a child run is not
110
+ #: a finding about the comparison, it is a statement about which of the
111
+ #: invocation's traces the comparison is OF.
112
+ CHILDREN_KEY = "refocus_children"
113
+
114
+
115
+ def driver() -> str | None:
116
+ """The `cargo-sensorium` this re-run will use, or None.
117
+
118
+ One line, because the rule lives in `sensorium.driver` now: the driver a
119
+ corpus case records with and the driver a `refocus` question re-runs
120
+ with have to be the same binary, and they were the same binary only for
121
+ as long as three copies of a two-line rule stayed in step. The name
122
+ stays -- callers say `refocus_rust.driver()` -- and what it resolves is
123
+ no longer this module's to decide.
124
+ """
125
+ return cargo_sensorium()
126
+
127
+
128
+ # -- may this recording be re-run at all? ----------------------------------
129
+ def refusal(meta: dict, args, driver: str | None) -> str | None:
130
+ """Why re-running this Rust recording would be illegitimate, or None.
131
+
132
+ Order is the design's and is load-bearing in one direction: the cheap,
133
+ always-answerable questions come first, so a call that is wrong in two
134
+ ways is told about the one the reader can act on without a toolchain.
135
+ """
136
+ if getattr(args, "window", None) is not None:
137
+ return ("--window is not available for a Rust trace (rung 4 leaves "
138
+ "it out); nothing was re-run")
139
+ run = meta.get("run_id") or "this run"
140
+ n = meta.get("invocation_processes")
141
+ if n != 1:
142
+ # `n` absent is a trace from before the key existed. It is named as
143
+ # unrecorded rather than rendered as `None` or defaulted to a count:
144
+ # the refusal must not report a number nothing measured.
145
+ count = n if n is not None else "an unrecorded number of"
146
+ return (f"run {run} is one of {count} processes of its invocation "
147
+ "(test binaries and doctests); refocus needs an invocation "
148
+ "with a single-target selector (--lib, --test X, --bin X) "
149
+ "so one trace is the answer; nothing was re-run")
150
+ root = meta.get("workspace_root")
151
+ if not root:
152
+ return (f"run {run} records no workspace_root (recorded by "
153
+ "cargo-sensorium 0.4.0 or earlier); nothing was re-run")
154
+ if not os.path.isdir(root):
155
+ return f"workspace {root} no longer exists; nothing was re-run"
156
+ if not driver:
157
+ return ("no cargo-sensorium to re-run with -- set "
158
+ "SENSORIUM_CARGO_SENSORIUM or put cargo-sensorium on PATH; "
159
+ "nothing was re-run")
160
+ return None
161
+
162
+
163
+ # -- the re-run ------------------------------------------------------------
164
+ def rerun_argv(meta: dict, requested_focus, driver: str) -> list[str]:
165
+ """The driver invocation that re-records this run under more focus.
166
+
167
+ `--refocus-of` is what makes the new trace findable afterwards, so it is
168
+ first and unconditional. `--tier` is the ORIGINAL's, read from its
169
+ recorded environment: omitted when the key is absent, so the driver's
170
+ own default applies rather than this file asserting one. The focus list
171
+ is `refocus_cmd._merged_focus`'s -- the original's values then the
172
+ caller's, never fewer than the original's -- and reusing that function
173
+ is the point: "a refocus only ever captures more" must mean the same
174
+ thing in both languages. It also drops a value the caller re-typed,
175
+ which the driver's own set rule would have collapsed anyway.
176
+
177
+ `cargo_args` goes last and verbatim: it is cargo's argv, starting with
178
+ the subcommand, and the driver splits its own flags off the front (only
179
+ before the first bare `--`, so a test binary's arguments are safe).
180
+ """
181
+ from sensorium.query.refocus_cmd import _merged_focus
182
+
183
+ argv = [driver, "--refocus-of", meta.get("run_id") or ""]
184
+ tier = (meta.get("env") or {}).get("SENSORIUM_TIER")
185
+ if tier:
186
+ argv += ["--tier", str(tier)]
187
+ for value in _merged_focus(meta, requested_focus):
188
+ argv += ["--focus", value]
189
+ return argv + [str(a) for a in (meta.get("cargo_args") or [])]
190
+
191
+
192
+ def _process_id(value) -> int | None:
193
+ """A recorded `pid`/`ppid`, or None where there is nothing to match on.
194
+
195
+ `bool` is rejected before `int` because `True == 1` in Python, and a
196
+ recorder that wrote a flag where a process id belongs must not be read
197
+ as process 1. Everything else that is not an integer -- a string, a
198
+ float, a null -- is a process identity this reader did not understand.
199
+
200
+ None is NOT zero, and the distinction is the whole point: a trace that
201
+ records no pid is a trace of unknown parentage, which makes it neither
202
+ a parent nor a child. Defaulted to 0 instead, two such traces would
203
+ each be read as the other's child and the lookup would return no
204
+ candidate at all.
205
+ """
206
+ if isinstance(value, bool) or not isinstance(value, int):
207
+ return None
208
+ return value
209
+
210
+
211
+ def find_pair(traces_dir, run_id: str,
212
+ launched_at: float) -> tuple[list[str], list[str]]:
213
+ """(the candidates, the child runs) this re-run produced, in name order.
214
+
215
+ A trace is LINKED on two counts, and BOTH are necessary: it names
216
+ `run_id` in `refocus_of` (the driver stamped it, so the link is durable
217
+ and the same one `info` prints), and its own recording started at or
218
+ after `launched_at` (so an EARLIER refocus of the same original is not
219
+ mistaken for this one -- see the module docstring).
220
+
221
+ A linked trace is then a CHILD RUN when its `ppid` is another linked
222
+ trace's `pid`, and a candidate otherwise. `another` is load-bearing
223
+ twice: a trace whose recorder wrote its own pid into `ppid` is a corrupt
224
+ record of one process rather than a process that spawned itself, and a
225
+ `ppid` naming something outside this list -- the shell, cargo, the
226
+ session leader -- is every re-run's ordinary parentage and links
227
+ nothing. Both would otherwise empty the candidate list and refuse a
228
+ pair that is sitting in the store.
229
+ """
230
+ linked = []
231
+ for path in sorted(Path(traces_dir).glob("*.db")):
232
+ try:
233
+ conn = db.open_trace(path)
234
+ except (OSError, sqlite3.DatabaseError, db.TraceFormatError):
235
+ # A file this process cannot open is not a trace the driver
236
+ # just wrote. Skipped rather than reported: the answer this
237
+ # function owes is "which traces are linked", and a store may
238
+ # hold a half-written or newer-format file for its own reasons.
239
+ continue
240
+ try:
241
+ of = db.get_meta(conn, "refocus_of")
242
+ started = db.get_meta(conn, "start_ts")
243
+ pid = _process_id(db.get_meta(conn, "pid"))
244
+ ppid = _process_id(db.get_meta(conn, "ppid"))
245
+ finally:
246
+ conn.close()
247
+ if of != run_id:
248
+ continue
249
+ if not isinstance(started, (int, float)) or started < launched_at:
250
+ continue
251
+ linked.append((path.stem, pid, ppid))
252
+
253
+ # `pid is not None` keeps the unidentified traces OUT of the set, which
254
+ # is what makes `ppid in pids` safe for a trace that records no ppid: an
255
+ # unknown parent must not match an unknown pid.
256
+ pids = {pid for _, pid, _ in linked if pid is not None}
257
+ candidates, children = [], []
258
+ for name, pid, ppid in linked:
259
+ if ppid in pids and ppid != pid:
260
+ children.append(name)
261
+ else:
262
+ candidates.append(name)
263
+ return candidates, children
264
+
265
+
266
+ def children_note(children: list[str]) -> str:
267
+ """The clause that names what the pair lookup set aside, or "".
268
+
269
+ One sentence, used wherever the outcome of the lookup is announced --
270
+ beside the pair and beside the refusal -- because a reader told about
271
+ an excluded trace in two different wordings has to work out whether
272
+ they are the same fact.
273
+ """
274
+ if not children:
275
+ return ""
276
+ return "child runs excluded from the pair: " + ", ".join(children)
277
+
278
+
279
+ def _run_lines(stdout: str) -> list[str]:
280
+ """The driver's own `run:` lines, for the report and for nothing else."""
281
+ return [ln for ln in stdout.splitlines() if ln.startswith("run: ")]
282
+
283
+
284
+ def _launch(argv: list[str], root: str, store: Path) -> tuple[float, object]:
285
+ """Run the driver from the workspace root, under the original's store.
286
+
287
+ `SENSORIUM_DIR` is the resolved ABSOLUTE store of the original, for the
288
+ reason `refocus_cmd._pin_trace_store` states one level up: a relative
289
+ value would follow the child into the workspace and write the new trace
290
+ where `find_pair` -- and `sensorium runs` -- will never look. Nothing
291
+ else is set or stripped, so the environment the re-run executed under is
292
+ the caller's, and the two traces' own recorded environments are what the
293
+ licence check compares afterwards.
294
+
295
+ stderr is NOT captured: a focused rebuild takes minutes and its progress
296
+ belongs to the person waiting for it.
297
+ """
298
+ launched_at = time.time()
299
+ proc = subprocess.run(
300
+ argv, cwd=root, env={**os.environ, "SENSORIUM_DIR": str(store)},
301
+ stdout=subprocess.PIPE, stderr=None, text=True)
302
+ return launched_at, proc
303
+
304
+
305
+ # -- the assessment, with the checks that could not run --------------------
306
+ def _stamp_children(path: Path, children: list[str]) -> None:
307
+ """Write this re-run's own child runs into the pair's trace.
308
+
309
+ Stamped even when the list is empty, for `stamp_unverifiable`'s reason
310
+ one key over: `[]` says the child rule ran over this invocation and
311
+ found nothing to exclude, while an ABSENT key says the trace was
312
+ written before the rule existed. A key that only appears sometimes
313
+ cannot tell a later reader which of the two it is looking at.
314
+ """
315
+ conn = db.open_trace(path)
316
+ try:
317
+ db.set_meta(conn, CHILDREN_KEY, children)
318
+ conn.commit()
319
+ finally:
320
+ conn.close()
321
+
322
+
323
+ # -- the verdict paths -----------------------------------------------------
324
+ def _refused_after_rerun(orig: Trace, reason: str) -> int:
325
+ """A re-run that happened and produced no comparable pair.
326
+
327
+ Exit 3, not 2: the driver DID run, so no edit to the command settles
328
+ this -- the second of `refocus`'s two gates, exactly as `report` uses
329
+ it. `report` itself cannot be reached here, because it prints a
330
+ comparison and there is no second trace to compare.
331
+ """
332
+ print(f"refocus verdict: REFUSED -- {reason}")
333
+ # The trace is the ORIGINAL's: it is the only one there is on this path,
334
+ # and REFUSED is a verdict, so the block that bounds what a verdict
335
+ # claims has to print here too -- with this recorder's own lines, of
336
+ # which "the re-run's rebuild is its own cost" is the most relevant one
337
+ # a reader whose re-run produced nothing can be told.
338
+ print_blind_spots(orig)
339
+ return UNSETTLED
340
+
341
+
342
+ #: Every `SENSORIUM_` name `cargo-sensorium` itself puts into the recorded
343
+ #: process's environment, and no other. Read off the SET sites --
344
+ #: `launch.rs`'s eleven `.env("SENSORIUM_…", …)` calls, plus the one it sets
345
+ #: through a constant, `.env(sensorium_rt::redact::KEY_VAR, hex)`.
346
+ #: `tests/test_refocus_rust_recorder_keys.py` greps `launch.rs`, `runner.rs`
347
+ #: and `driver.rs` for that call shape and holds this set equal to what it
348
+ #: finds, in both directions: a variable the driver starts setting without a
349
+ #: line here would be compared on every focused re-run and withhold every
350
+ #: licence, and a name left here after the driver stopped setting it would
351
+ #: keep a variable of the PROGRAM out of the comparison.
352
+ #:
353
+ #: SET, never merely READ (R34, 2026-09-14). `SENSORIUM_INNER_RUNNER` was in
354
+ #: this set for a day because the first pin matched bare literals and
355
+ #: `runner.rs` reads one. Nothing here sets it: it names the runner program
356
+ #: the USER configured, which the runner chains by running it as the
357
+ #: executable, so a re-run under a different one ran the binary under a
358
+ #: different program. Reading a variable is the opposite of owning it.
359
+ RECORDER_KEYS = frozenset({
360
+ "SENSORIUM_FOCUS",
361
+ "SENSORIUM_INVOCATION",
362
+ "SENSORIUM_MAX_BYTES",
363
+ "SENSORIUM_MAX_CALLS",
364
+ "SENSORIUM_MAX_EVENTS",
365
+ "SENSORIUM_RT_DIR",
366
+ "SENSORIUM_SPOOL",
367
+ "SENSORIUM_TARGET",
368
+ "SENSORIUM_TIER",
369
+ "SENSORIUM_TOOL_HASH",
370
+ "SENSORIUM_WS",
371
+ redact.KEY_VAR,
372
+ })
373
+
374
+
375
+ def _is_recorder_key(name: str) -> bool:
376
+ """Whether this variable is the RECORDER's own bookkeeping.
377
+
378
+ The same judgement `_UNCOMPARED_ENV` makes about `SENSORIUM_DIR`, and
379
+ for the same measured reason -- reporting the tool's own footprint as a
380
+ change the world made is noise, not honesty. Here it is not optional:
381
+ a focused re-run changes `SENSORIUM_FOCUS` by definition, mints a new
382
+ `SENSORIUM_INVOCATION` and `SENSORIUM_SPOOL`, and -- because `--focus`
383
+ keys a fresh shim -- hands cargo different `RUSTC_WORKSPACE_WRAPPER`
384
+ and `CARGO_TARGET_<TRIPLE>_RUNNER` values. Compared, those fire on
385
+ EVERY Rust refocus, and a check that always fires says nothing.
386
+
387
+ A LIST AND NOT A PREFIX (E16 part A, H3, 2026-09-14)
388
+ ---------------------------------------------------
389
+ This was `name.startswith("SENSORIUM_")`, and the measurement is what
390
+ that cost. E16 planted `SENSORIUM_E16_TOKEN` in the recorded program's
391
+ environment and re-exported it to a fresh value between the recording
392
+ and the re-run. The Python pair reported the difference and WITHHELD
393
+ the licence, as pre-registered; the Rust pair granted it -- twice, in
394
+ both arms -- because the prefix had removed the name before `env_of`
395
+ compared anything. A rotated secret the licence could not see.
396
+
397
+ A prefix is a promise about names nobody has written yet, and the
398
+ namespace it claims is not the recorder's to claim: a user's program
399
+ reads whatever variables it likes, and several of ours invite the
400
+ shape (`SENSORIUM_E16_TOKEN` was pre-registered by this project's own
401
+ instrument and no reviewer noticed). So the driver's own variables are
402
+ a LIST, pinned to the sites that SET them, and everything else --
403
+ `SENSORIUM_NO_REDACT`, `SENSORIUM_REDACT_NAMES`,
404
+ `SENSORIUM_REDACT_ALLOW`, `SENSORIUM_CARGO_SENSORIUM`,
405
+ `SENSORIUM_INNER_RUNNER`, and any `SENSORIUM_`-shaped name a person
406
+ exports -- is the user's and is compared like any other variable. The
407
+ last two are variables this tool READS, which is not the same as owning
408
+ them: one names the driver binary a re-run uses and the other the runner
409
+ program the test binary is launched under, and a pair that differs in
410
+ either is a pair of two different tools.
411
+
412
+ `SENSORIUM_REDACT_KEY` is the one member of the set no Rust source
413
+ sets, and it stays: every recorder DELETES it from what it records
414
+ (`redact.env`), so a pair of current traces never holds it -- but a
415
+ trace converted before rule v1 existed does, and comparing it against a
416
+ re-run that does not would report the tool's own key as a change the
417
+ world made.
418
+
419
+ The two cargo-derived names are still SHAPES rather than list members:
420
+ `CARGO_TARGET_<TRIPLE>_RUNNER` carries the host triple, which is the
421
+ box's and not something a source file can be grepped for.
422
+
423
+ Not applied to the Python branch, and not added to `_UNCOMPARED_ENV`:
424
+ these are variables of a recorder Python's traces never carry. The
425
+ names are printed beside the count rather than hidden behind it, which
426
+ is the rule the shell list follows too.
427
+ """
428
+ return (name in RECORDER_KEYS
429
+ or name == "RUSTC_WORKSPACE_WRAPPER"
430
+ or (name.startswith("CARGO_TARGET_")
431
+ and name.endswith("_RUNNER")))
432
+
433
+
434
+ def _verify(args, orig: Trace, orig_name: str, meta: dict, new_id: str,
435
+ source_caveat, source_fact, children: list[str]) -> int:
436
+ """Compare the pair, assess it, stamp it, report it."""
437
+ from sensorium.query.refocus_cmd import (_stamp, assess, report)
438
+ from sensorium.query.diff_cmd import compare
439
+
440
+ new_path = (paths.traces_dir() / f"{new_id}.db").resolve()
441
+ new = Trace.open(new_path)
442
+ env_line, env_caveat, env_fact = env_of(meta, new, _is_recorder_key)
443
+ world_verified = [f for f in (source_fact, env_fact) if f]
444
+ res = compare(orig, new)
445
+ a = assess(orig, new, res,
446
+ [c for c in (source_caveat, env_caveat) if c], world_verified)
447
+ checks = unverifiable_checks(orig, new)
448
+ a = _relicense(a, orig, new, world_verified)
449
+ _stamp(new_path, res, a)
450
+ _stamp_unverifiable(new_path, checks)
451
+ _stamp_children(new_path, children)
452
+
453
+ print("--- verdict ---")
454
+ # The pair line, and the only place a reader is told that a trace of
455
+ # this invocation was set aside: which trace the verdict is about and
456
+ # which trace it is NOT about are one fact, so they are one line.
457
+ note = children_note(children)
458
+ print(f"run: {new_id}" + (f" {note}" if note else ""))
459
+ print(f"trace: {new_path}")
460
+ print(env_line)
461
+ print(f"exit: rerun {new.meta.get('exit_status', '?')} original "
462
+ f"{meta.get('exit_status', '?')}")
463
+ # `report` prints the blind-spot block, this recorder's own lines
464
+ # included (`vocab.blind_spots`); what follows it is the pair's own
465
+ # unrun checks, which are findings about THIS pair rather than about
466
+ # the recorder, and are stamped as well as printed.
467
+ code = report(orig, new, res, orig_name, new_id, a,
468
+ compact=bool(getattr(args, "compact", False)))
469
+ _print_unverifiable(checks)
470
+ return code
471
+
472
+
473
+ def run(args, orig: Trace, orig_name: str, meta: dict) -> int:
474
+ """The Rust branch of `sensorium refocus`, whole."""
475
+ from sensorium.query.refocus_cmd import _merged_focus, _refuse
476
+
477
+ drv = driver()
478
+ problem = refusal(meta, args, drv)
479
+ if problem:
480
+ return _refuse(orig_name, problem, orig)
481
+
482
+ # Resolved BEFORE the chdir below and before the child is launched, for
483
+ # `_pin_trace_store`'s reason: a relative SENSORIUM_DIR would resolve
484
+ # against the workspace, not against the directory this command was
485
+ # invoked from.
486
+ store = paths.trace_root().resolve()
487
+ traces = paths.traces_dir().resolve()
488
+ root = meta["workspace_root"]
489
+ run_id = meta.get("run_id") or orig_name
490
+ argv = rerun_argv(meta, args.focus, drv)
491
+
492
+ # The original's source digests are workspace-RELATIVE (the wrapper
493
+ # records `a/src/lib.rs`, never an absolute path), so they can only be
494
+ # re-hashed from the workspace root. Checked before the re-run, as the
495
+ # Python branch checks it: a source that has changed is worth knowing
496
+ # before spending a rebuild on it.
497
+ prev = os.getcwd()
498
+ os.chdir(root)
499
+ try:
500
+ source, source_caveat, source_fact = _source_state(meta)
501
+ finally:
502
+ os.chdir(prev)
503
+
504
+ print(f"refocus-of: {orig_name} cmd: {' '.join(argv)}")
505
+ print(f"cwd: {root}")
506
+ print(f"focus: {', '.join(_merged_focus(meta, args.focus))} window: -")
507
+ print(source)
508
+ print("--- rerunning (the driver's build output is above and below; the "
509
+ "lines below are its own) ---")
510
+ launched_at, proc = _launch(argv, root, store)
511
+ # Captured, then printed back: the design captures the child's stdout so
512
+ # the `run:` lines can be reported, and printing it afterwards means the
513
+ # program's own output is delayed, never withheld.
514
+ sys.stdout.write(proc.stdout or "")
515
+ for line in _run_lines(proc.stdout or ""):
516
+ print(f"driver reported: {line}")
517
+
518
+ ids, children = find_pair(traces, run_id, launched_at)
519
+ if not ids:
520
+ return _refused_after_rerun(
521
+ orig, f"the re-run produced no trace linked to {run_id} (driver "
522
+ f"exit {proc.returncode}); see the driver's output above")
523
+ if len(ids) > 1:
524
+ # The count and the ids are the CANDIDATES': they are what the
525
+ # reader has to choose between, and naming a child run among them
526
+ # would send someone after a selector for a process cargo never
527
+ # started. The excluded ids follow in the same sentence all the
528
+ # same, because "2 traces linked" would otherwise describe two of
529
+ # the three traces this re-run really wrote.
530
+ note = children_note(children)
531
+ return _refused_after_rerun(
532
+ orig, f"the re-run produced {len(ids)} traces linked to "
533
+ f"{run_id} ({', '.join(ids)}); refocus needs an invocation "
534
+ "with a single-target selector (--lib, --test X, --bin X) "
535
+ "so one trace is the answer" + (f"; {note}" if note else ""))
536
+ return _verify(args, orig, orig_name, meta, ids[0], source_caveat,
537
+ source_fact, children)