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