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,666 @@
1
+ """The world the two runs happened in, and what it lets the verdict claim.
2
+
3
+ Split out of `refocus_cmd` along the seam the material has: everything here
4
+ establishes FACTS -- about the source tree, the process environment, the
5
+ program's own output, the threads and children each run started -- and
6
+ nothing here decides a verdict or prints one. `refocus_cmd` owns the verdict
7
+ and the assessment that ties the facts to it; it calls in here for the
8
+ evidence. The two halves were one 1004-line file, over this project's
9
+ 800-line ceiling -- and `refocus_cmd` met that ceiling in its turn, so the
10
+ stamp and the report now live in `refocus_report`, which prints and stamps
11
+ and decides nothing.
12
+
13
+ A verdict is about CALL SHAPE. A licence is about the whole run, and it is
14
+ withheld on every signal below that fired -- and just as firmly on every one
15
+ that could not RUN, because the granted sentence claims they all agreed.
16
+ That asymmetry is the reason these checks are worth their length: each one
17
+ returns a caveat when it finds something AND a caveat when it could not
18
+ look, and only a third, positive answer when it actually verified something.
19
+
20
+ `_UNCOMPARED_ENV` is the one deliberate hole, and it is named rather than
21
+ counted for the same reason.
22
+ """
23
+ import hashlib
24
+ from pathlib import Path
25
+
26
+ from sensorium import paths, redact
27
+ from sensorium.query.caps import witness_gap
28
+ from sensorium.query.refocus_env import (HARNESS_DIFFER, HARNESS_SET,
29
+ SESSION_DIFFER, SESSION_SET,
30
+ RedactionPair, differs_only_by_root,
31
+ is_harness_key, is_session_key,
32
+ relocated_clause, relocation,
33
+ strip_recorder_fragment,
34
+ stripped_clause, uncomparable_clause)
35
+ # The positive half of the evidence -- the program's own captured
36
+ # output, and what a granted licence rests on -- split out at this
37
+ # file's 800-line ceiling. Re-exported on the same pattern and for the
38
+ # same reason as the two blocks below.
39
+ from sensorium.query.refocus_facts import ( # noqa: F401
40
+ _clip, _output_difference, _output_text, _spawn_witnessed,
41
+ _verified_facts)
42
+ # The licence code the Rust branch used to own, moved to a shared home when
43
+ # a third recorder needed it and split out at this file's 800-line ceiling.
44
+ # Re-exported on the same pattern and for the same reason as the block below.
45
+ from sensorium.query.refocus_licence import ( # noqa: F401
46
+ UNVERIFIABLE_KEY, env_of, print_unverifiable, relicense,
47
+ stamp_unverifiable)
48
+ # The thread bookkeeping, split out at this file's 800-line ceiling.
49
+ # Re-exported so `refocus_world.<name>` keeps resolving: these are one
50
+ # command's internals across its files, not separate modules with surfaces
51
+ # of their own. `refocus_cmd` re-exports two of them onward, from here.
52
+ from sensorium.query.refocus_threads import ( # noqa: F401
53
+ compared_threads, harness_exclusion, harness_note, harness_threads,
54
+ uncompared_threads)
55
+ from sensorium.store.reader import Trace
56
+
57
+ # A check that CANNOT RUN on this pair -- because the recorder declares it
58
+ # does not produce what the check reads, or because rule v1 redacted a value
59
+ # neither side can compare. Distinct from every other string in this file,
60
+ # and deliberately so: the caveats below are findings -- a signal that fired
61
+ # -- and these four are the absence of a signal to fire.
62
+ #
63
+ # The bug class they exist for is the one this whole file is arranged
64
+ # around, one step further on. `_output_difference` over two recordings that
65
+ # captured no output compares two EMPTY sets, finds them equal, and adds no
66
+ # caveat -- so a licence granted over a Rust pair silently claimed the
67
+ # observer-effect cross-check had passed, when it had never run. Naming the
68
+ # gap is the only honest answer; withholding the licence for it would be the
69
+ # opposite error, reporting a recorder's declared scope as evidence against
70
+ # the run.
71
+ #: The narrowest recorded source digest a comparison may rest on: 64 bits of
72
+ #: sha256, which is what `boot.hash_file` keeps. Anything shorter is reported
73
+ #: as unverifiable rather than compared.
74
+ _MIN_DIGEST = 16
75
+
76
+ UNVERIFIABLE_OUTPUT = "output: unverifiable (not recorded)"
77
+ UNVERIFIABLE_CHILDREN = "children: unverifiable (not witnessed)"
78
+ #: The third, and the one a THIRD recorder brought. `sensorium-ts` declares
79
+ #: `capabilities.threads: false` -- a vitest worker is a process, and the
80
+ #: recorder witnesses no thread of its own -- so the bookkeeping the licence
81
+ #: reads (`threads_started`, `live_threads`) was never written. Reported as
82
+ #: a witness GAP until this slice, which withholds; a check that could not
83
+ #: run is not a finding against the pair, so it says so and does not vote.
84
+ UNVERIFIABLE_THREADS = "threads: unverifiable (not witnessed)"
85
+ #: The fourth, and the first that is about a VALUE rather than a record: a
86
+ #: variable rule v1 redacted on one side and cannot compare on the other
87
+ #: (no key, or another store's key) was checked by nothing. Fixed text, with
88
+ #: the names on the env line and in the fact instead of in the marker --
89
+ #: `relicense` filters caveats by exact string, and a marker carrying names
90
+ #: would never match itself.
91
+ UNVERIFIABLE_ENV = ("env: unverifiable in part (redacted variables not "
92
+ "comparable)")
93
+ UNVERIFIABLE = (UNVERIFIABLE_OUTPUT, UNVERIFIABLE_CHILDREN,
94
+ UNVERIFIABLE_THREADS, UNVERIFIABLE_ENV)
95
+
96
+ #: The same four checks named for a line that has ALREADY said the word
97
+ #: "unverifiable" once -- `info`'s replay of the stamp. Each keeps its own
98
+ #: reason; only the repeated word goes. A name this table does not know is
99
+ #: printed exactly as it was stamped: an older reader must not rewrite the
100
+ #: words a later version wrote into a trace.
101
+ _SHORT_UNVERIFIABLE = {
102
+ UNVERIFIABLE_OUTPUT: "output (not recorded)",
103
+ UNVERIFIABLE_CHILDREN: "children (not witnessed)",
104
+ UNVERIFIABLE_THREADS: "threads (not witnessed)",
105
+ UNVERIFIABLE_ENV: "env (redacted, not comparable)",
106
+ }
107
+
108
+
109
+ def unverifiable_line(checks) -> str | None:
110
+ """`info`'s one line for the checks a pair could not run, or None.
111
+
112
+ None both for a trace that names no such check and for one that predates
113
+ the stamp: neither is "every check ran", and a line asserting that from
114
+ an absent key would be exactly the reading `unverifiable_checks` exists
115
+ to prevent, printed one command further on.
116
+ """
117
+ names = [_SHORT_UNVERIFIABLE.get(c, c) for c in checks or []]
118
+ if not names:
119
+ return None
120
+ return "licence unverifiable: " + ", ".join(names)
121
+
122
+
123
+ def unverifiable_checks(orig: Trace, new: Trace) -> list[str]:
124
+ """Which of the licence's checks this pair cannot run at all.
125
+
126
+ Keyed on the CAPABILITY, never on the language: what makes the check
127
+ impossible is the recorder's own declaration that it does not produce
128
+ the record, and that is the same fact whichever recorder said it. A
129
+ trace that declares the capability true, or that predates declarations
130
+ entirely, is not in this state -- for those the caveats below still
131
+ apply, because there the record's absence is a contradiction or an
132
+ unknown rather than a scope.
133
+ """
134
+ out = []
135
+ if any(t.declares("output") is False for t in (orig, new)):
136
+ out.append(UNVERIFIABLE_OUTPUT)
137
+ if any(t.declares("children") is False for t in (orig, new)):
138
+ out.append(UNVERIFIABLE_CHILDREN)
139
+ if any(t.declares("threads") is False for t in (orig, new)):
140
+ out.append(UNVERIFIABLE_THREADS)
141
+ # The fourth is keyed on the two METAS and not on a capability: what
142
+ # makes this check impossible is a digest with no key to read it by,
143
+ # which is a fact about the pair rather than about either recorder.
144
+ # INVARIANT: this reads the WHOLE recorded redaction table, while the
145
+ # names the env line prints are `_env_diff`'s keys MINUS
146
+ # `_UNCOMPARED_ENV` -- so a member of that list which fired rule v1
147
+ # would stamp this marker with no name anywhere for a reader to act on.
148
+ # None does, and `test_no_uncompared_variable_can_ever_fire_rule_v1`
149
+ # in `tests/test_refocus_redaction.py` is the guard that says so.
150
+ if redact.uncomparable(orig.meta, new.meta,
151
+ redact.Key.load(paths.trace_root()))[0]:
152
+ out.append(UNVERIFIABLE_ENV)
153
+ return out
154
+
155
+
156
+ # Shell bookkeeping that differs between any two consecutive commands and
157
+ # says nothing about the program. Deliberately tiny: every name here is a
158
+ # name refocus has stopped checking.
159
+ _UNCOMPARED_ENV = frozenset({
160
+ "_", # bash: the previous command's last argument
161
+ "OLDPWD",
162
+ "PWD", # os.chdir does not update it; it names the calling shell
163
+ "SHLVL",
164
+ # Not shell bookkeeping: the recorder's OWN variable, which
165
+ # `_pin_trace_store` rewrites from a relative path to the absolute form
166
+ # of the same directory before the target runs. The environment compared
167
+ # here is snapshotted AFTER that rewrite, so it is the environment the
168
+ # program actually executed under -- and this key is excluded rather
169
+ # than reported as a change the world made, because the change is ours.
170
+ # A program that reads SENSORIUM_DIR therefore goes unchecked, which is
171
+ # exactly why the name is printed rather than hidden behind a count.
172
+ "SENSORIUM_DIR",
173
+ })
174
+ # COLUMNS and LINES were on this list and are not any more. They are terminal
175
+ # geometry, which most shells do not export at all and which changes only on
176
+ # a resize -- so ignoring them bought almost nothing, and cost a real hole: a
177
+ # program that sizes its output by COLUMNS wrote 80 bytes in one run and 9000
178
+ # in the other under a full licence. Every name above is a name this tool has
179
+ # stopped checking, so the list stays as short as it can be, and the names
180
+ # themselves are printed beside the count rather than left as "5 keys".
181
+
182
+
183
+ # -- the world the rerun will run in ---------------------------------------
184
+ def _still_hashes_to(path: str, digest: str) -> bool:
185
+ """Whether `path`'s bytes still hash to the digest recorded for them.
186
+
187
+ Compared at the WIDTH the recorder wrote, and that is the whole reason
188
+ this is a function. Both recorders digest the same bytes with sha256 and
189
+ write DIFFERENT amounts of it: `boot.hash_file` keeps the first 16 hex
190
+ characters, `cargo-sensorium`'s wrapper writes all 64. A straight
191
+ inequality against `hash_file`'s answer therefore read every Rust file
192
+ as changed -- a false accusation of the most expensive kind, since it
193
+ withholds the licence AND tells the reader their source moved under
194
+ them. A prefix comparison is exact for each recorder, because a prefix
195
+ of a digest is a digest of the same bytes.
196
+
197
+ Unreadable now is NOT a match: a file that cannot be hashed has not been
198
+ shown to be unchanged, and the caller reports it among the changed. The
199
+ recorded digest's own width is the caller's business (`_MIN_DIGEST`):
200
+ every digest reaching here has already been shown wide enough to
201
+ identify a file.
202
+ """
203
+ try:
204
+ with open(path, "rb") as fh:
205
+ now = hashlib.sha256(fh.read()).hexdigest()
206
+ except OSError:
207
+ return False
208
+ return isinstance(digest, str) and now[:len(digest)] == digest
209
+
210
+
211
+ def _source_state(meta: dict) -> tuple[str, str | None, str | None]:
212
+ """(status line, caveat or None, verified fact or None), by CONTENTS.
213
+
214
+ Deliberately not `git_dirty_hash`. That hash covers the output of
215
+ `git status --porcelain` -- a list of paths and status letters -- so a
216
+ file already dirty when the original ran can be edited arbitrarily,
217
+ including the program being executed, without moving it. It would let
218
+ the tool print "source: unchanged" over a rerun of different code, which
219
+ is the one thing a licence gate must never do. Gitignored and
220
+ out-of-repo files are outside it too.
221
+
222
+ `source_hashes` is the digest of every file the ORIGINAL run interned
223
+ traced code from, plus its entry target, taken at record time. Comparing
224
+ those same paths' contents now is a claim the tool has actually
225
+ verified. What it does NOT cover: code that was never traced -- stdlib,
226
+ site-packages, anything the run's filters excluded -- and any file the
227
+ RERUN reaches that the original never touched.
228
+
229
+ A changed file is a WARNING, never a refusal: the fingerprint speaks to
230
+ the execution path, not to file bytes, so an edit that leaves the causal
231
+ stream untouched still earns an honest MATCH. What it costs is the right
232
+ to assume the *values* were the same.
233
+ """
234
+ was = meta.get("source_hashes")
235
+ if not isinstance(was, dict) or not was:
236
+ return ("source: unverifiable -- the original trace records no "
237
+ "source digests (recorded before they existed), so "
238
+ "sensorium cannot tell whether the code changed",
239
+ "the source could not be checked at all -- the original "
240
+ "trace holds no file digests -- so nothing rules out an "
241
+ "edit between the runs", None)
242
+ # A file the recorder could not read has a None digest. Comparing it
243
+ # against a None read now would make two failures agree and print
244
+ # "unchanged" over a file nobody has ever hashed -- the same shape as
245
+ # every other bug in this round: a check that did not run, reported as a
246
+ # check that passed.
247
+ # A digest too narrow to identify a file matches almost anything under a
248
+ # prefix comparison -- `""` matches EVERY file -- so it is reported as a
249
+ # check that could not run, never as one that passed. The floor is the
250
+ # narrowest width this project's own recorders write (`boot.hash_file`
251
+ # keeps 16 hex characters; `cargo-sensorium` writes all 64), so no trace
252
+ # either of them produced is refused by it.
253
+ short = sorted(p for p, digest in was.items()
254
+ if digest is not None
255
+ and (not isinstance(digest, str)
256
+ or len(digest) < _MIN_DIGEST))
257
+ if short:
258
+ names = ", ".join(Path(p).name for p in short[:6])
259
+ return (f"source: unverifiable -- {len(short)} of {len(was)} "
260
+ f"file(s) recorded a digest too short to identify their "
261
+ f"contents ({names})",
262
+ f"{len(short)} source file(s) could not be checked "
263
+ f"({names}) -- their recorded digest is under "
264
+ f"{_MIN_DIGEST} hex characters, which would match files "
265
+ "this run never saw, so nothing rules out an edit between "
266
+ "the runs", None)
267
+ unread = sorted(p for p, digest in was.items() if digest is None)
268
+ if unread:
269
+ names = ", ".join(Path(p).name for p in unread[:6])
270
+ return (f"source: unverifiable -- {len(unread)} of {len(was)} "
271
+ f"file(s) had no digest recorded ({names})",
272
+ f"{len(unread)} source file(s) could not be checked "
273
+ f"({names}) -- they were unreadable when the original was "
274
+ f"recorded, so nothing rules out an edit between the runs",
275
+ None)
276
+ changed = [p for p, digest in sorted(was.items())
277
+ if not _still_hashes_to(p, digest)]
278
+ if not changed:
279
+ return (f"source: unchanged ({len(was)} file(s) compared by "
280
+ "content; data files, untraced code and installed "
281
+ "dependencies are NOT covered -- see blind spots below)",
282
+ None,
283
+ f"{len(was)} source file(s) unchanged by content")
284
+ shown = ", ".join(Path(p).name for p in changed[:6])
285
+ if len(changed) > 6:
286
+ shown += f", +{len(changed) - 6} more"
287
+ return (f"source: CHANGED since the original run -- {len(changed)} of "
288
+ f"{len(was)} file(s) differ by content: {shown}",
289
+ f"{len(changed)} source file(s) CHANGED between the two runs "
290
+ f"({shown}), so the rerun executed different code than the "
291
+ f"recording did", None)
292
+
293
+
294
+ def _capped(names: list[str]) -> str:
295
+ """At most eight names, with the rest counted. A cap on what is
296
+ PRINTED; the count beside the list is always the whole of it."""
297
+ shown = ", ".join(names[:8])
298
+ return shown + (f", +{len(names) - 8} more" if len(names) > 8 else "")
299
+
300
+
301
+ def _by_name(key: str, session: list, harness: list, changed: list) -> None:
302
+ """Where a DIFFERENCE goes once relocation has been ruled out.
303
+
304
+ Session first, then harness, then the changed list that withholds. Both
305
+ sets are judgements about the NAME -- which shell a process was launched
306
+ from, which worker of a pool ran it -- so they hold for a value nobody
307
+ can read exactly as they hold for one anybody can (ruling R21). Written
308
+ once because the redacted branch and the plaintext branch must not be
309
+ able to answer this differently: `SSH_AUTH_SOCK` is in session set 1 AND
310
+ fires rule v1, so the two branches disagreeing would mean a re-run from
311
+ another terminal withholding on a trace made after the rule and granting
312
+ on one made before it. The two sets are disjoint, so their order between
313
+ themselves is documentation and decides nothing.
314
+ """
315
+ (session if is_session_key(key)
316
+ else harness if is_harness_key(key) else changed).append(key)
317
+
318
+
319
+ def _env_diff(was: dict, now: dict, redaction: RedactionPair | None = None
320
+ ) -> tuple[list[str], list[str], list[str], list[str],
321
+ list[str], list[str]]:
322
+ """(names that differ, names that differ ONLY by the target directory,
323
+ names the recorder's own fragment was stripped from, names that
324
+ identify the SESSION the re-run was launched from, names that identify
325
+ the harness SLOT it ran in, names rule v1 redacted that no comparison
326
+ could decide).
327
+
328
+ Names only -- values are never printed, because environments carry
329
+ secrets. Every split here is `refocus_env`'s rule and its whole reason:
330
+ a re-run under a fresh `CARGO_TARGET_DIR` differs on every variable
331
+ cargo derives from the root, and one of them also carries the driver's
332
+ own `--extern sensorium_rt=...` whose hash moves with every driver
333
+ build. Reporting the tool's own relocation, or the tool's own fragment,
334
+ as a change the world made is noise. Everything else stays a
335
+ difference.
336
+
337
+ Only the FIRST list withholds. The other four are findings the line
338
+ and the fact both carry by name -- and the sixth is a finding of a
339
+ different kind: a check that could not run, which is never a finding
340
+ against the pair (`UNVERIFIABLE_ENV`).
341
+
342
+ `redaction` is None for every pair in which neither side redacted
343
+ anything, which is every pair recorded before rule v1 existed; then the
344
+ sixth list is empty and every string below is byte for byte the one it
345
+ was.
346
+
347
+ Order per key: the fragment goes first, because what is compared is
348
+ what the world put there; then equality; then the relocation rule over
349
+ the REMAINDERS; then `_by_name`. A key can be stripped and
350
+ unchanged, stripped and relocated, or stripped and changed -- the strip
351
+ is a statement about what was removed, never a verdict. A key present
352
+ on ONE side only is a difference, as it always was, and is then
353
+ partitioned like any other: a re-run launched outside tmux carries no
354
+ `TMUX` at all, which is the same fact about the launcher as a `TMUX`
355
+ that differs.
356
+ """
357
+ keys = (set(was) | set(now)) - _UNCOMPARED_ENV
358
+ move = relocation(was, now)
359
+ changed, relocated, stripped, session, harness = [], [], [], [], []
360
+ uncomparable = []
361
+ for key in sorted(keys):
362
+ before, after = was.get(key), now.get(key)
363
+ # A name at least one side REDACTED is decided by `redact.compare`
364
+ # and by nothing else below: the value is a digest, so there is no
365
+ # fragment to strip from it, no root to reroot it at, and a set's
366
+ # membership says nothing about a value nobody can read. It differs
367
+ # or it does not or it cannot be told, and only the middle answer
368
+ # is silence. A difference is then partitioned BY NAME like any
369
+ # other (R21): the two sets are judgements about the name, and only
370
+ # relocation -- which has to rewrite a path to test itself -- needs
371
+ # a value to look at.
372
+ if redaction is not None and redaction.covers(key):
373
+ verdict = redaction.compare(key, before, after)
374
+ if verdict is None:
375
+ uncomparable.append(key)
376
+ elif not verdict:
377
+ _by_name(key, session, harness, changed)
378
+ continue
379
+ removed = 0
380
+ if isinstance(before, str):
381
+ before, n = strip_recorder_fragment(before)
382
+ removed += n
383
+ if isinstance(after, str):
384
+ after, n = strip_recorder_fragment(after)
385
+ removed += n
386
+ if removed:
387
+ stripped.append(key)
388
+ if before == after:
389
+ continue
390
+ # A key present on ONE side only reaches `differs_only_by_root` as
391
+ # a None and would raise; it is also not a relocation by any
392
+ # reading -- a variable that appeared or vanished is a change.
393
+ if (move and isinstance(before, str) and isinstance(after, str)
394
+ and differs_only_by_root(before, after, *move)):
395
+ relocated.append(key)
396
+ else:
397
+ _by_name(key, session, harness, changed)
398
+ return changed, relocated, stripped, session, harness, uncomparable
399
+
400
+
401
+ def _sets_clause(session: list[str], harness: list[str]) -> tuple[str, str]:
402
+ """(the `outside ...` phrase, the counted clauses) for the two sets that
403
+ never withhold.
404
+
405
+ ONE builder, for both sets and for both callers, because the phrase and
406
+ the clauses are two halves of one sentence: a line that says "outside
407
+ session set 1" and then counts harness names, or names a set nothing
408
+ counted, is a line whose two halves disagree about what was exempted.
409
+
410
+ Both are "" when neither set fired, which is every Python pair and every
411
+ Rust one -- so every string the callers build below is byte for byte the
412
+ one it was before harness set 1 existed.
413
+
414
+ Each set is counted EXACTLY and its members named, the way the changed
415
+ names are: an exemption whose size and members a reader cannot see is a
416
+ silent one, and each set is versioned in the sentence so it can be dated
417
+ and argued with. Session first wherever both appear, in the phrase and
418
+ in the clauses alike -- two channels carrying the same names in two
419
+ orders are two sentences to keep in step.
420
+
421
+ `told` carries its own leading separator, because it is appended to a
422
+ sentence that has already ended: the caller that wants the clauses
423
+ ALONE takes the prefix back off rather than a second builder spelling
424
+ the same join a second way.
425
+ """
426
+ parts = []
427
+ if session:
428
+ parts.append((f"session set {SESSION_SET}",
429
+ f"{len(session)}{SESSION_DIFFER}{_capped(session)}"))
430
+ if harness:
431
+ parts.append((f"harness set {HARNESS_SET}",
432
+ f"{len(harness)}{HARNESS_DIFFER}{_capped(harness)}"))
433
+ if not parts:
434
+ return "", ""
435
+ return (" outside " + " and ".join(name for name, _c in parts),
436
+ "".join(f"; {c}" for _name, c in parts))
437
+
438
+
439
+ def _env_state(meta: dict, env: dict,
440
+ now_meta: dict | None = None) -> tuple[str, str | None,
441
+ str | None]:
442
+ """(status line, caveat, verified fact) for the rerun's environment.
443
+
444
+ The ignored keys are NAMED, not counted. "4 volatile keys ignored" is
445
+ not something a reader can judge; `COLUMNS` sitting silently on that
446
+ list is how a program that sized its output by terminal width earned a
447
+ full licence while writing 80 bytes one run and 9000 the next.
448
+
449
+ `now_meta` is the re-run trace's own meta, or None when `env` is this
450
+ process's LIVE environment -- which is what the Python branch compares
451
+ against, because it performs the re-run itself. The difference is a
452
+ real one: a live side holds plaintext and is verified through the
453
+ store's key, a recorded side holds its own digests.
454
+ """
455
+ was = meta.get("env")
456
+ if not isinstance(was, dict):
457
+ return ("env: unverifiable -- the original trace records no "
458
+ "environment to compare against",
459
+ "the environment could not be checked at all, so nothing "
460
+ "rules out the rerun getting different input through it",
461
+ None)
462
+ key = redact.Key.load(paths.trace_root())
463
+ names, relocated, stripped, session, harness, unsure = _env_diff(
464
+ was, env, redaction=RedactionPair.of(meta, now_meta, key))
465
+ # Named on BOTH channels or on neither: the line a person reads and the
466
+ # fact the trace keeps have to agree about which keys the check
467
+ # explained away, or `info` replays a licence whose terminal said more.
468
+ # Empty when nothing fired, so every string below is byte for byte what
469
+ # it was -- which is every Python pair, since only `cargo sensorium`
470
+ # records a target root or writes the fragment at all. Two clauses join
471
+ # with the separator each already ends its own names with.
472
+ clause = "; ".join(c for c in (relocated_clause(relocated),
473
+ stripped_clause(stripped)) if c)
474
+ # The reason word is `redact.uncomparable`'s, read from the two metas
475
+ # rather than derived a second time here: one word for the whole list,
476
+ # and one function that decides which word it is.
477
+ reason = redact.uncomparable(meta, now_meta, key)[1] if unsure else None
478
+ tail = uncomparable_clause(unsure, reason, _capped(unsure))
479
+ tail = f"; {tail}" if tail else ""
480
+ on_line = (f" {clause}" if clause else "") + tail
481
+ on_fact = (f"; {clause}" if clause else "") + tail
482
+ # MINUS the uncomparable (R22): a line that says "12 variables compared"
483
+ # and then names one of them as not comparable has counted a check it
484
+ # did not run. Every uncomparable name came out of the same key set, so
485
+ # the subtraction cannot go negative, and it is a no-op on every pair
486
+ # recorded before rule v1 -- there the list is always empty.
487
+ compared = len((set(was) | set(env)) - _UNCOMPARED_ENV) - len(unsure)
488
+ ignored = ", ".join(sorted(_UNCOMPARED_ENV))
489
+ # Neither set withholds, so each is counted and named instead -- and the
490
+ # `outside ...` phrase says which of them the "unchanged" is qualified
491
+ # by, in the same words the count uses.
492
+ outside, told = _sets_clause(session, harness)
493
+ if not names:
494
+ if not outside:
495
+ return (f"env: unchanged ({compared} variables compared; not "
496
+ f"compared: {ignored}){on_line}", None,
497
+ f"{compared} environment variable(s) compared and "
498
+ f"unchanged in the environment the rerun executed under; "
499
+ f"not compared: {ignored}{on_fact}")
500
+ return (f"env: unchanged{outside} "
501
+ f"({compared} variables compared; not compared: {ignored}"
502
+ f"{told}){on_line}", None,
503
+ f"{compared} environment variable(s) compared and unchanged"
504
+ f"{outside} in the environment the "
505
+ f"rerun executed under; not compared: {ignored}{told}"
506
+ f"{on_fact}")
507
+ shown = _capped(names)
508
+ # The clauses are the FACT here, alone: this branch has no unchanged
509
+ # environment to vouch for, but the keys the rules explained are a
510
+ # finding it made and `assess` keeps them even when the licence is
511
+ # withheld. In the LINE's order -- the two sets first, then the two
512
+ # rules that explained keys away -- because two channels carrying the
513
+ # same names in two orders are two sentences to keep in step. `None`
514
+ # when no rule fired, exactly as before.
515
+ return (f"env: CHANGED since the original run -- {len(names)} "
516
+ f"variable(s) differ: {shown} (names only){told}{on_line}",
517
+ f"{len(names)} environment variable(s) differ between the two "
518
+ f"runs ({shown}); a program that reads them got different input",
519
+ "; ".join(c for c in (told[2:], clause, tail[2:]) if c) or None)
520
+
521
+
522
+ # -- everything else that bears on the licence -----------------------------
523
+ def _licence_caveats(orig: Trace, new: Trace) -> list[str]:
524
+ """Every reason this MATCH is not a statement about the whole run.
525
+
526
+ Each entry is a signal sensorium actually checked and found. Anything it
527
+ cannot check belongs in `_BLIND_SPOTS`, which is printed regardless.
528
+ """
529
+ out = []
530
+ # Decided once, up front: some of the checks below cannot run on this
531
+ # pair at all, and both the branch that would have run them and the
532
+ # branch that would have reported their absence as a finding have to
533
+ # read the same answer.
534
+ unverifiable = unverifiable_checks(orig, new)
535
+ for label, trace in (("the original", orig), ("the rerun", new)):
536
+ if trace.main_thread_basis() == "inferred":
537
+ out.append(f"{label}'s compared thread is INFERRED, not recorded "
538
+ "-- it may not be the thread you think it is")
539
+ threads = max(len(orig.fingerprints()), len(new.fingerprints()))
540
+ if not threads:
541
+ # Defence in depth: `compare()` refuses two empty streams before this
542
+ # is reached for a real recording. It stays because "no fingerprint
543
+ # was recorded" means the whole-thread comparison did not run, and a
544
+ # check that did not run can never support the licence.
545
+ out.append(
546
+ "no per-thread fingerprint was recorded on either side, so the "
547
+ "whole-thread comparison could not run at all")
548
+ elif threads > 1:
549
+ out.append(
550
+ f"{threads} threads were recorded; each thread's own call shape "
551
+ "matched, but the INTERLEAVING between them was never compared, "
552
+ "and interleaving is what most concurrency bugs are made of")
553
+ # A thread whose body is entirely stdlib runs no traced code, so it gets
554
+ # no fingerprint row -- and once joined it is gone from `live_threads`
555
+ # too, invisible on both counts while doing file I/O of its own. The
556
+ # audit hook counts thread CREATION, which is the only one of the three
557
+ # signals that is sound rather than "usually right".
558
+ for label, trace in (("the original", orig), ("the rerun", new)):
559
+ meta = trace.meta
560
+ # THIS side's declaration, never the pair's marker. All three
561
+ # clauses below are about a recorder that witnesses threads -- the
562
+ # gap sentence says a witness wrote no record, and the two counts
563
+ # read the record it wrote -- so a recorder that declares it
564
+ # witnesses none has nothing for any of them to be about, and
565
+ # saying so as a caveat would withhold the licence for the
566
+ # recorder's own declared scope. The marker reports that once for
567
+ # the pair, at the end.
568
+ #
569
+ # Read per SIDE because the pair's marker fires when EITHER side
570
+ # declares false: gated on that, a mixed pair would lose the
571
+ # WITNESSING side's `started`/`live_threads` findings -- real
572
+ # findings about a real record, dropped because the other trace
573
+ # came from another recorder.
574
+ if trace.declares("threads") is False:
575
+ continue
576
+ if "threads_started" not in meta or "live_threads" not in meta:
577
+ legacy = ("predates the thread bookkeeping this check reads, "
578
+ "so how many threads it ran cannot be established -- "
579
+ "absence of the record is not a record of absence")
580
+ gap = witness_gap(trace, "threads", "thread", legacy)
581
+ joiner = "'s" if trace.declares("threads") is not None else ""
582
+ out.append(f"{label}{joiner} {gap}")
583
+ continue
584
+ # The recorder's own harness threads come OUT of this count and are
585
+ # named in the same sentence (R1). `> 0` and not truthiness: a
586
+ # harness thread has a spool of its own, so the converter's count
587
+ # already includes it and the difference cannot go below zero on a
588
+ # trace this project wrote -- and a hand-built one that says
589
+ # otherwise gets no caveat rather than a negative count printed as
590
+ # though it had been measured.
591
+ harness, harness_clause = harness_exclusion(trace)
592
+ started = meta["threads_started"] - harness
593
+ if started > 0:
594
+ out.append(
595
+ f"{label} started {started} thread(s) besides the main "
596
+ f"one{harness_clause}. "
597
+ "A thread that ran no traced code has no fingerprint to "
598
+ "compare, and the order the threads ran in was never "
599
+ "compared for any of them")
600
+ live = meta["live_threads"]
601
+ if live:
602
+ out.append(
603
+ f"{label} still had {len(live)} thread(s) running when "
604
+ f"recording stopped ({', '.join(sorted(live)[:4])}); whatever "
605
+ "they did after that point is in neither trace")
606
+ if (orig.meta.get("audit_errors") or new.meta.get("audit_errors")):
607
+ out.append(
608
+ "the recorder's audit hook malfunctioned during one of the runs, "
609
+ "so its record of subprocesses and threads is incomplete -- a "
610
+ "short list there cannot be read as 'nothing was spawned'")
611
+ # NOT consulted when the pair declares no output capture. Two empty
612
+ # captures are equal, and this function returning None over them is the
613
+ # difference between "the cross-check passed" and "there was nothing to
614
+ # cross-check" -- reported instead as UNVERIFIABLE_OUTPUT below.
615
+ if UNVERIFIABLE_OUTPUT not in unverifiable:
616
+ diff = _output_difference(orig, new)
617
+ if diff:
618
+ out.append(diff)
619
+ was, now = orig.meta.get("exit_status"), new.meta.get("exit_status")
620
+ if was != now:
621
+ out.append(f"the two runs ended differently: exit {was} originally, "
622
+ f"exit {now} on the rerun")
623
+ for label, trace in (("the original", orig), ("the rerun", new)):
624
+ meta = trace.meta
625
+ # Two independent observations of the same thing, reported as ONE
626
+ # caveat. `subprocess.Popen` nests a spawn syscall, so a single list
627
+ # would count every subprocess twice; two lists that are never summed
628
+ # avoid that, and either being non-empty answers the only question
629
+ # asked here -- was a child witnessed. Neither being non-empty means
630
+ # only that none was NOTICED, never that none ran.
631
+ # The declared-false case is UNVERIFIABLE_CHILDREN, reported ONCE
632
+ # for the pair below rather than once per side: the marker names no
633
+ # side, and saying it twice would read as two findings.
634
+ if UNVERIFIABLE_CHILDREN not in unverifiable and (
635
+ "spawn_syscalls" not in meta):
636
+ legacy = ("predates the spawn-syscall record, so a child "
637
+ "started through multiprocessing or a bare "
638
+ "posix_spawn would leave no trace here -- absence of "
639
+ "the record is not a record of absence")
640
+ gap = witness_gap(trace, "children", "spawn-syscall", legacy)
641
+ joiner = "'s" if trace.declares("children") is not None else ""
642
+ out.append(f"{label}{joiner} {gap}")
643
+ kids = meta.get("children") or []
644
+ spawns = meta.get("spawn_syscalls") or 0
645
+ if kids or spawns:
646
+ named = (f"{len(kids)} named" if kids else "none named")
647
+ # python_children is absent on a trace recorded before child
648
+ # bodies were merged into the run. Those traces still did not
649
+ # witness what the child did, and the sentence stays that one.
650
+ if meta.get("python_children"):
651
+ witnessed = (
652
+ "Python children are in this run, linked to the frame "
653
+ "that spawned them; a non-Python child is counted and "
654
+ "not traced")
655
+ else:
656
+ witnessed = "sensorium does not witness what any child did"
657
+ out.append(
658
+ f"{label} started at least one child process ({named}, "
659
+ f"{spawns} low-level spawn syscall(s) seen); {witnessed}")
660
+ # Last, and reported here so that every reader of the licence caveats
661
+ # sees them. `refocus_rust` takes them back out of the WITHHOLDING
662
+ # decision -- a check that could not run is not a finding against the
663
+ # pair -- and prints and stamps them separately; a caller that reads
664
+ # this list and nothing else is still told which checks did not run.
665
+ out.extend(unverifiable)
666
+ return out