sensorium-trace 0.18.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,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}"