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
sensorium/ts/build.py ADDED
@@ -0,0 +1,783 @@
1
+ """One spool, one format-4 trace.
2
+
3
+ Every row this module writes goes through `store.writer.TraceWriter`, the
4
+ same writer the Python recorder uses, so the schema has exactly one home
5
+ and a column added there is a column both recorders get. What is local to
6
+ this file is the MAPPING: which wire record becomes which event, which
7
+ frame, which meta key, and -- as often -- which record becomes nothing at
8
+ all and is counted instead.
9
+
10
+ Three of those "counted instead" rules are the reason this file is worth
11
+ reading:
12
+
13
+ * an `UNHANDLED` record becomes a `meta.unhandled_rejections` entry and
14
+ never an event, because a causal event with no `code_id` is refused by
15
+ the contract and a synthetic code object would put a site in the program
16
+ that has none (design D7);
17
+ * a `RAISE`/`HANDLED` whose `f` is null becomes a tick of
18
+ `meta.throw_flow_outside_frames` and no event, because there is no frame
19
+ to attach it to and inventing one would be a claim about where the throw
20
+ happened;
21
+ * an `UNWIND` closes its frame and writes no event: how a frame ended is
22
+ evidence the reader derives (`closed_by`, `unwind_exc`), not a row.
23
+
24
+ Loss is never counted. A container killed by SIGKILL did not get to count
25
+ what it was about to write, so the trace carries `incomplete: true` and no
26
+ `records_dropped` (typescript/HONESTY.md section 5).
27
+ """
28
+ import time
29
+ from dataclasses import dataclass
30
+
31
+ from sensorium import paths, redact, redact_values
32
+ from sensorium.query.js_inspect import is_clipped
33
+ from sensorium.record.fingerprint import Fingerprint
34
+ from sensorium.store.writer import TraceWriter
35
+ from sensorium.ts.invocation import env_hash
36
+ from sensorium.ts.redaction import ran_the_value_rule, rule_runs
37
+ from sensorium.ts.spool import Spool, SpoolError
38
+ from sensorium.ts.truncation import truncation_meta
39
+
40
+ #: What this recorder produces, and what it does not (design section 5.2).
41
+ #: A FLOOR, not the last word: `err_flow` is the one key the BOOT record's
42
+ #: own `capabilities` map (`_meta`) rides OVER this constant, because
43
+ #: whether RAISE/HANDLED rows carry what the `exceptions` rules need is the
44
+ #: runtime's statement to make, not a fact this converter can assert on its
45
+ #: own authority. A spool whose BOOT carries no such map declares the
46
+ #: constant alone -- `err_flow: false` included.
47
+ #:
48
+ #: `refocus` is true for every trace this converter writes (design R10):
49
+ #: the driver can be re-run, the record beside the spools says with what,
50
+ #: and the conversion carries it. Whether one PARTICULAR trace can be
51
+ #: refocused -- this command, this root, this world -- is a refusal the
52
+ #: READER raises with its own sentence, never a capability: a false one
53
+ #: here would refuse the whole command before any of those refusals got to
54
+ #: name the reason the caller could act on.
55
+ CAPABILITIES = {
56
+ "line": False, "locals": False, "return_value": True, "tasks": True,
57
+ "threads": False, "children": False, "stdin": False, "output": False,
58
+ "object_identity": False, "refocus": True, "err_flow": False,
59
+ }
60
+
61
+ #: The capture caps in force in the runtime (`typescript/src/dbg.mjs`).
62
+ CAPS = {"dbg": 200, "depth": 2, "sample": 8, "str": 100}
63
+
64
+ LANG = "typescript"
65
+ #: Every container is one thread as far as a trace is concerned: a worker
66
+ #: thread and a forked child are each their own container with their own
67
+ #: spool, so no trace ever holds two.
68
+ THREAD = 1
69
+
70
+ #: What a suspension parked ON, per wire kind. `await` parks on a promise;
71
+ #: `yield` parks on whoever is pulling the generator. Neither is a type the
72
+ #: recorder read off a value -- they are what the KEYWORD means.
73
+ AWAITING = {"await": "Promise", "yield": "consumer"}
74
+
75
+
76
+ class ConversionError(SpoolError):
77
+ """A record cannot be turned into a row. A subclass of `SpoolError`
78
+ because both are the same thing to a caller -- this spool did not
79
+ convert, here is why, the rest of the invocation still will."""
80
+
81
+
82
+ @dataclass
83
+ class Frame:
84
+ db_id: int
85
+ code_id: int
86
+ depth: int
87
+ rel: str
88
+ qualname: str
89
+ closed: bool = False
90
+
91
+
92
+ class Builder:
93
+ """Reads one `Spool`, writes one trace. Single-threaded and single-use.
94
+
95
+ Held together by three tables: `_frames` maps a wire frame id to the row
96
+ it opened (closed frames included -- a throw-flow record may name one),
97
+ `_files` maps a wire file id to its FILE header, and `_fps` holds one
98
+ `Fingerprint` per task plus the thread's own.
99
+ """
100
+
101
+ def __init__(self, spool: Spool, invocation, harness, tally: dict | None,
102
+ path, run_id: str, durable: bool = False) -> None:
103
+ self.spool = spool
104
+ self.inv = invocation
105
+ self.harness = harness
106
+ self.tally = tally or {}
107
+ self.run_id = run_id
108
+ # Non-durable by default because this is the CONVERTER's builder:
109
+ # `convert` writes under a temporary name and renames into place only
110
+ # after `build()` closes the writer, so no reader can be shown a
111
+ # committed row before then and a build that dies leaves a temporary
112
+ # file `convert` unlinks. The argument exists so a caller that wants
113
+ # the recorder's per-batch commits can say so.
114
+ self.w = TraceWriter(path, durable=durable)
115
+
116
+ self._frames: dict[int, Frame] = {}
117
+ self._files: dict[int, dict] = {}
118
+ self._codes: dict[tuple[int, int], tuple[int, str, str, int]] = {}
119
+ self._fps: dict[int | None, Fingerprint] = {None: Fingerprint()}
120
+ self.tasks: list[int] = []
121
+
122
+ self.source_hashes: dict[str, str] = {}
123
+ self.truncated = 0
124
+ #: How many captures this trace withholds, counted at the WRITE and
125
+ #: never at the rule (R10): one per stored capture carrying a
126
+ #: `redacted` object, whichever hand put it there. That makes
127
+ #: `values` a function of the trace's contents (B3).
128
+ self.values = 0
129
+ self._runtime_did_names = ran_the_value_rule(spool.boot)
130
+ self.tests_seen = 0
131
+ # Whether anything in this spool says the counter RAN. A `node --test`
132
+ # container runs no setup file, so nothing ever calls `seen()` -- and
133
+ # a zero written anyway is a measurement nobody took (R38).
134
+ self.counter_ran = False
135
+ self.outside_frames = 0
136
+ self.rejections: list[dict] = []
137
+ self.file_starts: list[str] = []
138
+ self.environments: set[str] = set()
139
+ self.bases: set[str] = set()
140
+ self.conflicts = 0
141
+ self.events = 0
142
+ self.last_ts: int | None = None
143
+ # Cap meta, filled in when an ELISION record says calls were dropped.
144
+ self._truncation: dict = {}
145
+ # The contract's literal rule (TRACE-FORMAT section 4): `incomplete`
146
+ # is written TRUE at the start of a run and false only after the
147
+ # finalize pass. Written here, before a single record is read, so a
148
+ # build that dies half way leaves a trace that CLAIMS to be
149
+ # unfinished rather than one with no claim at all -- an absent key
150
+ # reads as "not incomplete", which is the finalized reading, and the
151
+ # refusal rule would then let it through with every meta key missing.
152
+ self.w.set_meta("incomplete", True)
153
+
154
+ # -- the pass -----------------------------------------------------------
155
+
156
+ def abort(self) -> None:
157
+ """Let go of a trace that will not be finished.
158
+
159
+ `discard()` and not `close()`: the writer's transaction is rolled
160
+ back rather than committed, because a commit here would checkpoint
161
+ the whole trace out of the WAL and into a file the caller is about
162
+ to unlink. A mid-file refusal (a second BOOT, a record the wire does
163
+ not declare) comes through here with rows already written, and that
164
+ is exactly the build whose commit buys nothing.
165
+
166
+ The file is the caller's to remove -- it reserved the name -- and a
167
+ second failure while unwinding would replace the exception that
168
+ actually says what went wrong, so this one is not allowed to
169
+ propagate.
170
+ """
171
+ try:
172
+ self.w.discard()
173
+ except Exception: # pragma: no cover
174
+ pass
175
+
176
+ def build(self) -> dict:
177
+ """Convert, finalize, close. Returns the meta that was written.
178
+
179
+ Rule v1 is installed for the length of the pass and reset after it:
180
+ the value rules read one module-level state (B6), and the pool
181
+ reuses its workers. Under the STORE's key -- the one `_redaction`
182
+ loads for the environment -- and under NO KNOBS, for the reason
183
+ `_redaction` gives: the knobs belong to a recording this converter
184
+ did not make.
185
+ """
186
+ # B26: a recording made with the rule OFF is converted as it was
187
+ # written. The OFF knob rather than a branch at every site: every
188
+ # transform in `redact_values` is a pass-through under it, so one
189
+ # decision is taken once, here, and `values` stays the zero
190
+ # `_redaction` then does not write.
191
+ off = not rule_runs(self.spool.boot)
192
+ redact_values.install(redact.Key.load(paths.trace_root()),
193
+ redact.Knobs(off, frozenset(), frozenset()))
194
+ try:
195
+ for rec in self.spool.records:
196
+ self._one(rec)
197
+ self._fingerprints()
198
+ meta = self._meta()
199
+ for key, value in meta.items():
200
+ self.w.set_meta(key, value)
201
+ self.w.close()
202
+ return meta
203
+ finally:
204
+ redact_values.reset()
205
+
206
+ def _one(self, rec: dict) -> None:
207
+ handler = getattr(self, "_on_" + rec["e"].lower(), None)
208
+ if handler is None:
209
+ raise ConversionError(
210
+ f"{self.spool.path}: no rule for a {rec['e']} record -- this "
211
+ f"spool is wire {self.spool.boot.get('wire')}, which this "
212
+ "sensorium does not fully read")
213
+ if "ts" in rec:
214
+ self.last_ts = rec["ts"]
215
+ try:
216
+ handler(rec)
217
+ except ConversionError:
218
+ raise
219
+ except (KeyError, TypeError, IndexError, AttributeError) as e:
220
+ # A record missing a key this wire version declares is a spool
221
+ # this converter cannot read, not a crash: named, refused, and
222
+ # the spools beside it convert anyway.
223
+ raise ConversionError(
224
+ f"{self.spool.path}: a {rec['e']} record is not the shape "
225
+ f"wire {self.spool.boot.get('wire')} declares "
226
+ f"({type(e).__name__}: {e})") from None
227
+
228
+ # -- headers ------------------------------------------------------------
229
+
230
+ def _on_file(self, rec: dict) -> None:
231
+ self._files[rec["id"]] = rec
232
+ self.source_hashes[rec["abs"]] = rec["sha"]
233
+
234
+ def _on_file_start(self, rec: dict) -> None:
235
+ self.counter_ran = True
236
+ self.file_starts.append(relative(rec["path"], self.inv.root))
237
+ if rec.get("environment"):
238
+ self.environments.add(rec["environment"])
239
+
240
+ def _on_seen(self, rec: dict) -> None:
241
+ self.counter_ran = True
242
+ self.tests_seen += 1
243
+ self.truncated += bool(rec.get("name_trunc"))
244
+
245
+ def _on_task(self, rec: dict) -> None:
246
+ self.w.add_task(rec["id"], rec["name"], THREAD)
247
+ self.tasks.append(rec["id"])
248
+ self._fps[rec["id"]] = Fingerprint()
249
+ self.bases.add(rec["basis"])
250
+ self.conflicts += bool(rec.get("conflict"))
251
+ self.truncated += bool(rec.get("name_trunc"))
252
+
253
+ def _on_exit(self, rec: dict) -> None:
254
+ """No row. The record is read in `_meta` instead, under a name that
255
+ says whose observation it is (R21).
256
+
257
+ It does NOT become `exit_status`: what `process.on('exit')` reports
258
+ is the code chosen so far, not the status the process was reaped
259
+ with, and a container that borrowed a number it did not witness is
260
+ the Rust D4 failure wearing a different hat. But it is a fact the
261
+ container observed about ITSELF, and dropping a witnessed fact is
262
+ the other failure -- so it is kept, named `exit_self_reported`, and
263
+ `exit_status` stays null with basis `unwitnessed`.
264
+ """
265
+
266
+ def _on_elision(self, rec: dict) -> None:
267
+ """Calls a cap dropped. Applied in `_meta` only when the count is
268
+ above zero, so a record that kept every call adds no truncation key."""
269
+ self._truncation = truncation_meta(rec, self._files, str(self.spool.path))
270
+
271
+ # -- frames -------------------------------------------------------------
272
+
273
+ def _on_call(self, rec: dict) -> None:
274
+ code_id, rel, qualname, line, kind = self._code(rec)
275
+ if "a" in rec:
276
+ # The transform passes `a` at every site. A present key, even
277
+ # an empty map, is a read: `catchBinding()` takes nothing, and
278
+ # "read, found none" is a different fact from "nobody looked".
279
+ # A record with no `a` is that second fact (a spool from before
280
+ # arguments were read, or a caller that omitted the list).
281
+ args = self._values(rec["a"])
282
+ payload = {"args": args}
283
+ for v in args.values():
284
+ self._trunc(v)
285
+ self.values += redact_values.count(payload)
286
+ else:
287
+ payload = {"args": {}, "unread": ["locals"]}
288
+ parent = None
289
+ depth = 0
290
+ if rec["p"] is None:
291
+ # The truthful answer to "who called this?" when the frame was
292
+ # entered on an empty stack: Node's own machinery did.
293
+ payload["caller"] = "untraced"
294
+ else:
295
+ parent = self._frame(rec, rec["p"])
296
+ depth = parent.depth + 1
297
+ task = self._task(rec)
298
+ eid = self.w.add_event(rec["ts"], THREAD, "CALL", None, code_id, line,
299
+ payload, task)
300
+ self.events += 1
301
+ self._fps[task].update(rel, qualname, "CALL")
302
+ db_id = self.w.open_frame(parent.db_id if parent else None, code_id,
303
+ eid, depth, THREAD, kind)
304
+ self._frames[rec["f"]] = Frame(db_id, code_id, depth, rel, qualname)
305
+
306
+ def _on_return(self, rec: dict) -> None:
307
+ frame = self._close(rec)
308
+ task = self._task(rec)
309
+ # The RETURN rule reads the CALLEE's own name (B7). Only where the
310
+ # recorder did not: a 0.6.0 runtime read the same qualname off the
311
+ # same FILE record, and running it again here would digest the
312
+ # marker it left.
313
+ value = rec["v"]
314
+ if not self._runtime_did_names:
315
+ value = redact_values.named_return(frame.qualname, value)
316
+ value = redact_values.value(value)
317
+ self._trunc(value)
318
+ payload = {"value": value, "outcome": "ok"}
319
+ eid = self.w.add_event(rec["ts"], THREAD, "RETURN", frame.db_id,
320
+ frame.code_id, None, payload, task)
321
+ self.values += redact_values.count(payload)
322
+ self.events += 1
323
+ self._fps[task].update(frame.rel, frame.qualname, "RETURN")
324
+ self.w.close_frame(frame.db_id, eid, "return")
325
+
326
+ def _on_unwind(self, rec: dict) -> None:
327
+ """A frame left by throwing. The evidence is the frame row -- how it
328
+ ended is what the reader derives from `closed_by` and `unwind_exc`
329
+ -- so no event is written and nothing enters the fingerprint."""
330
+ frame = self._close(rec)
331
+ exc = redact_values.exc(rec["x"])
332
+ self._trunc(exc)
333
+ self.w.close_frame(frame.db_id, None, "unwind", exc)
334
+ self.values += redact_values.count_capture(exc)
335
+
336
+ def _on_line(self, rec: dict) -> None:
337
+ """One completed statement of a focused function.
338
+
339
+ `d` is what the statement wrote and `u` the names the transform
340
+ knows are out of scope at it. `u` is written by the runtime only
341
+ when there IS such a name, and it is copied on the same terms: an
342
+ empty `unbound` beside empty deltas would read as "nothing went out
343
+ of scope here", which is a claim nobody made. Empty deltas WITH an
344
+ `unbound` list is a real row -- a loop head on the pass that ends
345
+ the loop -- and is never dropped for looking empty.
346
+
347
+ A LINE naming a frame that has closed is refused. The runtime's own
348
+ `line()` drops such a row before it is written (`rt.mjs`: "a frame
349
+ that has closed reports no statement"), so a spool carrying one was
350
+ edited or is corrupt, and attaching it to the closed frame anyway
351
+ would put a statement after that frame's RETURN.
352
+ """
353
+ frame = self._frame(rec, rec["f"])
354
+ if frame.closed:
355
+ raise ConversionError(
356
+ f"{self.spool.path}: a LINE names frame {rec['f']}, which "
357
+ "had already closed")
358
+ payload = {"deltas": self._values(rec["d"])}
359
+ if rec.get("u"):
360
+ # R5: an `unbound` NAME is never withheld. It is the name of a
361
+ # value the trace does not hold at all, so there is nothing to
362
+ # take, and taking the name would cost a reader the fact that
363
+ # the binding ended here.
364
+ payload["unbound"] = list(rec["u"])
365
+ for v in payload["deltas"].values():
366
+ self._trunc(v)
367
+ self.values += redact_values.count(payload)
368
+ self.w.add_event(rec["ts"], THREAD, "LINE", frame.db_id,
369
+ frame.code_id, rec["l"], payload, self._task(rec))
370
+ # No fingerprint update: a LINE is not causal, and a fingerprint
371
+ # that moved with capture depth could not compare a focused run
372
+ # with an unfocused one (spec section 4).
373
+ self.events += 1
374
+
375
+ def _on_yield(self, rec: dict) -> None:
376
+ frame = self._frame(rec, rec["f"])
377
+ self.w.add_event(rec["ts"], THREAD, "YIELD", frame.db_id,
378
+ frame.code_id, None,
379
+ {"awaiting": AWAITING[rec["k"]]}, self._task(rec))
380
+ self.events += 1
381
+
382
+ def _on_resume(self, rec: dict) -> None:
383
+ frame = self._frame(rec, rec["f"])
384
+ self.w.add_event(rec["ts"], THREAD, "RESUME", frame.db_id,
385
+ frame.code_id, None, {}, self._task(rec))
386
+ self.events += 1
387
+
388
+ # -- throw flow ---------------------------------------------------------
389
+
390
+ def _on_raise(self, rec: dict) -> None:
391
+ self._throw(rec, "RAISE")
392
+
393
+ def _on_handled(self, rec: dict) -> None:
394
+ self._throw(rec, "HANDLED")
395
+
396
+ def _throw(self, rec: dict, kind: str) -> None:
397
+ if rec["f"] is None:
398
+ # No frame to attach it to, so no event: the count is the only
399
+ # trace of it, read the way Rust's err_flow_outside_frames is.
400
+ # Nothing of it is stored, so nothing of it is ruled either --
401
+ # the rule runs where a text is WRITTEN (R10).
402
+ self._trunc(rec.get("x"))
403
+ self.outside_frames += 1
404
+ return
405
+ exc = redact_values.exc(rec["x"])
406
+ self._trunc(exc)
407
+ frame = self._frame(rec, rec["f"])
408
+ task = self._task(rec)
409
+ payload = {"exc": exc, "how": rec["how"]}
410
+ self.w.add_event(rec["ts"], THREAD, kind, frame.db_id, frame.code_id,
411
+ rec["l"], payload, task)
412
+ self.values += redact_values.count(payload)
413
+ self.events += 1
414
+ self._fps[task].update(frame.rel, frame.qualname, kind)
415
+
416
+ def _on_unhandled(self, rec: dict) -> None:
417
+ """A rejection nobody handled, as a meta entry.
418
+
419
+ Its message meets the same content rule every other stored message
420
+ does -- `meta` is as much of the trace as an event is -- and the
421
+ `redacted` mark travels with it, absent as everywhere else when
422
+ nothing was found.
423
+ """
424
+ exc = redact_values.exc(rec["x"])
425
+ self._trunc(exc)
426
+ entry = {"type": exc["type"], "msg": exc["msg"],
427
+ "serial": exc["serial"]}
428
+ if "redacted" in exc:
429
+ entry["redacted"] = exc["redacted"]
430
+ self.rejections.append(entry)
431
+ self.values += redact_values.count_capture(entry)
432
+
433
+ # -- lookups ------------------------------------------------------------
434
+
435
+ def _code(self, rec: dict) -> tuple[int, str, str, int, str]:
436
+ """`(code_id, rel, qualname, firstlineno, frame kind)` for a CALL.
437
+
438
+ Interned against the ABSOLUTE path, which is what `code_objects.file`
439
+ holds; `rel` travels beside it because the fingerprint hashes the
440
+ root-relative path instead (TRACE-FORMAT section 7).
441
+ """
442
+ key = (rec["file"], rec["c"])
443
+ cached = self._codes.get(key)
444
+ header = self._files.get(rec["file"])
445
+ if header is None:
446
+ raise ConversionError(
447
+ f"{self.spool.path}: a CALL names file {rec['file']}, which "
448
+ "no FILE record declared")
449
+ codes = header["codes"]
450
+ if not 0 <= rec["c"] < len(codes):
451
+ raise ConversionError(
452
+ f"{self.spool.path}: a CALL names site {rec['c']} of "
453
+ f"{header['rel']}, which declared {len(codes)}")
454
+ qualname, line, kind = codes[rec["c"]]
455
+ if cached is None:
456
+ cached = (self.w.intern_code(header["abs"], qualname, line),
457
+ header["rel"], qualname, line)
458
+ self._codes[key] = cached
459
+ return (*cached, kind)
460
+
461
+ def _frame(self, rec: dict, wire_id: int) -> Frame:
462
+ frame = self._frames.get(wire_id)
463
+ if frame is None:
464
+ raise ConversionError(
465
+ f"{self.spool.path}: a {rec['e']} names frame {wire_id}, "
466
+ "which no CALL opened")
467
+ return frame
468
+
469
+ def _close(self, rec: dict) -> Frame:
470
+ frame = self._frame(rec, rec["f"])
471
+ if frame.closed:
472
+ raise ConversionError(
473
+ f"{self.spool.path}: a {rec['e']} closes frame {rec['f']}, "
474
+ "which had already closed")
475
+ frame.closed = True
476
+ return frame
477
+
478
+ def _task(self, rec: dict) -> int | None:
479
+ task = rec["t"]
480
+ if task is not None and task not in self._fps:
481
+ raise ConversionError(
482
+ f"{self.spool.path}: a {rec['e']} names test {task}, which no "
483
+ "TASK record opened")
484
+ return task
485
+
486
+ def _values(self, captures: dict) -> dict:
487
+ """Rule v1 over one CALL's arguments or one LINE's deltas.
488
+
489
+ The NAME half runs only where the RECORDER did not (B2): a 0.6.0
490
+ runtime took every firing name at the writer under its own key and
491
+ knobs, and running the rule again here would digest the marker it
492
+ left and overrule that recording's knobs with today's environment.
493
+
494
+ The CONTENT half runs on EVERY path (B9): it is idempotent -- the
495
+ marker holds none of the shapes it looks for -- so it changes
496
+ nothing on a scanned text and takes the span out of an unscanned
497
+ one. `value` is also what passes an already-taken capture through.
498
+ """
499
+ if self._runtime_did_names:
500
+ return {n: redact_values.value(c) for n, c in captures.items()}
501
+ return {n: redact_values.value(redact_values.named(n, c))
502
+ for n, c in captures.items()}
503
+
504
+ def _trunc(self, obj) -> None:
505
+ """Count every way this capture says it is a prefix.
506
+
507
+ The flags are two of the three. The third is blind spot 36: node's
508
+ `util.inspect` cuts a string at its own 100-character cap long
509
+ before the 200-byte wire cap looks at the rendering, so `trunc` is
510
+ `false` and the only evidence is the `... N more characters` tail
511
+ OUTSIDE the closing quote. `is_clipped` is what tells that from a
512
+ string whose CONTENT ends the same way -- one rule, in the module
513
+ `watch` and `flow` already read these texts with.
514
+ """
515
+ if isinstance(obj, dict):
516
+ self.truncated += bool(obj.get("trunc"))
517
+ self.truncated += bool(obj.get("type_trunc"))
518
+ v = obj.get("v")
519
+ if obj.get("k") == "dbg" and isinstance(v, str):
520
+ self.truncated += is_clipped(v)
521
+
522
+ # -- finalize -----------------------------------------------------------
523
+
524
+ def _fingerprints(self) -> None:
525
+ """One thread row and one row per test, zero counts included.
526
+
527
+ A zero-count thread row is a fact with content -- this container ran
528
+ traced code, all of it inside tests -- and is not the same fact as
529
+ having no row, which every reader takes to mean nothing ran here.
530
+ """
531
+ thread = self._fps[None]
532
+ self.w.write_fingerprint(THREAD, thread.hexdigest(), thread.count)
533
+ self.w.write_task_fingerprints(
534
+ [(tid, self._fps[tid].hexdigest(), self._fps[tid].count)
535
+ for tid in self.tasks])
536
+
537
+ def _meta(self) -> dict:
538
+ boot = self.spool.boot
539
+ env, hashed, redaction = self._redaction()
540
+ meta = {
541
+ "run_id": self.run_id,
542
+ "argv": boot["argv"],
543
+ "cwd": boot["cwd"],
544
+ "env": env,
545
+ "env_hash": hashed,
546
+ "redaction": redaction,
547
+ "start_ts": boot["startTs"],
548
+ "end_ts": self._end_ts(),
549
+ "exit_status": None,
550
+ "exit_status_basis": "unwitnessed",
551
+ "main_thread_ident": THREAD,
552
+ "fingerprint_basis": "per-task",
553
+ "truncated_count": self.truncated,
554
+ "source_hashes": self.source_hashes,
555
+ "recorder": self._recorder(),
556
+ "lang": LANG,
557
+ "capabilities": {**CAPABILITIES,
558
+ **(self.spool.boot.get("capabilities") or {})},
559
+ "caps": dict(CAPS),
560
+ "incomplete": self.spool.exit is None,
561
+ }
562
+ if self.spool.exit is not None:
563
+ # Present only where the container lived long enough to say it.
564
+ # An absent key is a container that never got to observe its own
565
+ # ending, which is not the same fact as one that ended at 0.
566
+ meta["exit_self_reported"] = {
567
+ "code": self.spool.exit.get("code"),
568
+ "signal": self.spool.exit.get("signal"),
569
+ }
570
+ meta.update(self._container_meta())
571
+ meta.update(self._invocation_meta())
572
+ if self._truncation:
573
+ meta.update(self._truncation)
574
+ return meta
575
+
576
+ def _redaction(self) -> tuple[dict, str, dict]:
577
+ """(the environment to store, its hash, the `redaction` object).
578
+
579
+ Two paths, and which one a spool takes is decided by whether the
580
+ RECORDER already ran rule v1.
581
+
582
+ A BOOT that carries `redaction` is `sensorium-ts` 0.5.0 or later and
583
+ its word is what the trace says, carried through with the two keys
584
+ only this converter can fill in -- `env`, the name -> digest table
585
+ the runtime wrote beside it, and `by`, the last hand that applied
586
+ the rule. The stored environment and its hash are the recorder's and
587
+ are NOT recomputed: the runtime hashed what it wrote, and a second
588
+ hash taken here could only differ by being wrong. `mode: "off"`
589
+ passes through exactly as written, two keys and no more, because an
590
+ `env` table on an object whose mode is off would be a table of
591
+ nothing at all -- and so does any mode this converter does not know.
592
+
593
+ A BOOT that carries none is 0.4.0 or earlier, and holds the whole
594
+ launching environment in plaintext; a converter that passed one
595
+ through would write today's trace with yesterday's secrets in it.
596
+ The rule runs HERE instead, under the STORE's key and `by:
597
+ "converter"`, and `env_hash` is recomputed because the environment
598
+ being hashed has changed.
599
+
600
+ NO KNOBS on that path. `SENSORIUM_REDACT_NAMES` and
601
+ `SENSORIUM_REDACT_ALLOW` are properties of a recording, and this
602
+ converter is a different process on a possibly different day --
603
+ reading its own environment for them would let a shell that happens
604
+ to carry one rewrite what an old recording is said to have been made
605
+ under. An old recording was made under none, and that is what the
606
+ object below records.
607
+ """
608
+ boot = self.spool.boot
609
+ recorded = boot.get("redaction")
610
+ if recorded:
611
+ if isinstance(recorded, dict) and recorded.get("mode") == "on":
612
+ recorded = {**recorded, "env": boot.get("envRedaction") or {},
613
+ "by": self._by(), "values": self.values}
614
+ return boot["env"], boot["envHash"], recorded
615
+ key = redact.Key.load(paths.trace_root())
616
+ knobs = redact.Knobs(False, frozenset(), frozenset())
617
+ stored, table = redact.env(boot["env"], key, knobs)
618
+ return (stored, env_hash(stored),
619
+ {**redact.meta(key, knobs, table, by="converter"),
620
+ "values": self.values})
621
+
622
+ def _by(self) -> str:
623
+ """Whose rule the trace records (B2): the LAST hand to apply it.
624
+
625
+ A 0.5.0 spool's environment is the recorder's work and its captures
626
+ are this converter's; one word cannot say both, and the later hand
627
+ is the one whose key the digests are under.
628
+ """
629
+ return "recorder" if self._runtime_did_names else "converter"
630
+
631
+ def _container_meta(self) -> dict:
632
+ boot = self.spool.boot
633
+ meta = {
634
+ "pid": boot["pid"],
635
+ "ppid": boot["ppid"],
636
+ "thread_id_os": boot["threadId"],
637
+ "is_main_thread": boot["isMainThread"],
638
+ "node": boot["node"],
639
+ "wire": boot["wire"],
640
+ "task_name_conflicts": self.conflicts,
641
+ "unhandled_rejections": self.rejections,
642
+ "throw_flow_outside_frames": self.outside_frames,
643
+ }
644
+ if self.counter_ran or self.inv.harness == "vitest":
645
+ # Written only where somebody counted (R38). The setup file is
646
+ # vitest's, and its FILE_START or SEEN records are the evidence
647
+ # that it ran; a vitest invocation whose file registered no test
648
+ # at all still counted, and its zero is a measurement. Under
649
+ # `node --test` there is no setup file and no counter, and the
650
+ # key is ABSENT -- "nobody counted" and "counted none" are
651
+ # different facts, and only one of them can be subtracted from
652
+ # the task count.
653
+ meta["tests_seen"] = self.tests_seen
654
+ if len(self.file_starts) == 1:
655
+ meta["test_file"] = self.file_starts[0]
656
+ elif self.file_starts:
657
+ meta["test_files"] = self.file_starts
658
+ if len(self.environments) == 1:
659
+ meta["environment"] = next(iter(self.environments))
660
+ if self.bases:
661
+ meta["task_name_basis"] = (self.bases.pop() if len(self.bases) == 1
662
+ else "mixed")
663
+ return meta
664
+
665
+ def _invocation_meta(self) -> dict:
666
+ meta = {
667
+ "invocation": self.inv.invocation,
668
+ "harness": self.inv.harness,
669
+ "harness_args": self.inv.harness_args,
670
+ "driver_version": self.inv.driver_version,
671
+ }
672
+ # Plan P9. Every `rel` in this trace -- the fingerprint's paths, the
673
+ # test file, a `focus_matched` entry -- was made relative to this
674
+ # directory, and a reader on another box cannot re-anchor any of
675
+ # them without it. Unconditional: the driver always knew it.
676
+ meta["root"] = self.inv.root
677
+ # Design section 2.2, and a different fact from either of its
678
+ # neighbours: `cwd` is the CONTAINER's, which for a vitest worker is
679
+ # wherever the pool started it, and `root` is the PLAN's. The
680
+ # harness command's relative arguments -- `vitest run src/fog` --
681
+ # are relative to neither; they are relative to where the person
682
+ # typed the command, which is what a re-run has to reproduce.
683
+ # Unconditional: the driver always knew it, and has always written
684
+ # it into the record as `cwd`.
685
+ meta["harness_cwd"] = self.inv.cwd
686
+ if self.inv.refocus_of:
687
+ # Written only where `refocus` launched this run. An absent key
688
+ # is a command a person typed, which is what `info` and `runs`
689
+ # both branch on; `refocus_of: null` would be a re-run of
690
+ # nothing.
691
+ meta["refocus_of"] = self.inv.refocus_of
692
+ if self.inv.focus:
693
+ # Both, because they answer different questions. `focus` is what
694
+ # was TYPED, which is what its author recognises; `focus_matched`
695
+ # is what it selected, which is what says whether the spelling
696
+ # meant what they thought. Written only when there was a focus:
697
+ # an empty list is a run that focused nothing, and no key at all
698
+ # is a run nobody focused -- `info` prints the two differently,
699
+ # and every unfocused TypeScript run is the second.
700
+ meta["focus"] = list(self.inv.focus)
701
+ meta["focus_matched"] = list(self.inv.focus_matched)
702
+ if self.inv.resolver_wall_s is not None:
703
+ # What resolving them cost, carried through so an instrument
704
+ # can time the resolver without timing the driver around it.
705
+ # Guarded separately from the block: a spool directory
706
+ # written before the field existed has the focus and not
707
+ # the cost, and an absent measurement is not a zero one.
708
+ meta["resolver_wall_s"] = self.inv.resolver_wall_s
709
+ if self.inv.command:
710
+ # The command as typed, which is the only one the reader may
711
+ # print (R26). Omitted when the spool's record predates the
712
+ # field, and the readers then fall back to what they said
713
+ # before -- an absent key is a record that was never written,
714
+ # not a run that was started by nothing.
715
+ meta["harness_command"] = list(self.inv.command)
716
+ if self.inv.vitest is not None:
717
+ meta["vitest"] = self.inv.vitest
718
+ if self.harness is not None:
719
+ meta["harness_exit"] = self.harness.meta()
720
+ if "files_transformed" in self.tally:
721
+ meta["files_transformed"] = self.tally["files_transformed"]
722
+ meta["transform_excluded"] = self.tally.get("excluded", {})
723
+ if "functions_focused" in self.tally:
724
+ # R22, and the same rule as its neighbour: written only where
725
+ # somebody counted. A tally written by a transform that predates
726
+ # the key carries no zero, and a zero invented here would say
727
+ # the focus selected nothing -- which is a run the driver would
728
+ # have refused before spawning anything.
729
+ meta["functions_focused"] = self.tally["functions_focused"]
730
+ return meta
731
+
732
+ def _end_ts(self) -> float:
733
+ """Wall-clock seconds at the end of the recording.
734
+
735
+ With an EXIT record the container read its own clock and said so.
736
+ Without one it was killed, and the last thing it managed to write is
737
+ the last thing that can be dated: the monotonic distance from BOOT
738
+ to that record, added to BOOT's wall clock. That is an estimate of
739
+ when the RECORDING ended, which is all `info` prints it as -- not a
740
+ claim about when the process died.
741
+ """
742
+ if self.spool.exit is not None:
743
+ return self.spool.exit["endTs"]
744
+ boot = self.spool.boot
745
+ if self.last_ts is None:
746
+ return boot["startTs"]
747
+ return boot["startTs"] + (self.last_ts - boot["ts"]) / 1e9
748
+
749
+ def _recorder(self) -> str:
750
+ """Who wrote the spool (R5). BOOT names its own writer, and that is
751
+ the authority; the driver's reading of the package version is the
752
+ fallback for a spool old enough not to carry one."""
753
+ version = self.spool.boot.get("version")
754
+ if version:
755
+ return f"sensorium-ts {version}"
756
+ return self.inv.recorder
757
+
758
+
759
+ def relative(path: str, root: str) -> str:
760
+ """`path` under `root`, or `path` unchanged when it is not under it.
761
+
762
+ Never `../..`: a file outside the project root is named absolutely,
763
+ because a relative path that climbs out of the root is not something a
764
+ reader on another box can resolve, and pretending otherwise would make
765
+ two different files look like one.
766
+ """
767
+ root = root.rstrip("/")
768
+ if path == root:
769
+ return "."
770
+ prefix = root + "/"
771
+ if path.startswith(prefix):
772
+ return path[len(prefix):]
773
+ return path
774
+
775
+
776
+ def mint_run_id(start_ts: float, token: str) -> str:
777
+ """`YYYYMMDD-HHMMSS-xxxxxx`, stamped with the container's OWN start.
778
+
779
+ Not the conversion's clock: every trace of one invocation then sorts
780
+ under the invocation it belongs to, and `runs` groups what actually ran
781
+ together rather than what happened to convert together.
782
+ """
783
+ return time.strftime("%Y%m%d-%H%M%S", time.localtime(start_ts)) + "-" + token