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.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- 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}"
|