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,493 @@
1
+ """A target directory that MOVED, a fragment the RECORDER wrote, and the
2
+ session a re-run was LAUNCHED from -- each told apart from a world that
3
+ changed.
4
+
5
+ Split out of `refocus_world` rather than added to it: the licence's
6
+ environment clause now has a rule of its own, and `refocus_world` is the
7
+ file that was already nearest this project's 800-line ceiling.
8
+
9
+ WHY THIS RULE EXISTS
10
+ --------------------
11
+ `refocus` re-runs the program, and a re-run happens under whatever
12
+ `CARGO_TARGET_DIR` the caller gives it -- E4' gives it a fresh one on
13
+ purpose, because the kept store is never written and the re-run must build
14
+ somewhere else. Cargo then hands the test binary four variables that embed
15
+ the target root, so the two recorded environments differ on all four and
16
+ the env clause fired on every pair Task 5's dry run measured:
17
+
18
+ CARGO_TARGET_DIR the root itself
19
+ CARGO_BIN_EXE_* one path under it, per binary target
20
+ LD_LIBRARY_PATH a colon list whose first entry is under it
21
+ RUSTDOCFLAGS a flag string carrying one
22
+
23
+ A clause that cannot not fire is not a finding -- the same rule R1 applied
24
+ to libtest's per-test thread, one check along. Ruling (controller,
25
+ 2026-09-07): a re-run from another target directory is a normal use of the
26
+ tool, and this clause must not read the target root's RELOCATION as a
27
+ change the world made.
28
+
29
+ AND WHY IT IS NOT A LIST OF EXCLUDED NAMES
30
+ -------------------------------------------
31
+ Excluding those four by name would be the cheap fix and the wrong one: a
32
+ program that really is handed a different `LD_LIBRARY_PATH` -- one extra
33
+ directory on the loader's path -- would then earn a full licence. So
34
+ nothing is excluded by name. Each key that DIFFERS is asked one question:
35
+ does the difference disappear when the original's target root is rewritten
36
+ to the re-run's? If it does, the key is named as relocated and the licence
37
+ still holds. If anything else about the value moved, it is a change, and it
38
+ withholds exactly as it did before.
39
+ """
40
+ import re
41
+ from dataclasses import dataclass
42
+
43
+ from sensorium import redact
44
+
45
+ #: The variable that names the root every other one embeds. Present only on
46
+ #: a trace `cargo sensorium` recorded, which is what makes the whole rule a
47
+ #: no-op on a Python trace: no root, nothing to normalise, and every string
48
+ #: below is the one it was before this module existed.
49
+ TARGET_ROOT = "CARGO_TARGET_DIR"
50
+
51
+ #: The phrase that both WRITES the relocation note and RECOGNISES it. One
52
+ #: constant, so the sentence and the reader of the sentence cannot drift.
53
+ _RELOCATED = "differ only by the target directory: "
54
+
55
+
56
+ def relocation(was: dict, now: dict) -> tuple[str, str] | None:
57
+ """The (original, re-run) target roots, or None when there is nothing
58
+ to normalise.
59
+
60
+ None the moment either side lacks the key -- and a root of `/` after
61
+ the trailing separator is stripped is also None, because a root that
62
+ prefixes every absolute path on the machine would explain any
63
+ difference at all, which is the opposite of a check.
64
+ """
65
+ old = (was.get(TARGET_ROOT) or "").rstrip("/")
66
+ new = (now.get(TARGET_ROOT) or "").rstrip("/")
67
+ if not old or not new:
68
+ return None
69
+ return old, new
70
+
71
+
72
+ #: What may appear INSIDE a path component. A root preceded by one of
73
+ #: these is the tail of a longer name, not the name itself -- `mytarget-a`
74
+ #: ends with `target-a` and is a different directory. A root preceded by a
75
+ #: separator, a space, an `=` or nothing at all begins a component and is
76
+ #: the root.
77
+ _NAME_CHAR = re.compile(r"[A-Za-z0-9_.+~@-]")
78
+
79
+
80
+ def _reroot(segment: str, old: str, new: str) -> str:
81
+ """`segment` with every path rooted at `old` re-rooted at `new`.
82
+
83
+ Where the root NAMES A PATH and nowhere else, anchored on BOTH sides:
84
+ followed by a separator or the end of the segment, and preceded by the
85
+ start of the segment or a character no path component may contain.
86
+ A substitution that skipped either anchor would grant a licence over a
87
+ directory that really did move -- `/build/target-abc` is not
88
+ `/build/target-a` relocated on the right, and `/ws/mytarget-a` is not
89
+ `target-a` relocated on the left. The left anchor matters most for a
90
+ RELATIVE root (`CARGO_TARGET_DIR=target-a`), which carries no leading
91
+ separator of its own to stand in for it.
92
+
93
+ Only the root is re-rooted, never a component that repeats it: `/a/a`
94
+ under `/a` -> `/z` is `/z/a`, because the second `/a` is the child.
95
+ """
96
+ out, i = [], 0
97
+ while True:
98
+ at = segment.find(old, i)
99
+ if at < 0:
100
+ break
101
+ end = at + len(old)
102
+ begins = at == 0 or not _NAME_CHAR.match(segment[at - 1])
103
+ ends = end == len(segment) or segment[end] == "/"
104
+ if begins and ends:
105
+ out.append(segment[i:at])
106
+ out.append(new)
107
+ i = end
108
+ else:
109
+ # Advance by ONE, not past the whole occurrence: a root that
110
+ # overlaps itself would otherwise lose its second start.
111
+ out.append(segment[i:at + 1])
112
+ i = at + 1
113
+ out.append(segment[i:])
114
+ return "".join(out)
115
+
116
+
117
+ def differs_only_by_root(was: str, now: str, old: str, new: str) -> bool:
118
+ """Whether the ONLY difference between two values is where the target
119
+ directory is.
120
+
121
+ Compared entry by entry, splitting on the separator a `PATH`-like list
122
+ uses, because the count of entries is itself a fact: a list that gained
123
+ or lost one is a change however the rest of it reads, and comparing the
124
+ joined strings instead would let an added directory ride in behind a
125
+ relocation. A single path is a list of one and takes the same route.
126
+
127
+ An entry that differs must both CONTAIN the old root and match after
128
+ the substitution; the trailing separator is forgiven on that entry
129
+ alone, because the two recorders may spell one directory `<root>` and
130
+ `<root>/` and that is a difference in the spelling, not in the world.
131
+ """
132
+ entries_was, entries_now = was.split(":"), now.split(":")
133
+ if len(entries_was) != len(entries_now):
134
+ return False
135
+ explained = False
136
+ for before, after in zip(entries_was, entries_now):
137
+ if before == after:
138
+ continue
139
+ if old not in before:
140
+ return False
141
+ if _reroot(before, old, new).rstrip("/") != after.rstrip("/"):
142
+ return False
143
+ explained = True
144
+ return explained
145
+
146
+
147
+ # -- session set 1: where a process was STARTED, not what it computes ------
148
+ #: The version of the set below. It is a NUMBER in the printed line on
149
+ #: purpose: an exemption from the licence's default is a claim, and a claim
150
+ #: a reader can date and argue with is a different thing from a silent one.
151
+ #: A key found to bear on what a program computes leaves the set with a
152
+ #: date; a key found to differ between shells joins it with one.
153
+ SESSION_SET = 1
154
+
155
+ #: Session set 1, the exact names. The tuple's order is the DOCUMENTATION
156
+ #: order -- the design's (amendment A-section-3) and this repository's
157
+ #: `docs/query.md` -- and the order E4'' arm C walks to pick the key it
158
+ #: injects. It is not the order the names print in: a differing key is
159
+ #: reported in the sorted key order `_env_diff` walks, like every other
160
+ #: name on that line.
161
+ #:
162
+ #: Every one is a handle to a bus, a window, a terminal, a connection, a
163
+ #: service manager's invocation or an agent session -- the identity of WHERE
164
+ #: a process was started, never input to what it computes. A re-run launched
165
+ #: from another shell differs on these and on very little else: measured
166
+ #: 2026-09-08 (names only) against kept E4 original 20260907-111144-33d30c,
167
+ #: 73 keys equal, 0 added, 3 missing (the previous launcher's own pins) and
168
+ #: exactly ONE changed, `CLAUDE_CODE_SESSION_ID`. That is the whole of the
169
+ #: problem E4' amendment A1 carried.
170
+ #:
171
+ #: A POSITIVE list, and short. The design first written here kept the
172
+ #: opposite -- a list of variables that "bear" on a program, everything else
173
+ #: let through -- and the suite already held its falsifier:
174
+ #: `test_refocus_withholds_the_licence_when_the_environment_differs`
175
+ #: records under `REFOCUS_TEST_LIMIT` and refocuses without it, a variable
176
+ #: the program demonstrably READS, and `REFOCUS_TEST_LIMIT` is on no bearing
177
+ #: list anyone would write. That design would have granted a licence over a
178
+ #: program that got different input: the direction that claims MORE, which
179
+ #: is the one thing the licence exists to refuse. The tool cannot know which
180
+ #: variables a program reads, so the default stands -- any differing key
181
+ #: withholds -- and this is the one enumerated exception.
182
+ SESSION_ORDER: tuple[str, ...] = (
183
+ "DBUS_SESSION_BUS_ADDRESS", "XDG_SESSION_ID", "TERM_SESSION_ID",
184
+ "WINDOWID", "TMUX", "TMUX_PANE", "SSH_AGENT_PID", "SSH_AUTH_SOCK",
185
+ "SSH_CLIENT", "SSH_CONNECTION", "SSH_TTY", "INVOCATION_ID",
186
+ "JOURNAL_STREAM", "SYSTEMD_EXEC_PID")
187
+ SESSION_EXACT = frozenset(SESSION_ORDER)
188
+
189
+ #: The one prefix. An agent session mints its own variables per session and
190
+ #: their names are not knowable in advance, which is what a prefix is for --
191
+ #: and why there is exactly one: a prefix admits names nobody enumerated, so
192
+ #: each one is a hole and each one has to earn its place.
193
+ SESSION_PREFIXES = ("CLAUDE_CODE_",)
194
+
195
+ #: The phrase that both WRITES the session clause and RECOGNISES it, the
196
+ #: `_RELOCATED`/`_STRIPPED` pattern a third time: one constant, so the
197
+ #: sentence and its reader cannot drift apart.
198
+ #:
199
+ #: There is no `session_clause()` builder beside `relocated_clause` and
200
+ #: `stripped_clause` because this clause counts AND names, and the cap on
201
+ #: how many names it prints (`refocus_world._capped`) lives with the other
202
+ #: printed lists. The phrase is what has to be shared; the assembly is one
203
+ #: f-string at the only site that builds it.
204
+ SESSION_DIFFER = " session variable(s) differ: "
205
+
206
+
207
+ def is_session_key(name: str) -> bool:
208
+ """Whether `name` identifies the session a process was launched from.
209
+
210
+ Exact membership or one of the prefixes, and nothing looser: a family
211
+ resemblance would exempt variables nobody put on the list.
212
+ `XDG_SESSION_IDX` is not `XDG_SESSION_ID`, and `CLAUDE_CODEX` does not
213
+ carry the `CLAUDE_CODE_` prefix.
214
+ """
215
+ return (name in SESSION_EXACT
216
+ or any(name.startswith(p) for p in SESSION_PREFIXES))
217
+
218
+
219
+ # -- harness set 1: which SLOT of a pool ran the work ----------------------
220
+ #: The version of the set below, on `SESSION_SET`'s pattern and for its
221
+ #: reason: an exemption from the licence's default is a claim, and a claim a
222
+ #: reader can date and argue with is a different thing from a silent one. A
223
+ #: SECOND number rather than a widening of session set 1, because the two
224
+ #: answer two questions -- WHERE a process was launched from, and WHICH
225
+ #: worker of a test pool ran it -- and a reader told "outside session set 1"
226
+ #: about a vitest slot would be told the wrong fact.
227
+ HARNESS_SET = 1
228
+
229
+ #: Harness set 1, the exact names. `vitest`'s pool hands every worker
230
+ #: process its own slot bookkeeping: `VITEST_POOL_ID` names the pool entry
231
+ #: and `VITEST_WORKER_ID` the worker inside it, minted per process, and a
232
+ #: re-run takes whichever slot is free. They are the pool's slot
233
+ #: bookkeeping, never input to what a program computes -- so a pair that
234
+ #: differs on them and on nothing else differs by where the work ran.
235
+ #:
236
+ #: A POSITIVE list, and short, for the reason `SESSION_ORDER` states at
237
+ #: length: the tool cannot know which variables a program reads, so the
238
+ #: default stands -- any differing key withholds -- and every enumerated
239
+ #: exception has to earn its place. The tuple's order is the DOCUMENTATION
240
+ #: order, not the printed one: a differing key is reported in the sorted key
241
+ #: order `_env_diff` walks, like every other name on that line.
242
+ HARNESS_ORDER: tuple[str, ...] = ("VITEST_POOL_ID", "VITEST_WORKER_ID")
243
+ HARNESS_EXACT = frozenset(HARNESS_ORDER)
244
+
245
+ #: The phrase that both WRITES the harness clause and RECOGNISES it, on the
246
+ #: `_RELOCATED`/`_STRIPPED`/`SESSION_DIFFER` pattern a fourth time: one
247
+ #: constant, so the sentence and its reader cannot drift apart.
248
+ HARNESS_DIFFER = " harness variable(s) differ: "
249
+
250
+
251
+ def is_harness_key(name: str) -> bool:
252
+ """Whether `name` is a test harness's own slot bookkeeping.
253
+
254
+ Exact membership and nothing looser -- not even the one prefix session
255
+ set 1 allows. `VITEST_` is a family the harness also mints real
256
+ configuration into, so a prefix here would exempt names nobody put on
257
+ the list: `VITEST_POOL_IDX` is not `VITEST_POOL_ID`, and `VITEST` is a
258
+ name this set knows nothing about.
259
+ """
260
+ return name in HARNESS_EXACT
261
+
262
+
263
+ # -- the recorder's OWN fragment, which is not the world's -----------------
264
+ #: `RUSTDOCFLAGS` as `cargo sensorium` writes it, and the one thing in the
265
+ #: compared environment that is the RECORDER's rather than the world's. The
266
+ #: driver links the runtime in by hand -- `--extern` plus the `-L
267
+ #: dependency=` that resolves it -- and the directory carries a digest of
268
+ #: the driver binary and the `sensorium-rt` sources, so the hash MOVES with
269
+ #: every driver build. E4' measured the cost of not knowing that: all 61
270
+ #: pairs withheld on this one key, under a driver that had simply been
271
+ #: rebuilt (that record's section 5, blind spot 27).
272
+ #:
273
+ #: The shape is the fence. `sensorium_rt` by name, `/sensorium/rt/` followed
274
+ #: by exactly sixteen hex characters and one of the two panic strategies,
275
+ #: `libsensorium_rt.rlib`, and -- the rule that makes it ours -- a
276
+ #: BACKREFERENCE: the two tokens must name ONE directory. Two tokens that
277
+ #: name two directories are not a thing this recorder has ever written, so
278
+ #: they are left for the world's compare. `(?:^| )` and `(?= |$)` bound the
279
+ #: match at token edges, and the leading space is consumed with it so the
280
+ #: remainder needs no re-spacing.
281
+ RECORDER_FRAGMENT = re.compile(
282
+ r"(?:^| )--extern sensorium_rt=(?P<dir>\S+/sensorium/rt/[0-9a-f]{16}/"
283
+ r"(?:unwind|abort))/libsensorium_rt\.rlib -L dependency=(?P=dir)(?= |$)")
284
+
285
+
286
+ def strip_recorder_fragment(value: str) -> tuple[str, int]:
287
+ """`value` with every occurrence of our fragment removed, and how many
288
+ were removed.
289
+
290
+ The count is returned rather than inferred from the remainder, because
291
+ the count is what puts the key on the printed strip list: a removal
292
+ that did not report itself would be an exclusion by name, hidden --
293
+ the thing the relocation rule above exists to avoid.
294
+
295
+ NOTHING HAPPENS WHEN NOTHING MATCHED. The value is handed back as it
296
+ came, byte for byte, because this function is called on both sides of
297
+ EVERY key -- and a `strip()` applied unconditionally would make `"UTC "`
298
+ and `"UTC"` compare equal on a variable this recorder never touched.
299
+ That widening would be silent on both channels: the key is only put on
300
+ the printed strip list when the count is non-zero, so a difference the
301
+ licence stopped checking would go unnamed. The trim belongs to the
302
+ removal and to nothing else.
303
+
304
+ Only the space the regex consumed goes with the match; the world's own
305
+ spacing inside what is left is untouched, so two values that differ by
306
+ whitespace still differ after the strip.
307
+ """
308
+ out, count = RECORDER_FRAGMENT.subn("", value)
309
+ return (out.strip(), count) if count else (value, 0)
310
+
311
+
312
+ #: The phrase that both WRITES the strip note and RECOGNISES it, on the
313
+ #: `_RELOCATED` pattern and for the same reason: one constant, so the
314
+ #: sentence and its reader cannot drift apart.
315
+ #:
316
+ #: It lives here rather than in `vocab.py` because it is not language-
317
+ #: bearing. `vocab` holds the sentences that say what Python or Rust means;
318
+ #: this one says what this TOOL does to its own footprint before comparing,
319
+ #: and it reads the same whichever recorder wrote the trace.
320
+ _STRIPPED = "the recorder's own fragment stripped before comparing: "
321
+
322
+
323
+ def stripped_clause(names: list[str]) -> str:
324
+ """What the env line and the verified fact both say about the keys the
325
+ strip touched. Empty when it touched none -- so a Python pair, which
326
+ can never carry the fragment, reads exactly as it always did.
327
+
328
+ Named, never counted, and never silent: a variable this tool removed
329
+ part of before comparing is a variable it checked less of, and a reader
330
+ is owed the name.
331
+ """
332
+ if not names:
333
+ return ""
334
+ return f"{_STRIPPED}{', '.join(names)}"
335
+
336
+
337
+ def relocated_clause(names: list[str]) -> str:
338
+ """What the env line and the verified fact both say about the keys the
339
+ rule explained. Empty when it explained none, so a pair that never
340
+ moved reads exactly as it always did.
341
+
342
+ The names are printed, not counted. "4 variables were fine" is not
343
+ something a reader can judge, and these four are the ones a reader most
344
+ needs to see named: they are the difference between "the tool re-ran
345
+ your program somewhere else" and "your environment changed".
346
+ """
347
+ if not names:
348
+ return ""
349
+ return (f"{len(names)} variable(s) {_RELOCATED}"
350
+ f"{', '.join(names)}; treated as unchanged")
351
+
352
+
353
+ def is_env_rule_note(fact: str) -> bool:
354
+ """Whether a world-fact carries the names a rule of this module
355
+ explained -- by ANY of its five: the target directory that moved, the
356
+ recorder's own fragment removed before the compare, either of the two
357
+ sets that never withhold, or the redacted variables no comparison could
358
+ decide.
359
+
360
+ A withheld licence records no verified facts -- it rests on nothing --
361
+ but the keys these rules EXPLAINED are a finding of their own, and the
362
+ terminal already prints them beside the accusation. Without this the
363
+ trace kept only the accusation, and `info` replayed a licence whose
364
+ screen had said more than the record does.
365
+
366
+ Recognised by the phrases `relocated_clause`, `stripped_clause`,
367
+ `uncomparable_clause` and the two set clauses build, from the same
368
+ constants they build them from, so a rewording moves both halves
369
+ together and cannot leave this reading a sentence that no longer
370
+ exists.
371
+
372
+ Named for the rules and not for one of them: it was
373
+ `is_relocation_note` while it already tested two, and a one-rule name
374
+ over a five-rule predicate is a reader's mistake waiting to be made.
375
+ """
376
+ return (_RELOCATED in fact or _STRIPPED in fact
377
+ or SESSION_DIFFER in fact or HARNESS_DIFFER in fact
378
+ or _UNCOMPARABLE in fact)
379
+
380
+
381
+ # -- the redacted variables, and what may still be said about them ---------
382
+ @dataclass(frozen=True)
383
+ class RedactionPair:
384
+ """The two sides' `redaction` tables, as one comparison can read them.
385
+
386
+ Rule v1 stores a secret-named variable as `<redacted>` and keeps an
387
+ HMAC of the plaintext under the store's key (`redact`), so the licence
388
+ can still answer the only question it asks of a variable -- did it
389
+ change -- over a value it does not hold. The table is what carries the
390
+ digests; this is the pair of them plus the key that verifies a
391
+ PLAINTEXT side against one.
392
+
393
+ `now is None` is the live plaintext side: `refocus` on a Python trace
394
+ re-runs in this process and compares the original's table against the
395
+ environment the re-run executed under, which is not a trace and has no
396
+ table. A `now` table that is merely EMPTY reads the same way for every
397
+ name -- a side that did not redact it -- and the distinction is kept in
398
+ the type because the two arrive from different places and a reader of
399
+ this class should be able to tell which one they have.
400
+
401
+ The comparison table itself (§6.2) lives in `redact.compare` and is not
402
+ re-encoded here: `compare` below builds the two `Side`s and delegates.
403
+ Two spellings of one table is how two commands come to give two answers
404
+ about one pair of digests.
405
+ """
406
+ was: dict[str, str | None]
407
+ was_key_id: str | None
408
+ was_keyed: bool
409
+ now: dict[str, str | None] | None
410
+ now_key_id: str | None
411
+ now_keyed: bool
412
+ key: redact.Key
413
+
414
+ @classmethod
415
+ def of(cls, was_meta: dict, now_meta: dict | None,
416
+ key: redact.Key) -> "RedactionPair | None":
417
+ """The pair, or None when NEITHER side redacted anything.
418
+
419
+ None is the whole of the legacy path: a pair of traces from before
420
+ the rule existed builds no pair, `_env_diff` is handed no
421
+ `redaction`, and every string it writes is byte for byte the one it
422
+ wrote before this module knew what a digest was.
423
+ """
424
+ was, now = _redaction(was_meta), _redaction(now_meta)
425
+ was_env = was.get("env") or {}
426
+ now_env = None if now_meta is None else (now.get("env") or {})
427
+ if not was_env and not now_env:
428
+ return None
429
+ return cls(was_env, was.get("key_id"), bool(was.get("keyed")),
430
+ now_env, now.get("key_id"), bool(now.get("keyed")), key)
431
+
432
+ def covers(self, name: str) -> bool:
433
+ """Whether EITHER side redacted `name`.
434
+
435
+ The gate on the whole comparison: a name no side redacted is
436
+ decided by the plain equality that has always decided it, and
437
+ `compare` is never asked about one.
438
+ """
439
+ return name in self.was or (self.now is not None and name in self.now)
440
+
441
+ def compare(self, name: str, before: str | None,
442
+ after: str | None) -> bool | None:
443
+ """True equal, False differs, None unverifiable -- §6.2's table,
444
+ through the one implementation of it.
445
+
446
+ `before`/`after` are the two sides' STORED values, read only on a
447
+ side that did not redact this name, where the stored value is the
448
+ plaintext itself.
449
+ """
450
+ was = self._side(name, self.was, self.was_key_id, self.was_keyed)
451
+ now = self._side(name, self.now, self.now_key_id, self.now_keyed)
452
+ return redact.compare(before, after, was, now, self.key)
453
+
454
+ @staticmethod
455
+ def _side(name: str, table: dict | None, key_id: str | None,
456
+ keyed: bool) -> redact.Side | None:
457
+ """One side's account of one name, or None when that side holds the
458
+ plaintext (it did not redact the name, or it is the live side)."""
459
+ if table is None or name not in table:
460
+ return None
461
+ return table[name], key_id, keyed
462
+
463
+
464
+ def _redaction(meta: dict | None) -> dict:
465
+ return ((meta or {}).get("redaction") or {})
466
+
467
+
468
+ #: The phrase that both WRITES the uncomparable clause and RECOGNISES it,
469
+ #: the `_RELOCATED`/`_STRIPPED`/`SESSION_DIFFER` pattern a fifth time: one
470
+ #: constant, so the sentence and its reader cannot drift apart.
471
+ _UNCOMPARABLE = " redacted variable(s) not comparable ("
472
+
473
+
474
+ def uncomparable_clause(names: list[str], reason: str | None,
475
+ capped: str) -> str:
476
+ """What the env line and the verified fact both say about the redacted
477
+ names no comparison could decide. Empty when there are none, so every
478
+ pair that compared cleanly reads exactly as it always did.
479
+
480
+ ONE reason for the whole list, and the word is `redact.uncomparable`'s
481
+ (`unkeyed`, `different keys`): a per-name reason would be several
482
+ spellings of one repair -- find the other store's key, or accept that
483
+ there is none to find.
484
+
485
+ Named and never counted alone, on the `stripped_clause` pattern: a
486
+ variable this tool stopped checking is one a reader is owed the name
487
+ of. The cap on how many print is `refocus_world._capped`, passed in
488
+ already applied, because every other capped list on that line is capped
489
+ by the same function and this module is the one that file imports FROM.
490
+ """
491
+ if not names:
492
+ return ""
493
+ return f"{len(names)}{_UNCOMPARABLE}{reason}): {capped}"