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,269 @@
|
|
|
1
|
+
"""The program's own output, and what a granted licence rests on.
|
|
2
|
+
|
|
3
|
+
Split out of `refocus_world`, which sat six lines under this repository's
|
|
4
|
+
800-line ceiling with a slice still to land in it. The seam is the one
|
|
5
|
+
`refocus_world`'s own header names, one step finer: everything there
|
|
6
|
+
establishes FACTS and nothing there decides a verdict, and these are the
|
|
7
|
+
facts stated POSITIVELY -- what the program printed, and what a licence may
|
|
8
|
+
claim once nothing has withheld it. `refocus_world` keeps `_licence_caveats`
|
|
9
|
+
and the checks that feed it, which is where a signal that FIRED withholds
|
|
10
|
+
the licence.
|
|
11
|
+
|
|
12
|
+
That is a move, not an interface: `refocus_world._verified_facts` and the
|
|
13
|
+
rest still resolve, to the SAME function objects, because every caller and
|
|
14
|
+
every test reaching for them is reaching for one command's internals and
|
|
15
|
+
there is still only one of each.
|
|
16
|
+
|
|
17
|
+
The import runs one way, `refocus_world` -> here. `_verified_facts` reads
|
|
18
|
+
three names that stay behind -- `unverifiable_checks` and the two markers it
|
|
19
|
+
tests against -- so it imports them inside its own body, the way
|
|
20
|
+
`refocus_licence` already does and for the same reason: a module-level
|
|
21
|
+
import back would be a cycle.
|
|
22
|
+
"""
|
|
23
|
+
import re
|
|
24
|
+
|
|
25
|
+
from sensorium.query.refocus_threads import harness_exclusion
|
|
26
|
+
from sensorium.query.vocab import terms
|
|
27
|
+
from sensorium.store.reader import Trace
|
|
28
|
+
|
|
29
|
+
# Pytest's own result words, longest first so "subtests passed" is not
|
|
30
|
+
# read as a count plus the word "passed". Anything outside this list is
|
|
31
|
+
# the program's text, and a number in it still counts.
|
|
32
|
+
_PYTEST_STAT = (
|
|
33
|
+
r"subtests passed|subtests failed|subtests skipped|"
|
|
34
|
+
r"passed|failed|skipped|deselected|xfailed|xpassed|"
|
|
35
|
+
r"warnings|warning|errors|error"
|
|
36
|
+
)
|
|
37
|
+
_PYTEST_SUMMARY_CORE = re.compile(
|
|
38
|
+
rf"^(?:no tests ran|(?:\d+ (?:{_PYTEST_STAT}))"
|
|
39
|
+
rf"(?:, \d+ (?:{_PYTEST_STAT}))*)$")
|
|
40
|
+
# The footer token, including the ` (H:MM:SS)` pytest adds past 60s.
|
|
41
|
+
# Anchored at the end so "loaded in 0.02s, then failed" is not one.
|
|
42
|
+
_PYTEST_ELAPSED = re.compile(
|
|
43
|
+
r"\s+in \d+(?:\.\d+)?s(?: \(\d+:\d{2}:\d{2}\))?\s*$")
|
|
44
|
+
_PYTEST_DURATION = re.compile(
|
|
45
|
+
r"^(?P<secs>\d+(?:\.\d+)?)s[ \t]+"
|
|
46
|
+
r"(?P<when>call|setup|teardown)[ \t]+(?P<rest>\S.*?)\s*$")
|
|
47
|
+
|
|
48
|
+
#: Lines matched, but the bytes did not: the old whitespace sentence.
|
|
49
|
+
_WHITESPACE = object()
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _output_text(trace: Trace) -> dict[str, str]:
|
|
53
|
+
out: dict[str, str] = {}
|
|
54
|
+
for _eid, stream, data in trace.output_chunks():
|
|
55
|
+
out[stream] = out.get(stream, "") + data
|
|
56
|
+
return out
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _clip(s: str, cap: int = 60) -> str:
|
|
60
|
+
return repr(s if len(s) <= cap else s[:cap] + "...")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _pytest_summary_core(line: str) -> str | None:
|
|
64
|
+
"""The result words of a pytest footer, or None if this is not one.
|
|
65
|
+
|
|
66
|
+
`=== 1 passed in 0.02s ===` and a bare `1 passed in 0.02s` are the
|
|
67
|
+
same footer: the `=` padding is pytest fitting the line to the
|
|
68
|
+
terminal, and it changes length when the time token does.
|
|
69
|
+
"""
|
|
70
|
+
text = line.strip()
|
|
71
|
+
if len(text) >= 2 and text.startswith("=") and text.endswith("="):
|
|
72
|
+
text = text.strip("=").strip()
|
|
73
|
+
elapsed = _PYTEST_ELAPSED.search(text)
|
|
74
|
+
if elapsed is None:
|
|
75
|
+
return None
|
|
76
|
+
core = text[:elapsed.start()].strip()
|
|
77
|
+
if _PYTEST_SUMMARY_CORE.fullmatch(core):
|
|
78
|
+
return core
|
|
79
|
+
return None
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _pytest_duration_key(line: str) -> tuple[str, str] | None:
|
|
83
|
+
"""`(phase, test)` of a durations-report line, ignoring the seconds."""
|
|
84
|
+
match = _PYTEST_DURATION.match(line.strip())
|
|
85
|
+
if match is None:
|
|
86
|
+
return None
|
|
87
|
+
return match.group("when"), match.group("rest")
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _pytest_timing_only(left: str, right: str) -> bool:
|
|
91
|
+
"""True when two captured lines differ only by pytest's elapsed time.
|
|
92
|
+
|
|
93
|
+
Pytest prints wall-clock duration into the stream the licence treats
|
|
94
|
+
as the program's output: the summary footer (`1 passed in 0.02s` vs
|
|
95
|
+
`1 passed in 0.03s`, padding and all) and the durations report
|
|
96
|
+
(`0.02s call test_foo` vs `0.03s call test_foo`). Two runs of the
|
|
97
|
+
same tests differ there and nowhere else, and that is not the
|
|
98
|
+
program differing. Counts, failure text, and which test is named
|
|
99
|
+
still count. Arbitrary numbers are left alone: a line is eligible
|
|
100
|
+
only when it is one of those two pytest shapes.
|
|
101
|
+
"""
|
|
102
|
+
left_duration = _pytest_duration_key(left)
|
|
103
|
+
right_duration = _pytest_duration_key(right)
|
|
104
|
+
if left_duration is not None or right_duration is not None:
|
|
105
|
+
return (left_duration is not None
|
|
106
|
+
and left_duration == right_duration)
|
|
107
|
+
left_core = _pytest_summary_core(left)
|
|
108
|
+
right_core = _pytest_summary_core(right)
|
|
109
|
+
return left_core is not None and left_core == right_core
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _first_captured_difference(was: str, now: str):
|
|
113
|
+
"""The first real line difference, `_WHITESPACE`, or None.
|
|
114
|
+
|
|
115
|
+
None means the texts differ only by pytest timing (or not at all).
|
|
116
|
+
Timing-only lines are skipped, so a real line later in the stream is
|
|
117
|
+
what gets reported rather than the footer that happens to sit above it.
|
|
118
|
+
"""
|
|
119
|
+
wl, nl = was.splitlines(), now.splitlines()
|
|
120
|
+
saw_timing = False
|
|
121
|
+
for i in range(max(len(wl), len(nl))):
|
|
122
|
+
x = wl[i] if i < len(wl) else "(no more output)"
|
|
123
|
+
y = nl[i] if i < len(nl) else "(no more output)"
|
|
124
|
+
if x == y:
|
|
125
|
+
continue
|
|
126
|
+
if _pytest_timing_only(x, y):
|
|
127
|
+
saw_timing = True
|
|
128
|
+
continue
|
|
129
|
+
return i, x, y
|
|
130
|
+
if saw_timing:
|
|
131
|
+
return None
|
|
132
|
+
return _WHITESPACE
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _output_difference(orig: Trace, new: Trace) -> str | None:
|
|
136
|
+
"""The first place the two runs' captured output parts company.
|
|
137
|
+
|
|
138
|
+
The only cross-check that can catch a recorder-induced change in the
|
|
139
|
+
program: the fingerprint is blind to the instrument by construction (see
|
|
140
|
+
OBSERVER EFFECT), but a `__repr__` that counts its own calls and prints
|
|
141
|
+
the total shows up right here.
|
|
142
|
+
"""
|
|
143
|
+
a, b = _output_text(orig), _output_text(new)
|
|
144
|
+
for stream in sorted(set(a) | set(b)):
|
|
145
|
+
was, now = a.get(stream, ""), b.get(stream, "")
|
|
146
|
+
if was == now:
|
|
147
|
+
continue
|
|
148
|
+
found = _first_captured_difference(was, now)
|
|
149
|
+
if found is None:
|
|
150
|
+
continue
|
|
151
|
+
if found is _WHITESPACE:
|
|
152
|
+
return (f"the program's own captured {stream} differs in "
|
|
153
|
+
"whitespace")
|
|
154
|
+
i, x, y = found
|
|
155
|
+
return (f"the program's own captured {stream} differs, first "
|
|
156
|
+
f"at line {i + 1}: {_clip(x)} -> {_clip(y)}")
|
|
157
|
+
return None
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
# -- what a granted licence rests on ---------------------------------------
|
|
161
|
+
def _spawn_witnessed(meta: dict) -> bool:
|
|
162
|
+
"""Whether this trace's interpreter could witness a `multiprocessing`
|
|
163
|
+
spawn at all.
|
|
164
|
+
|
|
165
|
+
False on CPython < 3.14 -- where no parent-side audit event fires for a
|
|
166
|
+
spawn/forkserver child, so `spawn_syscalls == 0` cannot be read as "none
|
|
167
|
+
ran" -- and on a trace recorded before the capability was noted. The
|
|
168
|
+
recorder stamps the answer at record time (`boot._SPAWN_WITNESSED`).
|
|
169
|
+
"""
|
|
170
|
+
return bool(meta.get("spawn_witnessing"))
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _verified_facts(orig: Trace, new: Trace, scope: str) -> list[str]:
|
|
174
|
+
"""What a granted licence is actually based on, stated positively.
|
|
175
|
+
|
|
176
|
+
`scope` is `refocus_cmd._thread_scope`'s answer, passed in rather than
|
|
177
|
+
recomputed: the same string goes into the assessment dict, and one
|
|
178
|
+
derivation read twice is one derivation that can be read two ways.
|
|
179
|
+
|
|
180
|
+
The granted line used to read "every signal sensorium can check agrees",
|
|
181
|
+
which invites the reader to treat the check-list as complete -- and every
|
|
182
|
+
review round has falsified that reading by finding another path through
|
|
183
|
+
it. Naming the concrete, bounded findings instead cannot be falsified by
|
|
184
|
+
a mechanism nobody has thought of yet: it claims these things and no
|
|
185
|
+
others.
|
|
186
|
+
"""
|
|
187
|
+
from sensorium.query.refocus_world import (UNVERIFIABLE_CHILDREN,
|
|
188
|
+
UNVERIFIABLE_THREADS,
|
|
189
|
+
unverifiable_checks)
|
|
190
|
+
|
|
191
|
+
fps = new.fingerprints()
|
|
192
|
+
# HOW MUCH was compared, not just how many rows. Under the per-task
|
|
193
|
+
# basis a thread row covers only what ran outside every task, and the
|
|
194
|
+
# commonest async shape -- an entry that does nothing but
|
|
195
|
+
# `asyncio.run` -- leaves it covering the module frame, or nothing at
|
|
196
|
+
# all. "Identical call shape across 1 compared fingerprint(s)" over two
|
|
197
|
+
# events of scaffolding reads as a statement about the run; the count
|
|
198
|
+
# and the scope are what make it a bounded claim instead.
|
|
199
|
+
events = sum(c for _h, c in fps.values())
|
|
200
|
+
# The noun is the recorder's, for the reason `vocab.py` exists: on a
|
|
201
|
+
# Rust trace the row is outside the test and spawned threads, and
|
|
202
|
+
# `asyncio` there names a runtime that never ran. `scope` decides
|
|
203
|
+
# WHETHER the clause appears (one derivation, read once); `terms`
|
|
204
|
+
# decides what it calls the units.
|
|
205
|
+
outside = f" outside any {terms(new).task_noun}" if scope else ""
|
|
206
|
+
# The thread clause is a PROVENANCE claim -- "through Python's own
|
|
207
|
+
# threading/_thread" says how the threads this run did not start would
|
|
208
|
+
# have come to exist -- so it comes from the trace's own vocabulary
|
|
209
|
+
# table, for the reason `vocab.py` exists at all. The Python string is
|
|
210
|
+
# unchanged, character for character: `PYTHON.thread_origin` IS this
|
|
211
|
+
# clause, moved.
|
|
212
|
+
# ...and where the recorder started a thread of its own, the clause
|
|
213
|
+
# NAMES it instead of making the provenance claim: design 2026-09-07
|
|
214
|
+
# section 2's line, verbatim. What a granted licence rests on is a
|
|
215
|
+
# bounded list, so the harness thread appears on it as an exclusion
|
|
216
|
+
# rather than being dropped from a sentence that then reads as though
|
|
217
|
+
# only the main thread ever ran.
|
|
218
|
+
harness, harness_clause = harness_exclusion(new)
|
|
219
|
+
thread_fact = (
|
|
220
|
+
f"no thread started besides the main one{harness_clause}"
|
|
221
|
+
if harness else
|
|
222
|
+
f"no thread started besides the main one "
|
|
223
|
+
f"{terms(new).thread_origin}, and none left running when recording "
|
|
224
|
+
"stopped")
|
|
225
|
+
# Decided once and read by both capability guards in this function: two
|
|
226
|
+
# derivations of one list is two answers to "what could this pair not
|
|
227
|
+
# check".
|
|
228
|
+
unverifiable = unverifiable_checks(orig, new)
|
|
229
|
+
facts = [
|
|
230
|
+
f"identical call shape across {len(fps)} compared fingerprint(s), "
|
|
231
|
+
f"holding {events} causal event(s){outside}",
|
|
232
|
+
]
|
|
233
|
+
# ...and stated only where the record it rests on exists. `relicense`
|
|
234
|
+
# takes UNVERIFIABLE_THREADS out of the WITHHOLDING decision, so a pair
|
|
235
|
+
# whose recorder declares it witnesses no thread can be GRANTED -- and
|
|
236
|
+
# a granted licence asserting "no thread started besides the main one"
|
|
237
|
+
# over bookkeeping nobody wrote is exactly the bug this file's header
|
|
238
|
+
# names: a check that never ran, reported as a check that passed. The
|
|
239
|
+
# child claim below is the same rule, three facts on.
|
|
240
|
+
if UNVERIFIABLE_THREADS not in unverifiable:
|
|
241
|
+
facts.append(thread_fact)
|
|
242
|
+
# Stated only when there were tasks: a run with none must not be given
|
|
243
|
+
# a fact about zero of them, and the count is the rerun's rows because
|
|
244
|
+
# a stream present on one side only is a divergence, never a MATCH.
|
|
245
|
+
# Spec D6's sentence in full -- the ordering clause travels with the
|
|
246
|
+
# claim, because "compared by content" is only bounded by what content
|
|
247
|
+
# means here.
|
|
248
|
+
n_tasks = len(new.task_fingerprints())
|
|
249
|
+
if n_tasks:
|
|
250
|
+
facts.insert(1, f"{n_tasks} task stream(s) compared by content; "
|
|
251
|
+
"the ordering between tasks is not compared")
|
|
252
|
+
# The child-witnessing claim rests on an audit event only CPython 3.14+
|
|
253
|
+
# raises for a multiprocessing/forkserver spawn. If EITHER run was recorded
|
|
254
|
+
# where that signal does not exist, the pair cannot vouch that no such child
|
|
255
|
+
# ran, so the line is omitted rather than asserted -- the blind-spot block
|
|
256
|
+
# printed on every verdict still states categorically that no child process
|
|
257
|
+
# is covered, so the gap is stated, not hidden.
|
|
258
|
+
#
|
|
259
|
+
# The capability clause is the same rule stated where it cannot be
|
|
260
|
+
# missed: a recorder that DECLARES it does not witness children can
|
|
261
|
+
# never support this fact, whatever `spawn_witnessing` happens to say.
|
|
262
|
+
# Today no such trace carries the key, so the clause changes no output;
|
|
263
|
+
# it is here because "the pair cannot vouch for this" must not depend on
|
|
264
|
+
# a second key agreeing.
|
|
265
|
+
if (_spawn_witnessed(orig.meta) and _spawn_witnessed(new.meta)
|
|
266
|
+
and UNVERIFIABLE_CHILDREN not in unverifiable):
|
|
267
|
+
facts.append(
|
|
268
|
+
"no child process witnessed, by any mechanism sensorium watches")
|
|
269
|
+
return facts
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
"""The licence code a SECOND driver language needs, at a shared home.
|
|
2
|
+
|
|
3
|
+
Every name here was written for the Rust branch and none of them is about
|
|
4
|
+
Rust: what they encode is what a licence may claim when a check could not
|
|
5
|
+
run, how the pair's own record says so, and what "the environment" means for
|
|
6
|
+
a re-run this process did not perform. A copy of any of them in the
|
|
7
|
+
TypeScript branch would be two spellings of one licence rule, which is how
|
|
8
|
+
two languages come to grant two different licences over the same evidence
|
|
9
|
+
(design 2026-09-07, G2, one layer down).
|
|
10
|
+
|
|
11
|
+
Split from `refocus_world` rather than added to it, because that file was
|
|
12
|
+
within twelve lines of this project's 800-line ceiling when the four
|
|
13
|
+
arrived. The names stay reachable as `refocus_world.<name>` -- the
|
|
14
|
+
re-export there is the same one `refocus_cmd` uses for `refocus_world` and
|
|
15
|
+
`refocus_report`. These are one command's internals across its files, not
|
|
16
|
+
separate modules with surfaces of their own.
|
|
17
|
+
|
|
18
|
+
WHY THE `refocus_world` IMPORTS ARE INSIDE THE FUNCTIONS
|
|
19
|
+
--------------------------------------------------------
|
|
20
|
+
`refocus_world` imports this module at its top, to re-export these names.
|
|
21
|
+
Two of the three functions below need `refocus_world`'s back --
|
|
22
|
+
`_verified_facts` is what a granted licence rests on and `_env_state` is the
|
|
23
|
+
environment compare itself, and neither can move here (both have callers of
|
|
24
|
+
their own, and `_env_state` is `refocus_cmd`'s Python branch). Imported at
|
|
25
|
+
the top that would be a hard cycle, and imported at the BOTTOM of
|
|
26
|
+
`refocus_world` it would be a cycle that only breaks when a caller happens
|
|
27
|
+
to import this module first. So they are taken at call time, which is the
|
|
28
|
+
idiom `refocus_rust` already uses for `refocus_cmd` and for the same reason.
|
|
29
|
+
The DIRECTION is still one way: nothing here runs at import time, and
|
|
30
|
+
`refocus_world` never has to know this file exists except to name it.
|
|
31
|
+
"""
|
|
32
|
+
from pathlib import Path
|
|
33
|
+
|
|
34
|
+
from sensorium.store import db
|
|
35
|
+
from sensorium.store.reader import Trace
|
|
36
|
+
|
|
37
|
+
#: The meta key `_stamp` may not write, because the checks it records are
|
|
38
|
+
#: NOT reasons a licence was withheld -- they are checks that could not run.
|
|
39
|
+
#: Stamped beside `refocus_licence_reasons` rather than inside it, so a
|
|
40
|
+
#: reader of the trace and a reader of the terminal are told the same thing.
|
|
41
|
+
UNVERIFIABLE_KEY = "refocus_licence_unverifiable"
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def relicense(a: dict, orig: Trace, new: Trace, world_verified) -> dict:
|
|
45
|
+
"""Take the UNVERIFIABLE markers out of the WITHHOLDING decision.
|
|
46
|
+
|
|
47
|
+
`_licence_caveats` reports them, because a reader of the licence must be
|
|
48
|
+
told which checks did not run. But a caveat withholds the licence, and
|
|
49
|
+
withholding it here would say the recorder's declared absence of output
|
|
50
|
+
capture is a finding AGAINST this pair -- it is not a finding at all.
|
|
51
|
+
The markers are printed and stamped separately (`print_unverifiable`,
|
|
52
|
+
`UNVERIFIABLE_KEY`), so nothing is hidden by the removal; what is
|
|
53
|
+
removed is only their vote.
|
|
54
|
+
|
|
55
|
+
The verified list is rebuilt exactly as `assess` builds it -- the
|
|
56
|
+
world's fact spliced after the first -- because two splices of one list
|
|
57
|
+
is two orders for the same evidence.
|
|
58
|
+
|
|
59
|
+
Was `refocus_rust._relicense`, which imports it under that name.
|
|
60
|
+
"""
|
|
61
|
+
from sensorium.query.refocus_world import UNVERIFIABLE, _verified_facts
|
|
62
|
+
|
|
63
|
+
caveats = [c for c in a["caveats"] if c not in UNVERIFIABLE]
|
|
64
|
+
if caveats == a["caveats"]:
|
|
65
|
+
return a
|
|
66
|
+
licence, verified = a["licence"], a["verified"]
|
|
67
|
+
if a["verdict"] == "MATCH" and not caveats:
|
|
68
|
+
licence = "granted"
|
|
69
|
+
facts = _verified_facts(orig, new, a["thread_scope"])
|
|
70
|
+
verified = facts[:1] + list(world_verified) + facts[1:]
|
|
71
|
+
return {**a, "caveats": caveats, "licence": licence,
|
|
72
|
+
"verified": verified}
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def stamp_unverifiable(path: Path, checks: list[str]) -> None:
|
|
76
|
+
"""Write the unrun checks into the new trace, beside the licence.
|
|
77
|
+
|
|
78
|
+
Stamped even when the list is empty -- and even when the licence is
|
|
79
|
+
withheld for other reasons -- so `info` on any re-run says which checks
|
|
80
|
+
the verdict does NOT rest on, rather than leaving a reader to infer it
|
|
81
|
+
from the absence of a key.
|
|
82
|
+
|
|
83
|
+
Was `refocus_rust._stamp_unverifiable`, which imports it under that name.
|
|
84
|
+
"""
|
|
85
|
+
conn = db.open_trace(path)
|
|
86
|
+
try:
|
|
87
|
+
db.set_meta(conn, UNVERIFIABLE_KEY, checks)
|
|
88
|
+
conn.commit()
|
|
89
|
+
finally:
|
|
90
|
+
conn.close()
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def print_unverifiable(checks: list[str]) -> None:
|
|
94
|
+
"""The unrun checks, on the terminal, under everything the report said.
|
|
95
|
+
|
|
96
|
+
Beside `stamp_unverifiable` and for its reason: what a pair could not
|
|
97
|
+
check is one sentence, and a branch spelling it for itself is how two
|
|
98
|
+
branches come to report the same fact differently. It was
|
|
99
|
+
`refocus_rust._print_unverifiable` while two branches used it; the
|
|
100
|
+
Python branch is the third (ruling R19), and a generic branch reaching
|
|
101
|
+
into the Rust one for a licence sentence is the dependency this module
|
|
102
|
+
exists to prevent.
|
|
103
|
+
|
|
104
|
+
Silent on an empty list: the block announces checks, and a heading over
|
|
105
|
+
nothing reads as a finding.
|
|
106
|
+
|
|
107
|
+
THE PREAMBLE IS EXACT FOR THREE OF THE FOUR MARKERS AND FALSE FOR THE
|
|
108
|
+
FOURTH. Output, children and threads are checks the recorder declares it
|
|
109
|
+
does not produce -- there is no record, and nothing a reader can do about
|
|
110
|
+
it. `UNVERIFIABLE_ENV` is the other shape: the recorder redacted the
|
|
111
|
+
variable exactly as asked, and what is missing is a KEY -- either none
|
|
112
|
+
took the digests (`unkeyed`, and they are null) or the one that took
|
|
113
|
+
them belongs to another store (`different keys`). Same word, opposite
|
|
114
|
+
repairs -- and the two reasons have different repairs from EACH OTHER,
|
|
115
|
+
which is why the line points at the env line (which carries the reason
|
|
116
|
+
word) rather than naming one. `redact.uncomparable` is where those two
|
|
117
|
+
words come from.
|
|
118
|
+
|
|
119
|
+
The preamble stays byte for byte what it was -- three acceptance readers
|
|
120
|
+
parse it, and every pair that carries no redaction marker still reads
|
|
121
|
+
exactly as it did -- and the one extra line goes UNDER the list, printed
|
|
122
|
+
only for the marker it is about.
|
|
123
|
+
"""
|
|
124
|
+
from sensorium.query.refocus_world import UNVERIFIABLE_ENV
|
|
125
|
+
|
|
126
|
+
if not checks:
|
|
127
|
+
return
|
|
128
|
+
print("checks that could not run on this pair -- the recorder declares "
|
|
129
|
+
"it does not produce them, so nothing here is evidence either "
|
|
130
|
+
"way:")
|
|
131
|
+
for check in checks:
|
|
132
|
+
print(f" - {check}")
|
|
133
|
+
if UNVERIFIABLE_ENV in checks:
|
|
134
|
+
print(" the env one does not fit the heading above: those "
|
|
135
|
+
"variables WERE redacted, and what is missing is the key that "
|
|
136
|
+
"decides them -- the env line names them and says which repair "
|
|
137
|
+
"it is (`unkeyed`: record again under a key; `different keys`:"
|
|
138
|
+
" find the other store's redaction.key).")
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def env_of(meta: dict, new: Trace,
|
|
142
|
+
is_recorder_key) -> tuple[str, str | None, str | None]:
|
|
143
|
+
"""(status line, caveat, fact) for the environment, from BOTH traces.
|
|
144
|
+
|
|
145
|
+
Design section 3.2's `reads` column: a driver language's environment
|
|
146
|
+
check is `env` recorded in both traces, not the caller's process
|
|
147
|
+
environment. Comparing the recorded harness environment against this
|
|
148
|
+
CLI's would diff the harness's own variables against their absence and
|
|
149
|
+
report a changed world on every single run -- a check that always fires
|
|
150
|
+
says nothing.
|
|
151
|
+
|
|
152
|
+
`is_recorder_key` is the CALLER's, because which variables are the
|
|
153
|
+
recorder's own bookkeeping is the one thing here that is not shared:
|
|
154
|
+
cargo's shim names are not vitest's. Everything done with the answer is
|
|
155
|
+
shared, which is why it is a parameter and not a second copy of this.
|
|
156
|
+
|
|
157
|
+
Was `refocus_rust._env_of`, which read its own module's predicate.
|
|
158
|
+
"""
|
|
159
|
+
from sensorium.query.refocus_world import _UNCOMPARED_ENV, _env_state
|
|
160
|
+
|
|
161
|
+
was, now = meta.get("env"), new.meta.get("env")
|
|
162
|
+
if not isinstance(now, dict):
|
|
163
|
+
return ("env: unverifiable -- the re-run's trace records no "
|
|
164
|
+
"environment to compare against",
|
|
165
|
+
"the environment could not be checked at all -- the "
|
|
166
|
+
"re-run's trace holds none to compare -- so nothing rules "
|
|
167
|
+
"out the two runs getting different input through it", None)
|
|
168
|
+
# `_UNCOMPARED_ENV`'s names are already printed by `_env_state`; listing
|
|
169
|
+
# them twice would read as two separate holes in one check.
|
|
170
|
+
mine = sorted({k for k in ((was if isinstance(was, dict) else {}) | now)
|
|
171
|
+
if is_recorder_key(k) and k not in _UNCOMPARED_ENV})
|
|
172
|
+
# `new.meta` whole, beside the FILTERED environment: the recorder's own
|
|
173
|
+
# keys are taken out of the compare, but the re-run's `redaction` table
|
|
174
|
+
# is how a redacted variable is compared at all, and a side handed no
|
|
175
|
+
# meta would be read as the live plaintext one -- which a driver
|
|
176
|
+
# language's re-run never is.
|
|
177
|
+
line, caveat, fact = _env_state(
|
|
178
|
+
{**meta, "env": {k: v for k, v in was.items()
|
|
179
|
+
if not is_recorder_key(k)}}
|
|
180
|
+
if isinstance(was, dict) else meta,
|
|
181
|
+
{k: v for k, v in now.items() if not is_recorder_key(k)},
|
|
182
|
+
now_meta=new.meta)
|
|
183
|
+
if mine:
|
|
184
|
+
named = f"; the recorder's own, also not compared: {', '.join(mine)}"
|
|
185
|
+
line += f" {named[2:]}"
|
|
186
|
+
fact = f"{fact}{named}" if fact else fact
|
|
187
|
+
return line, caveat, fact
|