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,661 @@
1
+ """Re-run a recorded command with deeper capture, then verify -- via causal
2
+ fingerprints -- that the rerun really was the same execution.
3
+
4
+ The whole value of this command is that its verdict can be trusted. A false
5
+ MATCH would let someone draw conclusions about a run that never happened, so
6
+ every part of this file is arranged around refusing rather than guessing.
7
+
8
+ THREE SEPARATE THINGS, NEVER CONFLATED
9
+ ---------------------------------------
10
+ An earlier version of this command printed one verdict and one confident
11
+ sentence, and was wrong three ways at once: a rerun with a different
12
+ environment, a rerun where only a worker thread took another path, and a
13
+ rerun the recorder itself perturbed all came back MATCH with the full "answers
14
+ about the original run" licence. The root cause was a category error -- MATCH
15
+ is a statement about *call shape*, and the licence sentence is a statement
16
+ about *the whole run*. They are now three different things:
17
+
18
+ * **VERDICT** (MATCH / DIVERGED / REFUSED) is about causal shape, across
19
+ EVERY recorded thread AND every asyncio task. `diff_cmd.compare()` owns
20
+ the compared thread and pinpoints where it parted; `_thread_divergence`
21
+ widens that to the rest, because spec section 4 says refocus compares
22
+ per-thread fingerprints and a worker that took another path means the
23
+ rerun was a different execution. `_task_divergence` is the same argument
24
+ one level down: under the per-task basis the compared thread stream holds
25
+ only what ran outside every task, so a task that took another path leaves
26
+ it identical -- and `compare()` reports that as DIVERGED with no `index`,
27
+ because the difference is not a step of the stream those keys describe.
28
+ Task streams are matched by CONTENT, never by the order they interleaved
29
+ in, which is why an order flip is a MATCH and the ordering is named in the
30
+ blind spots rather than compared.
31
+ * **LICENCE** is withheld on *every* honesty signal this tool can check --
32
+ a source file's contents moved, the environment moved, the program's own
33
+ output differs, the two runs exited differently, threads were involved at
34
+ all or one was still running when recording stopped, the compared thread
35
+ is inferred rather than recorded, a subprocess ran unwitnessed. It is
36
+ withheld just as firmly when a check could not RUN, because the granted
37
+ sentence claims they all agreed. They are listed, not summarised.
38
+ * **BLIND SPOTS** are stated on every verdict -- MATCH, DIVERGED and
39
+ REFUSED alike, because "every verdict" has to include the verdict that
40
+ says nothing or the sentence is not true. See OBSERVER EFFECT below: the
41
+ biggest blind spot is structural.
42
+
43
+ A verdict over nothing is not a verdict. Two EMPTY causal streams compare
44
+ equal, so a target whose code was never traced at all -- resolved outside
45
+ the run's root, or filtered away by an inherited `--include`/`--exclude` --
46
+ used to produce a serene MATCH over zero events with the licence granted on
47
+ the line after "there was nothing to compare". `compare()` now refuses that
48
+ case at the seam, and `_licence_caveats` withholds on a zero-thread
49
+ comparison as well, because two independent things had to be wrong for it to
50
+ escape.
51
+
52
+ WHAT A MATCH LICENSES, AND WHAT IT DOES NOT
53
+ -------------------------------------------
54
+ MATCH means: every recorded thread -- and every asyncio task beside it --
55
+ produced the identical sequence of (file, qualname, kind) for
56
+ CALL/RETURN/RAISE/HANDLED. That is the *shape* of the execution and nothing
57
+ else. It does NOT say the arguments were the same, the return values were
58
+ the same, the timing was the same, the per-line state was the same, or that
59
+ the threads interleaved the same way -- or the tasks.
60
+
61
+ Deterministic replay is explicitly out of scope. For a program whose control
62
+ flow depends on state outside the process, DIVERGED is not a failure of this
63
+ command -- it is the correct and honest answer, and the new trace is still
64
+ recorded, still queryable, and permanently labelled.
65
+
66
+ TWO DIFFERENT QUESTIONS, TWO DIFFERENT GATES
67
+ --------------------------------------------
68
+ `_refusal` answers "may this program be re-run at all", and is checked BEFORE
69
+ anything executes -- re-running has side effects, so it is not something to
70
+ do speculatively. `diff_cmd.compare` answers "can a verdict be issued", and
71
+ is asked after the rerun. Keeping them apart is what makes the treatment of
72
+ the two damaged-trace shapes coherent rather than arbitrary:
73
+
74
+ * An INCOMPLETE original never got its finalize pass, so it never recorded
75
+ `stdin_consumed`. The stdin gate below would read that missing key as False
76
+ and wave through exactly the run it exists to stop. "We do not know whether
77
+ this run read stdin" is not "it did not" -- so the rerun is refused
78
+ outright, with no trace written.
79
+ * A finalized-but-lossy original (`late_writes > 0`) has trustworthy
80
+ metadata; only some events are missing. Re-running it is legitimate and
81
+ still buys a deeper trace, so it runs and the verdict comes back REFUSED.
82
+
83
+ REFUSED is a third verdict, never a synonym for either of the other two.
84
+
85
+ THE VERDICT LIVES IN THE TRACE, NOT JUST ON STDOUT
86
+ ---------------------------------------------------
87
+ `refocus_of` is written by the recorder at boot; the verdict is stamped here
88
+ the moment it is known. Both are read back by `sensorium info` and
89
+ `sensorium runs`, so a DIVERGED or REFUSED rerun can never later pass itself
90
+ off as a verified one just because the terminal has scrolled away.
91
+
92
+ WHAT IS AND IS NOT RESTORED
93
+ ----------------------------
94
+ The rerun uses the recorded `argv`, the recorded `cwd`, and the recorded
95
+ `include`/`exclude` filters -- the last of these because they gate the causal
96
+ stream itself, so a rerun that filtered differently would be compared against
97
+ a stream the original never had. `focus` and `window` are the only settings a
98
+ caller may change, and only ever to capture MORE, because they gate LINE
99
+ events alone.
100
+
101
+ The process ENVIRONMENT is deliberately NOT restored. Overwriting a live
102
+ process's environment resurrects whatever the original happened to carry -- a
103
+ `TMPDIR` that no longer exists, a stale `VIRTUAL_ENV`, the recorder's own
104
+ `SENSORIUM_DIR` -- and the target runs in-process, so the swap would hit the
105
+ recorder too. But not restoring it is no excuse for not LOOKING: both traces
106
+ store the full `env` dict, so `_env_state` diffs them and any non-volatile
107
+ difference withholds the licence. `_UNCOMPARED_ENV` exists only to drop the
108
+ handful of shell-bookkeeping keys that change between any two consecutive
109
+ commands; it is deliberately tiny, because every name on it is a name this
110
+ tool has stopped checking.
111
+
112
+ The SOURCE is checked by content, never by `git_dirty_hash` -- see
113
+ `_source_state`. That hash covers a list of paths, so a file that was
114
+ already dirty when the original ran can be rewritten wholesale without
115
+ moving it, and "source: unchanged" would have been a claim about nothing.
116
+
117
+ OBSERVER EFFECT -- A STRUCTURAL BLIND SPOT
118
+ -------------------------------------------
119
+ Deeper capture is not free: LINE events run `capture_value` on every local,
120
+ which calls the program's own `__repr__`. A `__repr__` with a side effect
121
+ (a counter, a log line, a lazy load) therefore behaves differently under
122
+ `--focus` than it did in the original recording.
123
+
124
+ This CANNOT be detected by the fingerprint, and any claim that it "shows up
125
+ as DIVERGED" is false. The recorder calls into the program from inside its
126
+ own hooks, where `tls.in_hook` is set, and `_on_start`/`_on_return` return
127
+ immediately while it is -- so every frame the instrument itself provokes is
128
+ suppressed from the trace by construction. The instrument's footprint is
129
+ invisible to the very hash that is supposed to prove nothing changed.
130
+
131
+ The one cross-check available is the program's own captured output, which
132
+ `_output_difference` compares and reports. It is a real signal (it catches
133
+ the counting-`__repr__` case) but it is not a proof: a side effect that
134
+ prints nothing leaves nothing to compare. So the blind spot is stated on
135
+ every verdict rather than papered over.
136
+
137
+ WHERE THE CODE IS
138
+ -----------------
139
+ This file owns the verdict and the assessment that ties the findings to it.
140
+ The FINDINGS themselves -- the source-tree check, the environment check, the
141
+ output comparison, the licence caveats and the verified facts -- live in
142
+ `refocus_world`, which decides nothing and prints nothing. What is SAID of
143
+ them -- the stamp, the `threads:` line and the report -- lives in
144
+ `refocus_report`, which prints and stamps and decides nothing. Every name
145
+ below that starts `_source_`, `_env_`, `_output_`, `_licence_` or `_verified_`
146
+ is imported from the first and `report` with its three helpers from the
147
+ second; both sets are re-exported here.
148
+ """
149
+ import os
150
+ import sys
151
+ from collections import Counter
152
+ from pathlib import Path
153
+
154
+ from sensorium import paths, redact
155
+ from sensorium.exit import BAD_CALL
156
+ from sensorium.query.caps import print_truncated, require
157
+ from sensorium.query.help import RUN_HELP
158
+ from sensorium.query.refocus_env import is_env_rule_note
159
+ from sensorium.query.vocab import terms
160
+ from sensorium.query.diff_cmd import compare
161
+ # The evidence layer, split out at this file's 800-line ceiling. Re-exported
162
+ # so `refocus_cmd.<name>` keeps resolving: these are one command's internals
163
+ # across its files, not separate modules with surfaces of their own.
164
+ from sensorium.query.refocus_world import ( # noqa: F401
165
+ _UNCOMPARED_ENV, _clip, _env_diff, _env_state, _licence_caveats,
166
+ _output_difference, _output_text, _source_state, _spawn_witnessed,
167
+ _verified_facts, harness_note, print_unverifiable, relicense,
168
+ stamp_unverifiable, uncompared_threads, unverifiable_checks)
169
+ # The reporting layer, split out at this file's 800-line ceiling. Re-exported
170
+ # so `refocus_cmd.<name>` keeps resolving: these are one command's internals
171
+ # across its files, not separate modules with surfaces of their own.
172
+ from sensorium.query.refocus_report import ( # noqa: F401
173
+ _diverged_why, _print_thread_line, _stamp, report)
174
+ from sensorium.store.reader import Trace
175
+
176
+ # The blind-spot block moved to `vocab.py` (fix round 1): four of its nine
177
+ # lines name a language, so the block belongs where the languages' words
178
+ # live. `print_blind_spots` carries the reasoning it was written with.
179
+
180
+
181
+ def add_parser(sub) -> None:
182
+ p = sub.add_parser(
183
+ "refocus",
184
+ help="re-run a recorded command with deeper capture, verified",
185
+ description="Executes the recorded command again with the added "
186
+ "`--focus` and reports whether it was the same "
187
+ "execution — MATCH, DIVERGED or REFUSED; the "
188
+ "licence names what was compared.",
189
+ epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
190
+ p.add_argument("run", help=RUN_HELP)
191
+ p.add_argument(
192
+ "--focus", action="append", default=[], required=True,
193
+ help="pkg.module or pkg.module:qualname; repeatable. Added to the "
194
+ "original run's focus, never replacing it.")
195
+ p.add_argument(
196
+ "--window", default=None,
197
+ help="qualname gate for LINE capture; defaults to the original's")
198
+ p.add_argument(
199
+ "--compact", action="store_true",
200
+ help="print the verdict and the concrete finding only, not the "
201
+ "licence catalogue, blind spots, or observer-effect note. "
202
+ "Off here; the MCP tool defaults it on.")
203
+ p.set_defaults(func=run)
204
+
205
+
206
+ # -- may this program be re-run at all? ------------------------------------
207
+ def _refusal_shared(meta: dict, trace: Trace | None = None) -> str | None:
208
+ """The two gates that hold for EVERY recorder, before the branch.
209
+
210
+ Split out so the Rust branch can be dispatched between these and the
211
+ ones below, which are Python's own (design 2026-09-07 section 2.3: the
212
+ Rust refusals come "after the existing capability/`incomplete`
213
+ checks"). Both questions here are about the RECORDING rather than about
214
+ the world the rerun would run in, and neither has a language in it:
215
+
216
+ * a recorder that declares it cannot be refocused is refusing the whole
217
+ command, not failing one of its checks -- asked anything else, such a
218
+ trace would report whichever other question it happens to fail;
219
+ * an incomplete recording never reached its finalize pass, so what it
220
+ does not hold may simply be what it never got to write, and no verdict
221
+ against it would mean anything. It is checked before `stdin_consumed`
222
+ below because an incomplete trace has no `stdin_consumed` key to
223
+ check -- see the module docstring.
224
+ """
225
+ if trace is not None:
226
+ declared = require(trace, "refocus", "refocus")
227
+ if declared:
228
+ return declared
229
+ if meta.get("incomplete"):
230
+ return ("original trace is INCOMPLETE -- recording ended without a "
231
+ "finalize pass, so it never recorded whether the run "
232
+ "consumed stdin, and its causal stream can stop anywhere "
233
+ "without saying so. Neither the rerun nor a verdict against "
234
+ "it would mean anything")
235
+ return None
236
+
237
+
238
+ def _refusal(meta: dict, trace: Trace | None = None) -> str | None:
239
+ """Why re-running this recorded command would be illegitimate.
240
+
241
+ The shared gates first, unchanged, so this function's contract and its
242
+ callers are what they were. Everything after them is PYTHON's: a Rust
243
+ trace never reaches this function (`run` dispatches above it), and its
244
+ equivalents are `refocus_rust.refusal`'s five sentences.
245
+
246
+ Order is load-bearing below too. The fingerprint-basis check comes
247
+ before the argv/cwd gates because those two ask whether the world still
248
+ allows a rerun, and this one asks whether any verdict against this trace
249
+ could mean anything. A trace whose directory is also gone is better told
250
+ the durable reason -- re-recording is the fix for both, and restoring the
251
+ directory is the fix for neither.
252
+
253
+ `trace` is optional only so the metadata-shaped refusals stay callable
254
+ from a bare dict; every real call site passes the opened trace.
255
+ """
256
+ shared = _refusal_shared(meta, trace)
257
+ if shared:
258
+ return shared
259
+ if meta.get("stdin_consumed"):
260
+ return ("original run consumed stdin -- marked non-refocusable: a "
261
+ "rerun reads different stdin, or none, so it could not be "
262
+ "the same execution and no verdict about it would be honest")
263
+ # A trace recorded before task fingerprints existed defines its thread
264
+ # stream to INCLUDE the events that ran inside asyncio tasks; this
265
+ # version defines it to exclude them and compares the tasks separately.
266
+ # Comparing across that seam would put every task event on one side
267
+ # only, so `diff` refuses it -- and refusing it here as well means the
268
+ # rerun, which has side effects, never happens for an answer that could
269
+ # not have been issued anyway.
270
+ tasks = trace.tasks() if trace is not None else []
271
+ if tasks and trace.fingerprint_basis == "per-thread":
272
+ return (f"original was recorded under the per-thread fingerprint "
273
+ f"basis and ran {len(tasks)} asyncio task(s); this version "
274
+ "compares tasks by content and defines thread streams "
275
+ "without them, so no verdict against it would compare like "
276
+ "with like -- re-record it with this version")
277
+ if not meta.get("argv"):
278
+ return "original trace records no command to re-run"
279
+ cwd = meta.get("cwd")
280
+ if not cwd:
281
+ return "original trace records no working directory to re-run from"
282
+ if not os.path.isdir(cwd):
283
+ return (f"original working directory {cwd} no longer exists -- the "
284
+ "rerun could not start where the original did")
285
+ return None
286
+
287
+
288
+ def _refuse(orig_name: str, problem: str, trace: Trace) -> int:
289
+ """The refusal, and what may be done instead -- in the words of the
290
+ trace that was refused. `sensorium run --focus ...` cannot read a Rust
291
+ recording, so offering it there sends the reader to a second refusal;
292
+ the trace is required rather than defaulted, so no call site can reach
293
+ this line without saying which language it is speaking."""
294
+ print(f"error: cannot refocus {orig_name}: {problem}", file=sys.stderr)
295
+ print(terms(trace).no_rerun_note, file=sys.stderr)
296
+ # 2, not 3, and the two gates of this command differ here (X4). Nothing
297
+ # was re-run: the reader's next move is a different command -- another
298
+ # run to refocus, a `--focus` that resolves, `sensorium run --focus`
299
+ # instead. `report()` below is the other gate: there the rerun HAPPENED
300
+ # and could not be verified, and only a new recording settles that.
301
+ return BAD_CALL
302
+
303
+
304
+ # -- run settings ----------------------------------------------------------
305
+ def _merged_focus(meta: dict, requested) -> list[str]:
306
+ """The original's focus plus what was asked for.
307
+
308
+ A refocus only ever captures MORE: dropping the original's focus would
309
+ make the new trace shallower than the one it is meant to explain.
310
+ Widening it cannot move the verdict, because focus (and window) gate
311
+ only LINE events, which are never fingerprinted and never enter a
312
+ causal stream. `include`/`exclude` are a different matter entirely --
313
+ they gate the causal stream itself, so they are inherited verbatim and
314
+ are deliberately not overridable here.
315
+ """
316
+ focus = list(meta.get("focus") or [])
317
+ for entry in requested:
318
+ if entry not in focus:
319
+ focus.append(entry)
320
+ return focus
321
+
322
+
323
+ def _pin_trace_store() -> None:
324
+ """Keep the rerun in the store the original came from.
325
+
326
+ A relative SENSORIUM_DIR would follow the chdir into the original cwd
327
+ and silently write the new trace somewhere `sensorium runs` will never
328
+ look for it. Two orderings matter, and both are asserted by `run()`:
329
+
330
+ * BEFORE the chdir -- the path is relative to the invoking directory,
331
+ not to the target's.
332
+ * BEFORE the environment snapshot the licence check compares. The
333
+ snapshot must be of the environment the target actually EXECUTES
334
+ under, and this rewrite mutates that environment. Snapshotting first
335
+ left the check describing an environment the program never saw: a run
336
+ recorded with SENSORIUM_DIR=sdir wrote into `sdir`, the rerun wrote
337
+ into `/tmp/.../sdir`, and the output said `env: unchanged (76
338
+ variables compared)` and granted the full licence.
339
+
340
+ Reporting the tool's own bookkeeping as an environment change the user
341
+ should worry about would be noise, not honesty -- so SENSORIUM_DIR is in
342
+ `_UNCOMPARED_ENV` instead, where it is NAMED rather than hidden, and a
343
+ program that reads it goes explicitly unchecked.
344
+ """
345
+ sdir = os.environ.get("SENSORIUM_DIR")
346
+ if sdir and not os.path.isabs(sdir):
347
+ os.environ["SENSORIUM_DIR"] = str(Path(sdir).resolve())
348
+
349
+
350
+ # -- the whole-run verdict -------------------------------------------------
351
+ def _thread_shapes(trace: Trace) -> Counter:
352
+ """The multiset of per-thread causal fingerprints.
353
+
354
+ A multiset, not a mapping: thread IDs are OS handles and never repeat
355
+ across processes, so the two runs' threads cannot be paired by identity.
356
+ Two threads doing identical work share a hash and are counted twice,
357
+ which is the correct comparison -- "the same shapes ran, the same number
358
+ of times".
359
+ """
360
+ return Counter(h for h, _n in trace.fingerprints().values())
361
+
362
+
363
+ def _thread_scope(orig: Trace, new: Trace) -> str:
364
+ """What the compared thread rows cover, when it is not everything.
365
+
366
+ Under the per-task basis a thread's fingerprint covers only the events
367
+ that ran in NO task -- so a thread whose traced code all ran inside one
368
+ has a row of its own with zero events, and "2 recorded fingerprint(s)
369
+ compared" would otherwise invite the reader to think those rows account
370
+ for the whole run. The tasks are compared too, on the line below; this
371
+ says where the boundary between the two is.
372
+
373
+ WHAT a task is here is the recorder's word, not this function's. On a
374
+ Rust trace every non-main thread's stream is a `task_fingerprints` row
375
+ (`convert/frames.rs`), so the thread row holds the main thread's own
376
+ events and the boundary is the test and spawned threads -- and this
377
+ line said `asyncio` about it until the fixture carried the task rows
378
+ the converter really writes and the sentence became readable. `info`
379
+ reads the same table for the same gate (`info_cmd`'s
380
+ "the two commands must not describe one trace differently"), so both
381
+ take the noun from `Terms`.
382
+
383
+ Empty when neither run recorded a task: nothing was excluded, and a
384
+ parenthetical about a distinction that made no difference is noise.
385
+ """
386
+ if any(t.fingerprint_basis == "per-task" and t.tasks()
387
+ for t in (orig, new)):
388
+ return f" (events outside any {terms(new).task_noun})"
389
+ return ""
390
+
391
+
392
+ def _thread_divergence(orig: Trace, new: Trace) -> str | None:
393
+ """How the two runs' per-thread shapes differ, or None if they do not."""
394
+ a, b = _thread_shapes(orig), _thread_shapes(new)
395
+ if a == b:
396
+ return None
397
+ only_a = sorted(h[:12] for h in (a - b).elements())
398
+ only_b = sorted(h[:12] for h in (b - a).elements())
399
+ return (f"{sum(a.values())} thread(s) recorded originally, "
400
+ f"{sum(b.values())} on the rerun; fingerprints only in the "
401
+ f"original: {', '.join(only_a) or '-'}; only in the rerun: "
402
+ f"{', '.join(only_b) or '-'}")
403
+
404
+
405
+ def _task_divergence(res: dict) -> str | None:
406
+ """How the two runs' asyncio task streams differ, in one line, or None.
407
+
408
+ `compare_tasks()` did the comparing -- by CONTENT, as a multiset of
409
+ (name, hash), so a different interleaving is not a difference here and
410
+ the blind-spot block says so. This only phrases the finding for the
411
+ refocus verdict; refocus prints `diff`'s task section with `tasks=False`
412
+ and adds the drill-in commands itself beside this line (D1 of the final
413
+ wave), so the finding is stated exactly once.
414
+
415
+ The hashes are part of the sentence, not decoration: this string is
416
+ stamped into the trace as `refocus_diverge_tasks` and read back by
417
+ `info`, where diff's section is not printed above it -- and "only in A:
418
+ task-B; only in B: task-B" without them says two different things
419
+ happened under one name while looking like a contradiction.
420
+ """
421
+ t = res.get("tasks")
422
+ if not t or t["verdict"] != "DIVERGED":
423
+ return None
424
+
425
+ def fmt(rows):
426
+ return ", ".join(f"{n if n is not None else '(unnamed)'} {h[:12]}"
427
+ + ("" if k == 1 else f" x{k}") for n, h, k in rows
428
+ ) or "-"
429
+ s = (f"{t['n_a']} task stream(s) originally, {t['n_b']} on the rerun; "
430
+ f"only in A: {fmt(t['only_a'])}; only in B: {fmt(t['only_b'])}")
431
+ p = t["pair"]
432
+ if p:
433
+ # A pair with no name on either side was matched by creation order,
434
+ # which is a guide to look at and not a claim that the two are the
435
+ # same task. Saying "first difference inside (unnamed)" without that
436
+ # qualification would assert an identity nothing established.
437
+ guide = (" (paired by creation order -- a guide, not a match)"
438
+ if p["by_order"] else "")
439
+ s += (f"; first difference inside {p['name'] or '(unnamed)'}"
440
+ f"{guide} at causal step {p['index']}: A {p['a_desc']} / "
441
+ f"B {p['b_desc']}")
442
+ return s
443
+
444
+
445
+ def final_verdict(orig: Trace, new: Trace,
446
+ res: dict) -> tuple[str, str | None, str | None]:
447
+ """(verdict, thread-divergence description or None, task-divergence
448
+ description or None).
449
+
450
+ `compare()` decides on one thread and says exactly where it parted.
451
+ This widens the answer to every recorded thread, because a worker that
452
+ took a different path means the rerun was a different execution -- and
453
+ reporting that as MATCH-with-a-note is how the previous version handed
454
+ out a licence next to the words "this MATCH is about the worker".
455
+
456
+ The tasks are the same argument one level down. Under the per-task basis
457
+ the compared thread stream is only what ran OUTSIDE every asyncio task,
458
+ so a rerun whose task took another path can leave that stream identical:
459
+ `compare()` reports DIVERGED with `index` None for exactly this case,
460
+ and a verdict that read only `index` would call it a MATCH.
461
+ """
462
+ if res["verdict"] == "REFUSED":
463
+ return res["verdict"], None, None
464
+ threads = _thread_divergence(orig, new)
465
+ tasks = _task_divergence(res)
466
+ if res["verdict"] == "DIVERGED" and res.get("index") is not None:
467
+ # The compared thread itself parted; `print_comparison` has already
468
+ # pinpointed where, and the thread-shape multiset cannot add to it.
469
+ return "DIVERGED", None, tasks
470
+ # ADDITIVE, never subtractive: `compare()`'s DIVERGED stands whatever
471
+ # this function finds. Today a DIVERGED with no `index` always carries a
472
+ # task divergence, so the two agree -- but that is an invariant of
473
+ # another module which nothing here asserts, and reading only `threads
474
+ # or tasks` would turn a disagreement into a MATCH with the licence
475
+ # granted on top of it. The verdict may only ever be widened.
476
+ return ("DIVERGED" if (res["verdict"] == "DIVERGED" or threads or tasks)
477
+ else "MATCH"), threads, tasks
478
+
479
+
480
+ # -- the assessment --------------------------------------------------------
481
+ def assess(orig: Trace, new: Trace, res: dict, world_caveats=(),
482
+ world_verified=()) -> dict:
483
+ """Everything the two traces support, decided once.
484
+
485
+ `world_caveats` and `world_verified` are findings about the world outside
486
+ the traces (the source files, the environment) that only the caller can
487
+ establish; everything else is derived here. Computed in one place because
488
+ the verdict is printed, stamped into the new trace, and turned into an
489
+ exit code -- and those three must never be able to disagree.
490
+ """
491
+ verdict, threads, task_divergence = final_verdict(orig, new, res)
492
+ # Computed ONCE and passed down: `_verified_facts` needs the same answer
493
+ # this dict carries, and two calls to the same derivation are two places
494
+ # for it to come out differently.
495
+ scope = _thread_scope(orig, new)
496
+ world = list(world_caveats)
497
+ caveats = ((world + _licence_caveats(orig, new))
498
+ if verdict == "MATCH" else [])
499
+ licence = None
500
+ verified = []
501
+ if verdict == "MATCH":
502
+ licence = "withheld" if caveats else "granted"
503
+ if not caveats:
504
+ facts = _verified_facts(orig, new, scope)
505
+ verified = facts[:1] + list(world_verified) + facts[1:]
506
+ else:
507
+ # A withheld licence rests on nothing, so it lists nothing --
508
+ # with one exception, and it is an exception about NAMES rather
509
+ # than about standing. A world-fact that says which variables
510
+ # differed only because the tool re-ran the program somewhere
511
+ # else is printed on the env line either way, and a trace that
512
+ # kept only the accusation replayed less than its own screen
513
+ # had said. Empty for every pair that relocated nothing, which
514
+ # is every pair before this rule existed.
515
+ verified = [f for f in world_verified if is_env_rule_note(f)]
516
+ # Everything the report and the stamp need, derived ONCE. `report` used
517
+ # to reach back into `res` for `index` and `tasks` beside this dict,
518
+ # which is two sources for one verdict -- the exact shape that let the
519
+ # printed line, the stamped label and the exit code disagree before.
520
+ return {"verdict": verdict, "threads": threads,
521
+ "task_divergence": task_divergence,
522
+ "tasks": res.get("tasks"),
523
+ "thread_stream_parted": (res["verdict"] == "DIVERGED"
524
+ and res["index"] is not None),
525
+ "thread_scope": scope,
526
+ "world": world, "caveats": caveats, "licence": licence,
527
+ "verified": verified}
528
+
529
+
530
+ # -- driving ---------------------------------------------------------------
531
+ def _rerun_and_verify(args, orig: Trace, orig_name: str, meta: dict,
532
+ env: dict) -> int:
533
+ from sensorium.record import boot
534
+
535
+ argv = list(meta["argv"])
536
+ try:
537
+ boot.resolve_target(argv) # refuse before announcing a rerun
538
+ except boot.TargetError as e:
539
+ return _refuse(orig_name, str(e), orig)
540
+
541
+ focus = _merged_focus(meta, args.focus)
542
+ window = args.window if args.window is not None else meta.get("window")
543
+ source, source_caveat, source_fact = _source_state(meta)
544
+ # `now_meta=None`: `env` is this process's LIVE environment, in
545
+ # plaintext, because this branch performs the re-run itself. A redacted
546
+ # variable is therefore compared by hashing the live value under the
547
+ # store's key -- never by redacting the live side, which would grant a
548
+ # licence over a secret that really had changed.
549
+ env_line, env_caveat, env_fact = _env_state(meta, env, now_meta=None)
550
+
551
+ print(f"refocus-of: {orig_name} cmd: {' '.join(argv)}")
552
+ print(f"cwd: {os.getcwd()}")
553
+ print(f"focus: {', '.join(focus)} window: {window or '-'}")
554
+ print(source)
555
+ print(env_line)
556
+ print("--- rerunning (the lines below are the program's own output) ---")
557
+
558
+ new_id, status = boot.run_target(
559
+ argv, focus=focus, include=meta.get("include") or (),
560
+ exclude=meta.get("exclude") or (), window=window,
561
+ refocus_of=meta.get("run_id", orig_name),
562
+ record_children=bool(meta.get("record_children", True)))
563
+
564
+ new_path = (paths.traces_dir() / f"{new_id}.db").resolve()
565
+ new = Trace.open(new_path)
566
+ res = compare(orig, new)
567
+ world_verified = [f for f in (source_fact, env_fact) if f]
568
+ a = assess(orig, new, res,
569
+ [c for c in (source_caveat, env_caveat) if c], world_verified)
570
+ # The same two hands the Rust and TypeScript branches use, in the same
571
+ # order (ruling R19). This branch had neither, so a check that COULD
572
+ # NOT RUN -- a redacted variable with no key to read it by -- withheld
573
+ # the licence here while the same marker was reported and set aside on
574
+ # the other two. `relicense` takes the markers' vote and nothing else's,
575
+ # so a redacted variable that really differs still withholds; and the
576
+ # stamp is written even when the list is empty, so `info` on any Python
577
+ # re-run says which checks the verdict does not rest on rather than
578
+ # leaving a reader to infer it from an absent key.
579
+ checks = unverifiable_checks(orig, new)
580
+ a = relicense(a, orig, new, world_verified)
581
+ _stamp(new_path, res, a)
582
+ stamp_unverifiable(new_path, checks)
583
+
584
+ print("--- verdict ---")
585
+ print(f"run: {new_id}")
586
+ print(f"trace: {new_path}")
587
+ print(f"exit: rerun {status} original {meta.get('exit_status', '?')}")
588
+ # `report` prints the blind-spot block; what follows it is this pair's
589
+ # own unrun checks, printed where the other two branches print them so
590
+ # that a reader of a Python re-run is told what a reader of a Rust one
591
+ # is told (R19). Stamped as well as printed, above.
592
+ code = report(orig, new, res, orig_name, new_id, a,
593
+ compact=bool(getattr(args, "compact", False)))
594
+ print_unverifiable(checks)
595
+ return code
596
+
597
+
598
+ def run(args) -> int:
599
+ orig_path = paths.find_trace(args.run).resolve()
600
+ orig_name = orig_path.stem
601
+ orig = Trace.open(orig_path)
602
+ print_truncated(orig)
603
+ meta = orig.meta
604
+
605
+ # The capability gate and `incomplete` come FIRST and are shared: a
606
+ # recorder that declares it cannot be refocused, or a recording that
607
+ # never finalized, is refused in the same words whatever wrote it.
608
+ problem = _refusal_shared(meta, orig)
609
+ if problem:
610
+ return _refuse(orig_name, problem, orig)
611
+
612
+ # Then the branch, BEFORE Python's own gates. A Rust recording cannot be
613
+ # re-run in this process (design 2026-09-07 section 2.3): the branch
614
+ # below re-invokes the driver instead, and calls back into this file for
615
+ # the comparator, the verdict, the assessment, the report and the
616
+ # stamps. It is dispatched here rather than after `_refusal` so that the
617
+ # five sentences a Rust user meets arrive in the order the design fixes
618
+ # -- `--window` first -- instead of behind a Python gate (`argv`, `cwd`,
619
+ # the per-thread basis) whose sentence names a fact about the Python
620
+ # recorder. Imported here rather than at the top because that module
621
+ # imports this one.
622
+ if orig.lang == "rust":
623
+ from sensorium.query import refocus_rust
624
+ return refocus_rust.run(args, orig, orig_name, meta)
625
+ # The third recorder, on the same seam and for the same reason. A
626
+ # TypeScript recording is one CONTAINER of a harness invocation, and
627
+ # what its branch re-runs is the whole invocation -- so which trace of
628
+ # the re-run is the pair is a question neither of the other two
629
+ # branches has, and the seven sentences a TypeScript user meets arrive
630
+ # in the order design 2026-09-13 section 2.3 fixes.
631
+ if orig.lang == "typescript":
632
+ from sensorium.query import refocus_typescript
633
+ return refocus_typescript.run(args, orig, orig_name, meta)
634
+
635
+ problem = _refusal(meta, orig)
636
+ if problem:
637
+ return _refuse(orig_name, problem, orig)
638
+
639
+ # Pin first, THEN snapshot: the environment compared must be the one the
640
+ # target is executed with, not the one this process started with. The pin
641
+ # rewrites SENSORIUM_DIR, which is why that key is in _UNCOMPARED_ENV and
642
+ # named in the output -- snapshotting before the pin instead left the
643
+ # check describing an environment the program never saw.
644
+ _pin_trace_store()
645
+ env = dict(os.environ)
646
+ # Every recorder DELETES this from what it records (`redact.env`): a
647
+ # digest of the key under the key is a pointless row, and a driver that
648
+ # hands the key down leaves it set in the process this command runs in.
649
+ # Compared as it arrives it is a variable that appeared out of nowhere,
650
+ # and the licence would be withheld over the tool's own plumbing. It is
651
+ # popped HERE rather than added to `_UNCOMPARED_ENV`, whose printed
652
+ # `not compared:` list is a pinned sentence about the SHELL's
653
+ # bookkeeping -- this name was never in the recorded environment to be
654
+ # compared in the first place.
655
+ env.pop(redact.KEY_VAR, None)
656
+ prev_cwd = os.getcwd()
657
+ os.chdir(meta["cwd"])
658
+ try:
659
+ return _rerun_and_verify(args, orig, orig_name, meta, env)
660
+ finally:
661
+ os.chdir(prev_cwd)