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,214 @@
1
+ """What `info` prints about a trace only the Rust recorder writes.
2
+
3
+ Split from `info_cmd` for one reason: these are facts about how a BUILD
4
+ recorded a process -- which units were instrumented, which fell back, which
5
+ file was never reached, whether recording refused a further unit -- and none
6
+ of them exist in a Python trace. Keeping them here means `info_cmd.run` has
7
+ one extra call and no extra branch, and a Python trace's output cannot drift
8
+ by accident.
9
+
10
+ Every line is gated on the meta key it reports, never on the language: a
11
+ Rust trace written by an older converter that carries none of these keys
12
+ prints none of these lines, which is the same rule the rest of `info`
13
+ follows. Zero counts are printed where the count IS the finding (`units:`,
14
+ `partial fns`, `err_flow_outside_frames`), and withheld where a printed zero
15
+ would read as proof (`seq gaps`, `records dropped`, `panics unrecorded`) --
16
+ the `late_writes` precedent.
17
+ """
18
+ from collections import Counter
19
+
20
+
21
+ def rust_lines(trace, m: dict) -> list[str]:
22
+ """The Rust block, in the order `info` prints it: what built this
23
+ process, what it recorded, then everything it could not follow.
24
+
25
+ The declaration comes BEFORE the counts it qualifies, and the child runs
26
+ immediately after the declaration that says spawns were not witnessed:
27
+ a list of joined children read on its own is an inventory, and the
28
+ declaration is what stops it being read as a complete one.
29
+ """
30
+ # Local: `info_cmd` imports THIS module, and the two halves of its
31
+ # unwitnessed block are what this order rearranges -- importing them at
32
+ # module level would be a cycle, and duplicating their wording here
33
+ # would be two sentences about one fact.
34
+ from sensorium.query.info_cmd import declaration_lines, witnessed_counts
35
+ return (_build_lines(m)
36
+ + declaration_lines(trace, m)
37
+ + _child_runs(m)
38
+ + _live_threads(m)
39
+ + witnessed_counts(trace, m)
40
+ + _loss_lines(m)
41
+ + _panic_lines(m)
42
+ + _err_flow_lines(m))
43
+
44
+
45
+ def _build_lines(m: dict) -> list[str]:
46
+ out = []
47
+ if m.get("invocation"):
48
+ binary = str(m.get("exe", "?")).rsplit("/", 1)[-1]
49
+ out.append(f"invocation: {m['invocation']} binary: {binary} "
50
+ f"pid: {m.get('pid', '?')}")
51
+ if "instrumented_units" in m:
52
+ out.append(_units_line(m))
53
+ if "partial" in m:
54
+ # Design R6. Beside the units line because it is the same kind of
55
+ # fact -- what the transformer could not reach -- and printed at
56
+ # ZERO, because zero is what says every `?` site in the workspace is
57
+ # watched. The key's ABSENCE is a different fact (a converter that
58
+ # predates the list, or a Python trace), and prints nothing.
59
+ out.append(f"partial fns: {len(m['partial'] or [])} "
60
+ "(?-sites the transformer could not reach)")
61
+ unscoped = m.get("manifests_unscoped") or 0
62
+ if unscoped:
63
+ # A shared CARGO_TARGET_DIR holds every workspace's manifests in one
64
+ # directory; a manifest with no `workspace_root` at all predates that
65
+ # field and is excluded from `uninstrumented`/`skipped`/`spawns`/
66
+ # `unreached_files` rather than silently folded in -- this is the
67
+ # line that says some manifests were that old, not zero of them.
68
+ out.append(f"manifests unscoped: {unscoped} -- predate the "
69
+ "workspace stamp")
70
+ unreached = m.get("unreached_files") or []
71
+ if unreached:
72
+ # Named, never counted alone: "1 file was not reached" leaves the
73
+ # reader unable to tell whether the code they are looking for is in
74
+ # it. A file nothing reached is a hole in the trace with an address.
75
+ out.append(f"unreached files: {len(unreached)} -- "
76
+ + ", ".join(unreached))
77
+ refused = m.get("units_refused") or {}
78
+ if refused.get("refused"):
79
+ # The most consequential absence this recorder can have: everything
80
+ # after this point in the process is missing, and nothing else in
81
+ # the trace says so. A reader who takes the event list as complete
82
+ # after a ceiling is reading a truncated run as a whole one.
83
+ out.append(f"unit ceiling: recording REFUSED at unit "
84
+ f"{refused.get('at', '?')} -- every later call in this "
85
+ "process is unrecorded")
86
+ return out
87
+
88
+
89
+ def _units_line(m: dict) -> str:
90
+ """One line for the build: instrumented, fell back, skipped, spawn
91
+ sites. The zeros are printed here because the count is the claim -- "0
92
+ fell back" is what says the whole workspace was instrumented -- and each
93
+ non-zero carries its reasons, because "3 skipped" without them cannot be
94
+ told from "3 functions this recorder cannot see"."""
95
+ units = m.get("instrumented_units") or []
96
+ spawns = m.get("spawns") or []
97
+ wrapped = sum(1 for s in spawns if s.get("wrapped"))
98
+ return (f"units: {len(units)} instrumented, "
99
+ f"{_with_reasons(m.get('uninstrumented'), 'fell back')}, "
100
+ f"{_with_reasons(m.get('skipped'), 'skipped')}, "
101
+ f"{len(spawns)} spawn sites ({wrapped} wrapped)")
102
+
103
+
104
+ def _with_reasons(entries, verb: str) -> str:
105
+ entries = entries or []
106
+ if not entries:
107
+ return f"0 {verb}"
108
+ reasons = Counter(e.get("reason") or "?" for e in entries)
109
+ detail = ", ".join(f"{r} x{n}" for r, n in sorted(reasons.items()))
110
+ return f"{len(entries)} {verb} ({detail})"
111
+
112
+
113
+ def _child_runs(m: dict) -> list[str]:
114
+ kids = m.get("child_runs") or []
115
+ if not kids:
116
+ return []
117
+ return [f"child runs: {len(kids)} -- "
118
+ + ", ".join(str(k.get("run_id", "?")) for k in kids)]
119
+
120
+
121
+ def _live_threads(m: dict) -> list[str]:
122
+ """Threads that never ended. The process DID finish, so the trace is not
123
+ INCOMPLETE -- and that is exactly the pair a reader misreads one way or
124
+ the other (`rust/HONESTY.md` section 4), so both halves are said.
125
+
126
+ "Still running" is one of two ways to end up here, and the trace can tell
127
+ them apart: a thread whose spool went inert could not write THREAD_END
128
+ either, so where `records_dropped` is non-zero the line offers that
129
+ reading too rather than asserting a thread was running that had
130
+ finished."""
131
+ live = m.get("live_threads") or []
132
+ if not live:
133
+ return []
134
+ dropped = m.get("records_dropped") or {}
135
+ total = sum(int(v) for v in dropped.values() if v is not None)
136
+ why = "still running when the process ended"
137
+ if total:
138
+ why += (" -- or whose spool was inert at exit and could not record "
139
+ f"an ending (records dropped: {total})")
140
+ return [f"live threads: {len(live)} -- " + ", ".join(str(t) for t in live)
141
+ + f" -- {why}: their frames are "
142
+ "left open and no ending for them was recorded, which is not "
143
+ "the same fact as an INCOMPLETE recording and is not printed "
144
+ "as one"]
145
+
146
+
147
+ def _loss_lines(m: dict) -> list[str]:
148
+ """Two different numbers, never merged: `seq_gaps` is INFERRED from a
149
+ hole in the process-global sequence, `records_dropped` is WITNESSED by a
150
+ writer that knew it could not write. Both are bounded losses and both
151
+ make `diff` refuse a verdict (`Trace.dropped_writes`)."""
152
+ out = []
153
+ gaps = m.get("seq_gaps") or 0
154
+ if gaps:
155
+ out.append(f"seq gaps: {gaps} -- records minted and never found in "
156
+ "any spool (one lost mid-write per thread at most; see "
157
+ "rust/HONESTY.md §4)")
158
+ dropped = m.get("records_dropped") or {}
159
+ total = sum(int(v) for v in dropped.values() if v is not None)
160
+ if total:
161
+ detail = ", ".join(f"thread {k}: {v}" for k, v in
162
+ sorted(dropped.items(), key=_serial_key))
163
+ out.append(f"records dropped: {total} -- records the runtime knew it "
164
+ f"could not write ({detail}); a thread whose spool could "
165
+ "not be mapped or grown is inert from that point on")
166
+ return out
167
+
168
+
169
+ def _serial_key(item) -> tuple:
170
+ """Thread serials are NUMBERS carried in JSON object keys, which are
171
+ strings: sorting them as strings puts thread 10 before thread 2, and a
172
+ reader scanning for a thread finds it in the wrong place. Anything not a
173
+ plain integer sorts after the numbers, by its own text, rather than
174
+ raising on a key this reader did not write."""
175
+ key = str(item[0])
176
+ return (0, int(key), "") if key.isdigit() else (1, 0, key)
177
+
178
+
179
+ def _panic_lines(m: dict) -> list[str]:
180
+ out = []
181
+ unrecorded = m.get("panics_unrecorded") or 0
182
+ if unrecorded:
183
+ out.append(f"panics unrecorded: {unrecorded} -- frames that unwound "
184
+ "with no PANIC record on their thread (hook replaced, or "
185
+ "the panic began before recording)")
186
+ outside = m.get("panics_outside_frames") or 0
187
+ if outside:
188
+ out.append(f"panics outside frames: {outside} -- panics recorded on "
189
+ "a thread with no open frame, so there is no frame to "
190
+ "attach a RAISE to and none was written")
191
+ return out
192
+
193
+
194
+ def _err_flow_lines(m: dict) -> list[str]:
195
+ """Err flow's version of the line above, printed beside it because it is
196
+ the same fact about a different record kind: a RAISE or HANDLED on a
197
+ thread with no open frame has nothing to be reported against, so the
198
+ converter counts it and writes no event (design R16, `rust/HONESTY.md`
199
+ §11).
200
+
201
+ Printed at ZERO, unlike the panic lines: this is the `partial fns` rule,
202
+ not the `late_writes` one. A zero here says every err-flow record the
203
+ runtime wrote reached the trace as an event -- which is exactly what a
204
+ reader tallying swallows needs to know before trusting the tally. The
205
+ key's ABSENCE is a different fact (a Python trace, or a converter older
206
+ than err flow) and prints nothing.
207
+ """
208
+ if "err_flow_outside_frames" not in m:
209
+ return []
210
+ return [f"err_flow_outside_frames: {m['err_flow_outside_frames'] or 0} "
211
+ "-- RAISE/HANDLED records on a thread with no open frame (a sink "
212
+ "or arm inside an `async {}` block polled off-frame, or a site "
213
+ "whose enclosing CALL was refused), counted and never written as "
214
+ "events"]
@@ -0,0 +1,261 @@
1
+ """What `info` prints about a trace only the TypeScript recorder writes.
2
+
3
+ Split from `info_cmd` for the reason `info_rust` is: these are facts about
4
+ how a HARNESS and a CONTAINER produced a recording -- which harness the
5
+ driver waited for, which test file this worker ran, how many tests the
6
+ transform reached of the ones the harness registered, what the transform
7
+ excluded -- and none of them exist in a Python or a Rust trace. Keeping
8
+ them here means `info_cmd.run` gets one call on a gate it already
9
+ computes, and no other trace's output can drift by accident.
10
+
11
+ THREE EXIT FACTS, THREE LINES, NEVER MERGED
12
+ -------------------------------------------
13
+ `typescript/HONESTY.md` section 6 states the rule and this module keeps it:
14
+
15
+ * `exit_status` / `exit_status_basis` -- the CONTAINER's status, always
16
+ `null` / `unwitnessed`, because the driver spawned the harness and not
17
+ its workers. Printed by the shared `vocab.exit_phrase` on `info`'s own
18
+ interpreter line, as `exit: unwitnessed`.
19
+ * `exit_self_reported` -- what the container said about its OWN ending,
20
+ from inside, on the way out. Nobody waited for it, and the line says so.
21
+ * `harness_exit` -- what the driver really did wait for, with the basis
22
+ attached.
23
+
24
+ Three processes, three facts. Rendering any of them wearing another's name
25
+ is the failure the whole exit rule exists to stop.
26
+
27
+ Every line but `tests:` is gated on the meta key it reports, never on the
28
+ language: a TypeScript trace written by an older converter that carries
29
+ none of these keys prints none of the others, which is the rule the rest
30
+ of `info` follows. `tests:` is gated on the trace's own TASK rows instead
31
+ -- a task count is not a meta key -- and adds its "seen by the harness"
32
+ clause only when `tests_seen` is present (R38). Zero counts are printed
33
+ where the count IS the finding
34
+ (`throw flow outside frames` is not: a zero there is silence about records
35
+ that arrived nowhere) and where the recorder can prove it looked -- the
36
+ `unhandledRejection` listener always ran, so on a COMPLETE trace a zero is
37
+ measured, and on an incomplete one it is only how far the count got.
38
+ """
39
+
40
+
41
+ def interp_suffix(m: dict) -> str:
42
+ """What ran the program, beyond the interpreter: ` (vitest 4.1.9,
43
+ jsdom)`.
44
+
45
+ `node v24.16.0` alone is true and nearly useless -- every container of
46
+ every TypeScript recording says it. The harness version and the DOM
47
+ environment are what change a run's behaviour, and both are recorded
48
+ per invocation, so they belong on the line a reader compares two runs
49
+ by. Each half is gated on its own key; with neither there is no
50
+ parenthesis, not an empty one.
51
+ """
52
+ parts = []
53
+ if m.get("vitest"):
54
+ parts.append(f"vitest {m['vitest']}")
55
+ if m.get("environment"):
56
+ parts.append(m["environment"])
57
+ return f" ({', '.join(parts)})" if parts else ""
58
+
59
+
60
+ def typescript_lines(trace, m: dict) -> list[str]:
61
+ """The TypeScript block, in the order `info` prints it: what ran the
62
+ harness, what this container was, how it ended, then what the recording
63
+ reached and what it did not.
64
+
65
+ The harness comes first because it is the only line about a process the
66
+ reader can go and look at another trace of; the container's own
67
+ identity follows, and the counts that qualify what every number below
68
+ them means come after both.
69
+ """
70
+ return (_harness_line(m)
71
+ + _container_line(m)
72
+ + _self_reported_line(m)
73
+ + _tests_line(trace, m)
74
+ + _files_line(m)
75
+ + _flow_lines(m))
76
+
77
+
78
+ def _harness_line(m: dict) -> list[str]:
79
+ """The command the driver spawned and waited for, AS TYPED (R26).
80
+
81
+ `harness_command` is the tokens the user gave after `--`, before the
82
+ driver consumed `--root`/`--config` out of them and before it re-issued
83
+ its own. Nothing else here is a command: `harness` is the KIND the
84
+ driver recognised and `harness_args` is what survived the consumption,
85
+ so joining the two builds a string nobody typed -- `node-test --test
86
+ test/` names no program, and the user's `--root` is simply gone from
87
+ it. That join is kept only as the fallback for a trace whose converter
88
+ predates the key, where the alternative is printing nothing.
89
+
90
+ Shared with `runs`' invocation header by rule and not by call: the two
91
+ print the same fact in two different layouts, and this is the sentence
92
+ both are checked against (`v23`, `v28`).
93
+
94
+ `harness cwd` comes second and only where the key is present, because it
95
+ is the directory THAT command's relative arguments were relative to --
96
+ where the person was standing, which is neither the container's `cwd`
97
+ nor the plan's `root`, and which is what a re-run has to reproduce.
98
+ """
99
+ typed = m.get("harness_command")
100
+ if typed:
101
+ cmd = " ".join(typed)
102
+ elif m.get("harness"):
103
+ cmd = " ".join([m["harness"], *(m.get("harness_args") or [])]).rstrip()
104
+ else:
105
+ return []
106
+ lines = [f"harness: {cmd}{_harness_ending(m)}"]
107
+ if m.get("harness_cwd"):
108
+ lines.append(f"harness cwd: {m['harness_cwd']}")
109
+ return lines
110
+
111
+
112
+ def _harness_ending(m: dict) -> str:
113
+ """` exit: 1 (waited)`, and nothing at all with no record.
114
+
115
+ An absent `harness_exit` is a driver killed before the harness returned
116
+ -- `ingest` is re-runnable over exactly that spool directory -- and is
117
+ not a harness that ended at 0. `status` and `signal` are exclusive.
118
+ """
119
+ ending = m.get("harness_exit")
120
+ if not ending:
121
+ return ""
122
+ basis = ending.get("basis", "waited")
123
+ if ending.get("status") is not None:
124
+ return f" exit: {ending['status']} ({basis})"
125
+ if ending.get("signal") is not None:
126
+ return f" exit: signal {ending['signal']} ({basis})"
127
+ return ""
128
+
129
+
130
+ def _container_line(m: dict) -> list[str]:
131
+ """Which process and thread this trace IS, and which test file it ran.
132
+
133
+ `(main|worker)` is `is_main_thread`, and it is worth a word because it
134
+ decides what the absence of a `threads_started` record means here: a
135
+ worker's siblings are other traces of this same invocation, unlinked.
136
+ """
137
+ if "pid" not in m:
138
+ return []
139
+ line = f"container: pid {m['pid']}"
140
+ if "thread_id_os" in m:
141
+ where = "main" if m.get("is_main_thread") else "worker"
142
+ line += f" thread {m['thread_id_os']} ({where})"
143
+ one = m.get("test_file")
144
+ several = m.get("test_files")
145
+ if one:
146
+ line += f" file: {one}"
147
+ elif several:
148
+ line += f" files: {len(several)}"
149
+ return [line]
150
+
151
+
152
+ def _self_reported_line(m: dict) -> list[str]:
153
+ """What the container said about its own ending on the way out.
154
+
155
+ `(nobody waited)` is not decoration: this number came from inside the
156
+ process that was ending, which is exactly the kind of status the exit
157
+ rule refuses to print bare. A container that never got to observe its
158
+ own ending carries no key and gets no line -- which is not the same
159
+ fact as one that ended at 0.
160
+ """
161
+ ending = m.get("exit_self_reported")
162
+ if not ending:
163
+ return []
164
+ if ending.get("code") is not None:
165
+ return [f"container exit: self-reported code {ending['code']} "
166
+ "(nobody waited)"]
167
+ if ending.get("signal") is not None:
168
+ return [f"container exit: self-reported signal {ending['signal']} "
169
+ "(nobody waited)"]
170
+ # The record exists and carries neither. Said rather than dropped: a
171
+ # missing line means "no EXIT record", and this is not that.
172
+ return ["container exit: self-reported, but the record carries neither "
173
+ "a code nor a signal"]
174
+
175
+
176
+ def _tests_line(trace, m: dict) -> list[str]:
177
+ """How many tests the transform reached, of the ones the harness ran.
178
+
179
+ The shortfall is the finding. A test the transform did not wrap ran and
180
+ was recorded by nothing, so a bare count of tasks would read as the
181
+ whole test file; the setup file counts what the HARNESS registered so
182
+ the difference can be stated instead of being silence
183
+ (`typescript/HONESTY.md` section 2).
184
+
185
+ Where nobody counted -- `node --test`, which runs no setup file -- the
186
+ key is absent and the clause is not printed at all (R38). It read
187
+ `tests: 2 as tasks, 0 seen by the harness` there, a zero nothing
188
+ measured, which invites exactly the subtraction the clause exists to
189
+ make possible.
190
+ """
191
+ tasks = len(trace.tasks())
192
+ line = f"tests: {tasks} as tasks"
193
+ seen = m.get("tests_seen")
194
+ if seen is not None:
195
+ line += f", {seen} seen by the harness"
196
+ if seen > tasks:
197
+ line += (f"; {seen - tasks} registered through a shape the "
198
+ "transform did not wrap")
199
+ line += _naming(m)
200
+ return [line]
201
+
202
+
203
+ def _naming(m: dict) -> str:
204
+ """Which rule named this trace's tasks, and how often it disagreed.
205
+
206
+ A conflict is a provider name that did not end with the string literal
207
+ the transform passed; the task then falls back to its lexical title and
208
+ the disagreement is counted rather than resolved. The count travels
209
+ with the basis it qualifies -- alone it would name no rule to doubt.
210
+ """
211
+ basis = m.get("task_name_basis")
212
+ conflicts = m.get("task_name_conflicts") or 0
213
+ if basis:
214
+ return (f"; task names: {basis}"
215
+ + (f", {conflicts} conflict(s)" if conflicts else ""))
216
+ return f"; {conflicts} task name conflict(s)" if conflicts else ""
217
+
218
+
219
+ def _files_line(m: dict) -> list[str]:
220
+ """What the transform edited, and what it refused, BY REASON.
221
+
222
+ A count of exclusions with no reasons is a number a reader cannot act
223
+ on; the reasons are the difference between "nothing happened in that
224
+ file" and "nothing was watching it". An empty exclusion map prints no
225
+ clause, because there is nothing to name.
226
+ """
227
+ if "files_transformed" not in m:
228
+ return []
229
+ line = f"files: {m['files_transformed']} transformed"
230
+ excluded = m.get("transform_excluded") or {}
231
+ if excluded:
232
+ detail = ", ".join(f"{reason} x{n}"
233
+ for reason, n in sorted(excluded.items()))
234
+ line += f"; excluded: {sum(excluded.values())} ({detail})"
235
+ return [line]
236
+
237
+
238
+ def _flow_lines(m: dict) -> list[str]:
239
+ """The two things this recorder counts instead of writing an event for.
240
+
241
+ An unhandled rejection has no site, and a throw with no open frame has
242
+ no frame -- a causal event with no `code_id` is refused by the contract
243
+ and inventing a code object would put a site in the program that has
244
+ none (`typescript/HONESTY.md` section 4). The count is the only trace
245
+ of either.
246
+
247
+ The rejection count prints its ZERO on a complete trace, because the
248
+ listener always ran: that zero is measured. On an incomplete trace it
249
+ is only how far the counting got, and is withheld on the `late_writes`
250
+ precedent. The outside-frames count is withheld at zero on that
251
+ precedent either way -- nothing in the recording proves a throw at
252
+ module scope would have been noticed.
253
+ """
254
+ out = []
255
+ rejections = m.get("unhandled_rejections")
256
+ if rejections or (rejections is not None and not m.get("incomplete")):
257
+ out.append(f"unhandled rejections: {len(rejections)}")
258
+ outside = m.get("throw_flow_outside_frames") or 0
259
+ if outside:
260
+ out.append(f"throw flow outside frames: {outside}")
261
+ return out