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,527 @@
|
|
|
1
|
+
"""Summarize one trace: shape, exceptions, caps, honesty flags.
|
|
2
|
+
|
|
3
|
+
`meta` only guarantees every key for a run that finished normally. A run
|
|
4
|
+
whose `install()` failed is written with `incomplete=True` and never gets
|
|
5
|
+
its finalize pass, so it has no `exit_status`, no `uncaught`, no `children`
|
|
6
|
+
and no `truncated_count` at all -- every read below goes through `.get()`
|
|
7
|
+
with a fallback, and the INCOMPLETE flag is printed first, not buried.
|
|
8
|
+
"""
|
|
9
|
+
import re
|
|
10
|
+
from collections import Counter
|
|
11
|
+
|
|
12
|
+
from sensorium import paths, redact
|
|
13
|
+
from sensorium.exit import ANSWERED
|
|
14
|
+
from sensorium.query.caps import witness_gap
|
|
15
|
+
from sensorium.query.fmt import fmt_exc
|
|
16
|
+
from sensorium.query.help import RUN_HELP
|
|
17
|
+
from sensorium.query.info_rust import rust_lines
|
|
18
|
+
from sensorium.query.info_typescript import (interp_suffix,
|
|
19
|
+
typescript_lines)
|
|
20
|
+
# `_capped` is private to `refocus_world` and stays there: it is the cap the
|
|
21
|
+
# licence's own printed lists use, and the `env:` field below is a printed
|
|
22
|
+
# list of names on the same terms. Importing it is how the two cannot drift
|
|
23
|
+
# to two different caps; a second spelling of "eight, then a count" would be
|
|
24
|
+
# a second answer to how much of an environment `info` shows.
|
|
25
|
+
from sensorium.query.refocus_world import (_capped, harness_exclusion,
|
|
26
|
+
unverifiable_line)
|
|
27
|
+
from sensorium.query.caps import print_elisions, print_truncated
|
|
28
|
+
from sensorium.query.vocab import exit_phrase, terms
|
|
29
|
+
from sensorium.store.reader import Trace
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def add_parser(sub) -> None:
|
|
33
|
+
p = sub.add_parser(
|
|
34
|
+
"info", help="summarize one trace",
|
|
35
|
+
description="Recorder, language, the capabilities the trace "
|
|
36
|
+
"declares, what was recorded and what was not, focus, "
|
|
37
|
+
"the redaction stamp; read it before any other "
|
|
38
|
+
"question on a run.",
|
|
39
|
+
epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
|
|
40
|
+
p.add_argument("run", help=RUN_HELP)
|
|
41
|
+
p.set_defaults(func=run)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
_BOOKKEEPING = ("children", "threads_started", "spawn_syscalls",
|
|
45
|
+
"audit_errors")
|
|
46
|
+
_THREAD_BOOKKEEPING = ("threads_started",)
|
|
47
|
+
_CHILD_BOOKKEEPING = ("children", "spawn_syscalls", "audit_errors")
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def unwitnessed_lines(trace, m: dict) -> list[str]:
|
|
51
|
+
"""Everything the recorder NOTICED starting and could not witness, in
|
|
52
|
+
the order a Python trace has always printed it.
|
|
53
|
+
|
|
54
|
+
The two halves are separate functions because `info_rust` prints them
|
|
55
|
+
in the other order (declaration first, then the counts it qualifies)
|
|
56
|
+
and adds its own lines between them. Neither half's WORDING moves.
|
|
57
|
+
"""
|
|
58
|
+
return witnessed_counts(trace, m) + declaration_lines(trace, m)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def witnessed_counts(trace, m: dict) -> list[str]:
|
|
62
|
+
"""The counts of what the recorder saw start and could not follow.
|
|
63
|
+
|
|
64
|
+
`children` was for a long time the only one of these `info` printed, so a
|
|
65
|
+
`multiprocessing` run whose child is visible ONLY as a spawn syscall, and
|
|
66
|
+
every thread a run started, left no mark on the durable record at all --
|
|
67
|
+
while `refocus` withholds its licence on exactly these keys. Two commands
|
|
68
|
+
reading one trace must not answer the same question differently.
|
|
69
|
+
|
|
70
|
+
Non-zero values only, on the `late_writes` precedent: a printed `spawn
|
|
71
|
+
syscalls: 0` would be read as proof no child ran, which is precisely what
|
|
72
|
+
it is not. A trace that never recorded the key at all is a third state,
|
|
73
|
+
and says so rather than reading as a zero.
|
|
74
|
+
"""
|
|
75
|
+
out = []
|
|
76
|
+
started = m.get("threads_started")
|
|
77
|
+
if started:
|
|
78
|
+
# Partitioned the way the licence partitions it, and on the same
|
|
79
|
+
# screen as the licence lines `info` replays below (design R1): the
|
|
80
|
+
# recorder's own harness threads come out of the count and are
|
|
81
|
+
# named. The emit test reads the raw count, so a run whose only
|
|
82
|
+
# extra thread is the harness's still says so. Python starts none,
|
|
83
|
+
# and both the number and the string are unchanged there.
|
|
84
|
+
harness, harness_clause = harness_exclusion(trace)
|
|
85
|
+
out.append(
|
|
86
|
+
f"threads started: {started - harness} besides the main one"
|
|
87
|
+
f"{harness_clause}, "
|
|
88
|
+
f"{terms(trace).thread_origin} -- one that ran no traced code "
|
|
89
|
+
"has no fingerprint above and was not otherwise seen")
|
|
90
|
+
spawns = m.get("spawn_syscalls")
|
|
91
|
+
if spawns:
|
|
92
|
+
out.append(
|
|
93
|
+
f"spawn syscalls: {spawns} -- low-level process starts, counted "
|
|
94
|
+
"apart from any subprocess named above because one Popen nests "
|
|
95
|
+
"one; a multiprocessing 'spawn'/'forkserver' child is visible "
|
|
96
|
+
"here and nowhere else")
|
|
97
|
+
errors = m.get("audit_errors")
|
|
98
|
+
if errors:
|
|
99
|
+
out.append(
|
|
100
|
+
f"audit hook errors: {errors} -- the subprocess and thread "
|
|
101
|
+
"records above are INCOMPLETE, and a short list there cannot be "
|
|
102
|
+
"read as 'nothing was started'")
|
|
103
|
+
return out
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def declaration_lines(trace, m: dict) -> list[str]:
|
|
107
|
+
"""Why each absent bookkeeping key is absent -- as a declaration from
|
|
108
|
+
format 4 on, as "predates" only for a trace that really does."""
|
|
109
|
+
out: list[str] = []
|
|
110
|
+
# An incomplete run is missing all of these for a reason already printed
|
|
111
|
+
# at the top; saying it twice would bury the one that is news.
|
|
112
|
+
if m.get("incomplete"):
|
|
113
|
+
return out
|
|
114
|
+
if trace.declares("threads") is None:
|
|
115
|
+
# Predates declarations outright (no `capabilities` key): one
|
|
116
|
+
# merged line, in the original key order and the original wording
|
|
117
|
+
# -- this task changes nothing about a pre-format-4 trace's output.
|
|
118
|
+
missing = [k for k in _BOOKKEEPING if k not in m]
|
|
119
|
+
if missing:
|
|
120
|
+
out.append("not recorded in this trace: " + ", ".join(missing)
|
|
121
|
+
+ " -- it predates that bookkeeping, so absence of "
|
|
122
|
+
"the record is not a record of absence")
|
|
123
|
+
return out
|
|
124
|
+
# From format 4 an absence is a declaration, and `threads` and
|
|
125
|
+
# `children` can be declared two different ways on the same trace --
|
|
126
|
+
# grouped so a mixed case never borrows one capability's declaration to
|
|
127
|
+
# describe the other's.
|
|
128
|
+
missing_threads = [k for k in _THREAD_BOOKKEEPING if k not in m]
|
|
129
|
+
if missing_threads:
|
|
130
|
+
out.append("not recorded in this trace: "
|
|
131
|
+
+ ", ".join(missing_threads) + " -- "
|
|
132
|
+
+ witness_gap(trace, "threads", "thread", ""))
|
|
133
|
+
missing_children = [k for k in _CHILD_BOOKKEEPING if k not in m]
|
|
134
|
+
if missing_children:
|
|
135
|
+
out.append("not recorded in this trace: "
|
|
136
|
+
+ ", ".join(missing_children) + " -- "
|
|
137
|
+
+ witness_gap(trace, "children", "child-process", ""))
|
|
138
|
+
return out
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def capabilities_line(trace) -> str:
|
|
142
|
+
"""What the trace DECLARES -- never what a reader assumed on its behalf.
|
|
143
|
+
|
|
144
|
+
`Trace.capabilities` fills in `boot.CAPABILITIES` (every one true) for a
|
|
145
|
+
Python trace carrying no `capabilities` key. That is the right reading
|
|
146
|
+
for a command deciding whether to refuse -- the only recorder that
|
|
147
|
+
existed had every capability -- but printing it here rendered an
|
|
148
|
+
assumption as a declaration: a format-1 trace said `capabilities:
|
|
149
|
+
children=yes line=yes ... tasks=yes threads=yes` two lines above
|
|
150
|
+
`tasks: not recorded (format-1 trace; parentage assumed)`, about the
|
|
151
|
+
same trace. `declares()` returns None for exactly that case and for no
|
|
152
|
+
other, so it is what the branch reads.
|
|
153
|
+
"""
|
|
154
|
+
if trace.declares("threads") is None:
|
|
155
|
+
return ("undeclared (pre-format-4 Python recorder; read as full by "
|
|
156
|
+
"every command)")
|
|
157
|
+
return (" ".join(f"{k}={'yes' if v else 'no'}"
|
|
158
|
+
for k, v in sorted(trace.capabilities.items()))
|
|
159
|
+
or "(none declared)")
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def focus_matched_line(meta: dict) -> str | None:
|
|
163
|
+
"""What the focus SELECTED, beside what was typed (ruling R31).
|
|
164
|
+
|
|
165
|
+
Two different facts, and the line prints only the keys the trace holds.
|
|
166
|
+
`focus` is the spec as its author wrote it, which is what they will
|
|
167
|
+
recognise; `focus_matched` is the `<file>:<qualname>` of every function
|
|
168
|
+
it actually selected, which is what says whether the spelling meant
|
|
169
|
+
what they thought -- a spec that matched one function where its author
|
|
170
|
+
expected three is invisible on the `focus:` line above.
|
|
171
|
+
|
|
172
|
+
`functions_focused` is a third number and only sometimes a different
|
|
173
|
+
one: the matched specs are the INVOCATION's, shared by every container
|
|
174
|
+
it started, while the tally is what THIS container's transform
|
|
175
|
+
instrumented. Equal, it says nothing the count already said and is
|
|
176
|
+
folded away; different, it is a fact about this container and is
|
|
177
|
+
printed rather than reconciled.
|
|
178
|
+
"""
|
|
179
|
+
matched = meta.get("focus_matched")
|
|
180
|
+
if matched is None:
|
|
181
|
+
return None
|
|
182
|
+
line = f"focus matched: {len(matched)} \u2014 {', '.join(matched)}"
|
|
183
|
+
count = meta.get("functions_focused")
|
|
184
|
+
if count is not None and count != len(matched):
|
|
185
|
+
line += f" ({count} function(s) focused by the transform)"
|
|
186
|
+
return line
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def env_field(meta: dict) -> str:
|
|
190
|
+
"""The `env:` field: the hash, and what rule v1 took out of the
|
|
191
|
+
environment that hash is over (design section 6.1).
|
|
192
|
+
|
|
193
|
+
NAMES only. A digest beside the name it belongs to is an offline
|
|
194
|
+
guessing target for any short value, and this field exists to say what
|
|
195
|
+
was redacted, never to carry it.
|
|
196
|
+
|
|
197
|
+
Three forms, and the difference between the last two is the whole
|
|
198
|
+
point: `(120 vars, 2 redacted: ...)` when the rule fired,
|
|
199
|
+
`(120 vars, 0 redacted)` when it ran and fired on nothing -- a MEASURED
|
|
200
|
+
zero, which is not the same fact as the bare hash a trace from before
|
|
201
|
+
the rule prints. `mode: off` prints the bare hash too: nothing was
|
|
202
|
+
taken, and the line below says so in words.
|
|
203
|
+
"""
|
|
204
|
+
hashed = meta.get("env_hash", "?")
|
|
205
|
+
redaction = meta.get("redaction") or {}
|
|
206
|
+
if redaction.get("mode") != "on":
|
|
207
|
+
return hashed
|
|
208
|
+
names = sorted(redaction.get("env") or {})
|
|
209
|
+
stored = f"{len(meta.get('env') or {})} vars"
|
|
210
|
+
if not names:
|
|
211
|
+
return f"{hashed} ({stored}, 0 redacted)"
|
|
212
|
+
return f"{hashed} ({stored}, {len(names)} redacted: {_capped(names)})"
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def redaction_line(meta: dict) -> str:
|
|
216
|
+
"""The rule this recording was made under, in one of four forms.
|
|
217
|
+
|
|
218
|
+
`none` is the one a reader most needs: a trace with no `redaction` key
|
|
219
|
+
was written before the rule existed and holds the launching shell's
|
|
220
|
+
environment in plaintext, tokens and all. Absence of the key is not
|
|
221
|
+
absence of secrets, and this line is the only place that is said.
|
|
222
|
+
|
|
223
|
+
The key MODE rides the keyed form when the store's key is loose AND is
|
|
224
|
+
the key that took these digests: a world-readable key makes every
|
|
225
|
+
digest in the store guessable, and a note about some other store's file
|
|
226
|
+
permissions would send a reader to the wrong file.
|
|
227
|
+
|
|
228
|
+
`values redacted:` rides BOTH forms the rule ran under, and only when
|
|
229
|
+
the recorder actually counted. It is a fact about the whole recording
|
|
230
|
+
-- captures, output chunks and exception messages -- not about the
|
|
231
|
+
environment, which is why it is here and not in the `env:` field. A
|
|
232
|
+
recording made before the count existed carries no `values` key, and a
|
|
233
|
+
zero invented for it would be a measurement nobody made; the two forms
|
|
234
|
+
the rule did NOT run under (`OFF`, `none`) say in words that nothing
|
|
235
|
+
was taken, and a count there would be a second, weaker way of saying
|
|
236
|
+
it.
|
|
237
|
+
"""
|
|
238
|
+
redaction = meta.get("redaction")
|
|
239
|
+
if not redaction:
|
|
240
|
+
return ("redaction: none -- recorded before redaction existed; "
|
|
241
|
+
"plaintext throughout")
|
|
242
|
+
if redaction.get("mode") != "on":
|
|
243
|
+
return ("redaction: OFF (SENSORIUM_NO_REDACT) -- the environment "
|
|
244
|
+
"and every captured value are stored in plaintext")
|
|
245
|
+
rule, by = redaction.get("rule"), redaction.get("by")
|
|
246
|
+
took = (f"; values redacted: {redaction['values']}"
|
|
247
|
+
if "values" in redaction else "")
|
|
248
|
+
if not redaction.get("keyed"):
|
|
249
|
+
return (f"redaction: rule {rule}, UNKEYED (no redaction.key in the "
|
|
250
|
+
f"store); by {by}{took}")
|
|
251
|
+
key_id = redaction.get("key_id")
|
|
252
|
+
# One read of the store's key answers both halves -- whether the file
|
|
253
|
+
# is loose, and whether it is the file that took these digests.
|
|
254
|
+
key = redact.Key.load(paths.trace_root())
|
|
255
|
+
note = key.mode_note()
|
|
256
|
+
mode = f" ({note})" if note and key_id == key.key_id else ""
|
|
257
|
+
return (f"redaction: rule {rule}, keyed (key {key_id}), by {by}{mode}"
|
|
258
|
+
f"{took}")
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def run(args) -> int:
|
|
262
|
+
t = Trace.open(paths.find_trace(args.run))
|
|
263
|
+
m = t.meta
|
|
264
|
+
counts = t.counts()
|
|
265
|
+
|
|
266
|
+
print(f"run {m.get('run_id', t.path.stem)} trace: {t.path}")
|
|
267
|
+
if m.get("incomplete"):
|
|
268
|
+
print("INCOMPLETE: recording ended without a finalize pass "
|
|
269
|
+
"(process died mid-record); exit/uncaught/children/"
|
|
270
|
+
"truncated-count fields below are UNKNOWN, not zero")
|
|
271
|
+
print_truncated(t)
|
|
272
|
+
print_elisions(t)
|
|
273
|
+
|
|
274
|
+
dur = ""
|
|
275
|
+
if m.get("end_ts") and m.get("start_ts"):
|
|
276
|
+
dur = f" duration: {m['end_ts'] - m['start_ts']:.2f}s"
|
|
277
|
+
print(f"cmd: {' '.join(m.get('argv', []))} cwd: {m.get('cwd', '?')}")
|
|
278
|
+
# meta["env"] is the entire process environment -- never print it
|
|
279
|
+
# wholesale; env_hash lets two runs be compared without leaking it.
|
|
280
|
+
words = terms(t)
|
|
281
|
+
# The gate the TypeScript block below shares. `interp_line` renders the
|
|
282
|
+
# `node <version>` half from the vocabulary table like every other
|
|
283
|
+
# language's; the harness and DOM environment beside it are keys only
|
|
284
|
+
# this recorder writes, so the suffix is that module's and not a fourth
|
|
285
|
+
# `Terms` field with two empty columns.
|
|
286
|
+
ts = t.lang == "typescript"
|
|
287
|
+
print(f"{words.interp_line(m)}{interp_suffix(m) if ts else ''} "
|
|
288
|
+
f"env:{env_field(m)} "
|
|
289
|
+
f"exit: {exit_phrase(m)} events: {sum(counts.values())}"
|
|
290
|
+
f"{dur}")
|
|
291
|
+
print(f"recorder: {t.recorder} lang: {t.lang} "
|
|
292
|
+
f"capabilities: {capabilities_line(t)}")
|
|
293
|
+
print("recorded: " + " ".join(f"{k} {counts.get(k, 0)}" for k in
|
|
294
|
+
("CALL", "RETURN", "RAISE", "HANDLED",
|
|
295
|
+
"YIELD", "RESUME", "LINE")))
|
|
296
|
+
# An ABSENT `focus` key and a RECORDED EMPTY one are two different
|
|
297
|
+
# records and print as two different words. The converter writes no key
|
|
298
|
+
# at all on a run that named no focus (`convert/meta.rs`: "no focus, no
|
|
299
|
+
# key"), and `boot` always writes the list it was handed, so an
|
|
300
|
+
# unfocused Rust trace is on one side of that fence and an unfocused
|
|
301
|
+
# Python trace on the other. Collapsing both into the dash meant no
|
|
302
|
+
# reader -- and no test -- could tell from this line which the trace
|
|
303
|
+
# holds, and design section 6's "`info` shows no `focus` key" could be
|
|
304
|
+
# pinned only as `focus: -` rather than literally. The dash keeps the
|
|
305
|
+
# ABSENT key, which is what this line already prints for an absent
|
|
306
|
+
# `window` and what the Rust corpus pins; the recorded empty list gets
|
|
307
|
+
# the word `info` already uses for a counted nothing, `none`.
|
|
308
|
+
focus = m.get("focus")
|
|
309
|
+
shown = ", ".join(focus) if focus else ("none" if focus == [] else "-")
|
|
310
|
+
print(f"focus: {shown} window: {m.get('window') or '-'}")
|
|
311
|
+
matched = focus_matched_line(m)
|
|
312
|
+
if matched:
|
|
313
|
+
print(matched)
|
|
314
|
+
caps = m.get("caps", {})
|
|
315
|
+
print("caps: " + " ".join(f"{k}={v}" for k, v in caps.items())
|
|
316
|
+
+ f" truncated values: {m.get('truncated_count', 0)}")
|
|
317
|
+
# Directly under `caps:`, because it is a parameter of the recording
|
|
318
|
+
# like the capture limits above it, and the one line every trace prints
|
|
319
|
+
# -- including one recorded before the rule existed, which is exactly
|
|
320
|
+
# the trace whose reader most needs to be told.
|
|
321
|
+
print(redaction_line(m))
|
|
322
|
+
# A Rust trace's build facts, and its unwitnessed block, come BEFORE the
|
|
323
|
+
# fingerprints: what a fingerprint row covers depends on which units
|
|
324
|
+
# were instrumented at all, and a ceiling above it changes what every
|
|
325
|
+
# count below means. A Python trace prints neither here and keeps its
|
|
326
|
+
# unwitnessed block in its own place, below.
|
|
327
|
+
rust = t.lang == "rust"
|
|
328
|
+
if rust:
|
|
329
|
+
for line in rust_lines(t, m):
|
|
330
|
+
print(line)
|
|
331
|
+
# Same place, same reason: a TypeScript container's harness, its test
|
|
332
|
+
# file and how many of the harness's tests the transform actually
|
|
333
|
+
# reached all change what every count below them means.
|
|
334
|
+
if ts:
|
|
335
|
+
for line in typescript_lines(t, m):
|
|
336
|
+
print(line)
|
|
337
|
+
# What a fingerprint row covers is not readable from the hash, and plan
|
|
338
|
+
# 2b narrowed it: under the per-task basis a thread row holds only what
|
|
339
|
+
# ran in no asyncio task, and each task has a row of its own. Two traces
|
|
340
|
+
# whose rows mean different things print identically without this, and a
|
|
341
|
+
# reader comparing them by eye has nothing to go on.
|
|
342
|
+
per_task = t.fingerprint_basis == "per-task"
|
|
343
|
+
# The narrowing is a fact about THIS run, not only about the recorder's
|
|
344
|
+
# version: a run that never made a task had nothing narrowed away, and
|
|
345
|
+
# "(4 causal events outside any asyncio task)" beside "0 task
|
|
346
|
+
# fingerprint(s)" invites a reader to go looking for the tasks. So the
|
|
347
|
+
# qualifier and the count are gated on the run having tasks -- which is
|
|
348
|
+
# the same gate `refocus._thread_scope` uses, and the two commands must
|
|
349
|
+
# not describe one trace differently.
|
|
350
|
+
ran_tasks = per_task and bool(t.tasks())
|
|
351
|
+
scope = f" outside any {words.task_noun}" if ran_tasks else ""
|
|
352
|
+
for tid, (h, n) in sorted(t.fingerprints().items()):
|
|
353
|
+
tag = " (main)" if tid == t.main_thread_id() else ""
|
|
354
|
+
print(f"fingerprint thread {tid}{tag}: {h} ({n} causal events{scope})")
|
|
355
|
+
if per_task:
|
|
356
|
+
# The basis line stays whatever the run did: it says how this
|
|
357
|
+
# recorder defines a thread row, which is what a reader comparing
|
|
358
|
+
# two traces by eye needs. Under Ruling 9 every task has a
|
|
359
|
+
# fingerprint row, so this count is the task count -- a zero-count
|
|
360
|
+
# row means that task ran no causal event while traced.
|
|
361
|
+
beside = (f"; {len(t.task_fingerprints())} task fingerprint(s) "
|
|
362
|
+
"beside it" if ran_tasks else "")
|
|
363
|
+
print("fingerprints: per-task basis -- each thread row covers the "
|
|
364
|
+
f"events that ran in no {words.task_noun}{beside}")
|
|
365
|
+
else:
|
|
366
|
+
# Never claimed retroactively: a trace recorded before the marker
|
|
367
|
+
# existed was fingerprinted the other way, and saying "0 task
|
|
368
|
+
# fingerprints" about it would read as "no task ran".
|
|
369
|
+
print("fingerprints: per-thread basis -- each thread row covers "
|
|
370
|
+
"every causal event on the thread, task events included; no "
|
|
371
|
+
"task fingerprints were recorded (recorded before they "
|
|
372
|
+
"existed)")
|
|
373
|
+
if m.get("uncaught"):
|
|
374
|
+
print(f"uncaught: {fmt_exc(m['uncaught'])}")
|
|
375
|
+
for child in m.get("children") or []:
|
|
376
|
+
print(f"unwitnessed subprocess: {' '.join(child)}")
|
|
377
|
+
if not rust:
|
|
378
|
+
for line in unwitnessed_lines(t, m):
|
|
379
|
+
print(line)
|
|
380
|
+
# Always the JOIN, on every format. Arc 2 opens a frame for every traced
|
|
381
|
+
# code object -- function, generator, coroutine, or async generator -- so
|
|
382
|
+
# a format-3 trace is expected to have none of these, and the zero SAYS
|
|
383
|
+
# so: a bare "unframed calls: 0" on an older trace means only that this
|
|
384
|
+
# run happened to make none. But the reason is printed for a counted
|
|
385
|
+
# zero, never instead of counting: reading the format and reporting a
|
|
386
|
+
# count is the instrument describing a version number as though it had
|
|
387
|
+
# looked at the trace.
|
|
388
|
+
unframed = t.unframed_calls()
|
|
389
|
+
if t.format >= 3 and not unframed:
|
|
390
|
+
print("unframed calls: 0 (all calls framed in format 3)")
|
|
391
|
+
else:
|
|
392
|
+
kinds: dict[str, int] = {}
|
|
393
|
+
for ev in unframed:
|
|
394
|
+
k = (ev.payload or {}).get("unframed", "generator/coroutine")
|
|
395
|
+
kinds[k] = kinds.get(k, 0) + 1
|
|
396
|
+
detail = ", ".join(f"{k} {n}" for k, n in sorted(kinds.items()))
|
|
397
|
+
print(f"unframed calls: {len(unframed)}"
|
|
398
|
+
+ (f" ({detail})" if detail else ""))
|
|
399
|
+
if t.format < 2:
|
|
400
|
+
print("tasks: not recorded (format-1 trace; parentage assumed)")
|
|
401
|
+
elif t.tasks():
|
|
402
|
+
print(f"tasks: {len(t.tasks())} ({_task_names(t.tasks(), words)})")
|
|
403
|
+
else:
|
|
404
|
+
# Not "no loop ran": a loop can run and never make a task -- and
|
|
405
|
+
# loop callbacks run inside it with no current task at all.
|
|
406
|
+
print(f"tasks: none (no event ran inside {words.a_task})")
|
|
407
|
+
task_errors = m.get("task_errors", 0)
|
|
408
|
+
if task_errors:
|
|
409
|
+
print(f"task identity errors: {task_errors} -- the task identity "
|
|
410
|
+
"lookup raised that many times (current_task(), or a Task "
|
|
411
|
+
"subclass's __hash__/__eq__); those events carry NULL task_id "
|
|
412
|
+
"meaning 'could not tell', not 'no task'")
|
|
413
|
+
# late_writes is a lower bound: writes that arrive after this count was
|
|
414
|
+
# captured can never be counted either. Only surface it when non-zero,
|
|
415
|
+
# so a reader never mistakes a printed "0" for proof nothing was lost.
|
|
416
|
+
late_writes = t.dropped_writes()
|
|
417
|
+
# ...unless the loss was already reported, key by key, above: a Rust
|
|
418
|
+
# trace's `seq_gaps` and `records_dropped` are two different facts with
|
|
419
|
+
# two different provenances, and "late writes dropped" is neither.
|
|
420
|
+
if late_writes and not (m.get("seq_gaps") or m.get("records_dropped")):
|
|
421
|
+
print(f"late writes dropped: >={late_writes} (trace is incomplete "
|
|
422
|
+
"for still-live threads; the true count may be higher)")
|
|
423
|
+
if m.get("refocus_of"):
|
|
424
|
+
# The verdict never travels alone. A bare MATCH here would read as a
|
|
425
|
+
# clean bill of health for a rerun whose licence was withheld on
|
|
426
|
+
# every count, and a bare DIVERGED gives the reader no way to see
|
|
427
|
+
# WHAT diverged without re-running the comparison by hand.
|
|
428
|
+
licence = m.get("refocus_licence")
|
|
429
|
+
print(f"refocus-of: {m['refocus_of']} "
|
|
430
|
+
f"verdict: {m.get('refocus_verdict', 'UNVERIFIED')}"
|
|
431
|
+
+ (f" licence: {licence}" if licence else ""))
|
|
432
|
+
# What ELSE that re-run produced, in the words the pair line used.
|
|
433
|
+
# Only a TypeScript re-run has siblings -- its branch re-runs a
|
|
434
|
+
# whole harness invocation and compares one container of it -- so
|
|
435
|
+
# the sentence is imported from there rather than spelled a second
|
|
436
|
+
# time here. Absent key, absent line: a re-run recorded before the
|
|
437
|
+
# stamp existed did not have zero siblings, it has no record of
|
|
438
|
+
# them, and `0` is a measurement.
|
|
439
|
+
siblings = m.get("refocus_siblings")
|
|
440
|
+
if siblings is not None:
|
|
441
|
+
from sensorium.query.refocus_typescript import siblings_note
|
|
442
|
+
print(f" {siblings_note(siblings)}")
|
|
443
|
+
# Three ways a rerun can part, three separate stamps -- and a rerun
|
|
444
|
+
# is stamped with the ones that apply, never with all of them. The
|
|
445
|
+
# positional line is absent for a divergence that was not a step of
|
|
446
|
+
# the compared thread's stream at all (`refocus` deliberately writes
|
|
447
|
+
# no index for one), which is precisely when the task line below is
|
|
448
|
+
# the whole answer: without it `info` printed a bare DIVERGED and
|
|
449
|
+
# left the reader to re-run the comparison by hand.
|
|
450
|
+
index = m.get("refocus_diverge_index")
|
|
451
|
+
if index is not None:
|
|
452
|
+
# Indexed, not `.get(..., '?')`: `refocus._stamp` writes these
|
|
453
|
+
# three keys in one block and always has, so a '?' here could
|
|
454
|
+
# only ever be printed by a trace this project did not write. A
|
|
455
|
+
# fallback for that case is a fallback nothing can reach, and it
|
|
456
|
+
# reads as though the value were sometimes genuinely unknown.
|
|
457
|
+
print(f" diverged at causal step {index}: "
|
|
458
|
+
f"A {m['refocus_diverge_a']} / B {m['refocus_diverge_b']}")
|
|
459
|
+
if m.get("refocus_thread_divergence"):
|
|
460
|
+
print(f" diverged on threads: {m['refocus_thread_divergence']}")
|
|
461
|
+
if m.get("refocus_diverge_tasks"):
|
|
462
|
+
print(f" diverged on tasks: {m['refocus_diverge_tasks']}")
|
|
463
|
+
for reason in m.get("refocus_licence_reasons") or []:
|
|
464
|
+
print(f" licence withheld: {reason}")
|
|
465
|
+
# A granted licence without its points is the bad news keeping its
|
|
466
|
+
# qualifications while the good news loses them. The terminal prints
|
|
467
|
+
# five itemised facts and the blind spots; what persisted was the
|
|
468
|
+
# word "granted", which reads as unbounded -- exactly the failure the
|
|
469
|
+
# comment in `runs_cmd` names one level up. `refocus` has been
|
|
470
|
+
# stamping these into the trace all along; nothing read them.
|
|
471
|
+
verified = m.get("refocus_licence_verified") or []
|
|
472
|
+
for fact in verified:
|
|
473
|
+
print(f" licence verified: {fact}")
|
|
474
|
+
if licence == "granted" and not verified:
|
|
475
|
+
print(" licence granted, but this trace does not record WHAT it "
|
|
476
|
+
"was granted on -- it predates that record; re-run "
|
|
477
|
+
"`sensorium refocus` for the bounded list")
|
|
478
|
+
# The other half of what `refocus` stamped. A reader given the
|
|
479
|
+
# `licence verified:` lines alone is left to infer that every other
|
|
480
|
+
# check ran and failed -- and on a Rust pair two of them could not
|
|
481
|
+
# run at all (design 2026-09-07 R7). Absent key, absent line: the
|
|
482
|
+
# stamp's absence is not a claim that everything was checked.
|
|
483
|
+
unrun = unverifiable_line(m.get("refocus_licence_unverifiable"))
|
|
484
|
+
if unrun:
|
|
485
|
+
print(f" {unrun}")
|
|
486
|
+
for reason in m.get("refocus_refused_reasons") or []:
|
|
487
|
+
print(f" refused: {reason}")
|
|
488
|
+
counts_by_code = t.call_counts()
|
|
489
|
+
hot = sorted(((c, counts_by_code.get(c.id, 0)) for c in t.codes()),
|
|
490
|
+
key=lambda x: -x[1])[:8]
|
|
491
|
+
if hot:
|
|
492
|
+
print("hot functions:")
|
|
493
|
+
for code, n in hot:
|
|
494
|
+
if n:
|
|
495
|
+
print(f" {n}x {code.file.rsplit('/', 1)[-1]}:{code.qualname}")
|
|
496
|
+
return ANSWERED
|
|
497
|
+
|
|
498
|
+
|
|
499
|
+
_DEFAULT_TASK_NAME = re.compile(r"^Task-\d+\Z")
|
|
500
|
+
_TASK_LIST_CAP = 8
|
|
501
|
+
|
|
502
|
+
|
|
503
|
+
def _task_names(tasks, words) -> str:
|
|
504
|
+
"""Up to eight tasks: every one, `tN name`. More: names grouped and
|
|
505
|
+
counted, most frequent first, asyncio's default `Task-N` names (a
|
|
506
|
+
creation counter, not an identity) folded into one group. A FastAPI test
|
|
507
|
+
run recorded 166 tasks and the flat list said nothing a reader could
|
|
508
|
+
use; "2 distinct name(s): …coro x120, Task-N x46" does."""
|
|
509
|
+
default_names = words.default_name_note is not None
|
|
510
|
+
if len(tasks) <= _TASK_LIST_CAP:
|
|
511
|
+
return ", ".join(
|
|
512
|
+
f"t{k.id} {k.name if k.name is not None else words.unnamed_task}"
|
|
513
|
+
for k in tasks)
|
|
514
|
+
groups = Counter()
|
|
515
|
+
for k in tasks:
|
|
516
|
+
if k.name is None:
|
|
517
|
+
label = words.unnamed_task
|
|
518
|
+
elif default_names and _DEFAULT_TASK_NAME.match(k.name):
|
|
519
|
+
label = "Task-N (asyncio default names)"
|
|
520
|
+
else:
|
|
521
|
+
label = k.name
|
|
522
|
+
groups[label] += 1
|
|
523
|
+
shown = groups.most_common(6)
|
|
524
|
+
rest = len(groups) - len(shown)
|
|
525
|
+
body = ", ".join(f"{name} x{n}" for name, n in shown)
|
|
526
|
+
tail = f"; and {rest} more name(s)" if rest else ""
|
|
527
|
+
return f"{len(groups)} distinct name(s): {body}{tail}"
|