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,778 @@
1
+ """Value provenance: where a value was seen, and what consumed it.
2
+
3
+ WHAT THIS COMMAND CLAIMS
4
+ ------------------------
5
+ ``--value`` lists every recorded capture that compares EQUAL to a literal.
6
+ ``--object`` lists every recorded capture at one memory address with one type.
7
+ Both are identity-based lineage over what was captured, never true dataflow
8
+ analysis: nothing here proves that one sighting produced another. Two calls
9
+ that both received 1800 may have got it from the same place or from nowhere
10
+ near each other -- the trace records values, not the edges between them.
11
+
12
+ OBJECT IDENTITY, AND WHY IT IS ONLY ALMOST AN IDENTITY
13
+ -----------------------------------------------------
14
+ ``capture_value`` records ``id(obj)`` as ``oid``. That is a memory address,
15
+ and CPython recycles addresses. Measured in this project's own fixtures: three
16
+ dicts made and dropped in a plain loop share ONE address, and a ``Draft`` and
17
+ a ``Final`` instance alternate on one address four times in six lines of
18
+ entirely ordinary code. Matching on ``oid`` alone splices those unrelated
19
+ objects into a single lineage and prints it as one object's story -- the worst
20
+ failure this command can have, because the output looks exactly like a correct
21
+ answer.
22
+
23
+ So identity here is ``(oid, type)``, never ``oid`` alone. An object's type is
24
+ fixed for its life, so the pair costs nothing and it separates the most common
25
+ false splice. It is still not an identity, and the header says so on every run
26
+ rather than leaving it to this docstring.
27
+
28
+ Task 11 solved the same problem exactly for exceptions, by having the tracer
29
+ mint a monotonic serial while holding a strong reference to the object. That
30
+ does not transfer here: it works because an in-flight exception is one object
31
+ the recorder can afford to retain, bounded at 64 per thread. ``flow`` would
32
+ have to retain every object the program touches. So ``flow`` is honest instead
33
+ of exact.
34
+
35
+ WHAT THE TRACE CAN STILL CORROBORATE
36
+ ------------------------------------
37
+ Between two consecutive sightings of one ``(oid, type)`` this reports what the
38
+ trace supports, and only that:
39
+
40
+ * ADDRESS REUSED -- some capture strictly in between records a DIFFERENT
41
+ type at this same address. Two live objects never share an address, so the
42
+ earlier object was already freed by then: the sightings on either side are
43
+ provably different objects. That is a hard fact and it is printed loudly.
44
+
45
+ * NEW OBJECT -- a constructor for this type ran ON this address inside the
46
+ gap: a ``T.__init__`` whose receiver is here, or a ``T.__new__`` that
47
+ returned here. Ordinarily that means the object seen afterwards was born
48
+ at that moment, and it is the one signal that catches a same-type reuse,
49
+ which ADDRESS REUSED cannot see and a spanning binding actively hides. It
50
+ is measured, not hypothetical: a plain four-iteration loop building one
51
+ object per pass puts two of them on one address, and without this the
52
+ whole run reads as a single lineage with ``Node.__init__`` sitting
53
+ unremarked in the middle of it.
54
+
55
+ Only the RECEIVER counts, never another argument: ``Wrapper.__init__(
56
+ self, payload)`` passes an existing object into a constructor, and reading
57
+ that as "payload was born here" would split one real object's lineage and
58
+ assert two -- the mirror of the bug this catches.
59
+
60
+ It is reported as strong evidence rather than proof, because "re-running a
61
+ constructor on a live object is pathological" is false in one ordinary
62
+ idiom. Measured: the textbook caching ``__new__``
63
+
64
+ class Config:
65
+ _inst = None
66
+ def __new__(cls):
67
+ if cls._inst is None: cls._inst = super().__new__(cls)
68
+ return cls._inst
69
+ def __init__(self): self.n = 1
70
+
71
+ records ``Config.__new__`` returning ONE address twice and
72
+ ``Config.__init__`` running on that same live object twice, with
73
+ ``a is b`` true. Calling that two objects would be exactly the false
74
+ claim this command exists to avoid, so when the trace records a
75
+ ``__new__`` that can hand back a live instance of this type, the line says
76
+ the trace cannot tell rather than asserting a split. A metaclass
77
+ ``__call__`` doing the same is not detected and is named in the line's
78
+ residual instead.
79
+
80
+ * spanned by fN -- a recorded argument or local of a frame that was open
81
+ across the whole gap was bound to this address before it, and NO DIFFERING
82
+ CAPTURE of that name was recorded during it. A live frame's local holds a
83
+ strong reference, so for as long as the name really did hold the address
84
+ it could not have been recycled underneath it.
85
+
86
+ This is evidence, not proof, and the exact residual matters. The tracer
87
+ emits a LINE delta by comparing CAPTURES, not objects
88
+ (``tracer.py``: ``if prev.get(name) != cap``). A capture carries the
89
+ address, so rebinding a name to a different object almost always changes
90
+ it -- but rebinding to a NEW object that took the same address and has
91
+ equal content produces an identical capture and therefore NO delta and no
92
+ LINE event at all. A loop that frees and rebuilds an equal object reaches
93
+ that in ordinary code, and ADDRESS REUSED cannot catch it because the type
94
+ is the same. ``--window`` can also gate LINE recording off for part of a
95
+ frame's life. So "no differing capture recorded" is exactly what is
96
+ claimed, and the header caveat says what it does not rule out. A frame
97
+ with no line capture at all is weaker still, and its line says so.
98
+
99
+ * unwitnessed -- none of the above. Nothing in the trace holds the address
100
+ across the gap, so the object may have died there and the later sighting
101
+ may be a different object at the same address. These are counted and named
102
+ in the footer rather than smoothed over.
103
+
104
+ Ranked in that order, strongest evidence first: a proven reuse outranks a
105
+ constructor, and either outranks a binding -- a binding that appears to span a
106
+ constructor is precisely the case where the binding is wrong.
107
+
108
+ Only top-level name bindings count as holders. A container captured holding the
109
+ object is a real reference too, but the trace does not record whether that
110
+ container was mutated in between, so it is not used as evidence.
111
+
112
+ WHAT IS SEARCHED
113
+ ----------------
114
+ CALL args, RETURN values and LINE local deltas -- every place a value is
115
+ captured. The command searches whichever of those this trace recorded.
116
+ ``capabilities.line: false`` is the statement tier, not a reason to ignore
117
+ a RETURN value or a CALL argument an unfocused Rust or TypeScript run still
118
+ wrote. The ``unbound`` names on a LINE event are deliberately NOT searched:
119
+ they name locals that went out of scope at that step, and listing one as a
120
+ sighting would assert a binding that had just ended.
121
+
122
+ A capture can be smaller than the value it stands for: over-cap containers,
123
+ depth-capped containers (which carry no ``sample`` key at all) and clipped
124
+ strings all carry ``trunc``. Those parts were never recorded and cannot be
125
+ searched, so the footer says how many were passed over instead of implying the
126
+ list is complete. A clipped string is never reported as equal to anything: the
127
+ real string is strictly longer than what was recorded, so it cannot be equal to
128
+ the literal it was compared against.
129
+ """
130
+ import shlex
131
+ from dataclasses import dataclass
132
+
133
+ from sensorium import paths
134
+ from sensorium.exit import ANSWERED, BAD_CALL, NEGATIVE, UNSETTLED
135
+ from sensorium.query.caps import none_status, print_incomplete, require
136
+ from sensorium.query.dbg_dialects import for_trace
137
+ from sensorium.query.fmt import fmt_value, parse_eref
138
+ # The printing half, split out at this file's 800-line ceiling.
139
+ # Re-exported so `flow_cmd.<name>` keeps resolving: these are one
140
+ # command's internals across two files, not separate modules with
141
+ # surfaces of their own.
142
+ from sensorium.query.flow_report import ( # noqa: F401
143
+ EXACT_CONTINUITY, ROLES_SEARCHED, _MAX_NAMED_GAPS, _notes,
144
+ _print_footer, _print_rows, continuity_line, page_gaps)
145
+ from sensorium.query.flow_values import ( # noqa: F401 (re-exported)
146
+ CONTAINER_KINDS, ObjTarget, _walk, find_in_value, matches,
147
+ parse_literal)
148
+ from sensorium.query.help import LIMIT_HELP, RUN_HELP
149
+ from sensorium.query.rust_debug import debug_text
150
+ from sensorium.query.vocab import terms
151
+ from sensorium.store.reader import Trace
152
+
153
+ IDENTITY_CAVEAT = (
154
+ "identity-based lineage, not true dataflow analysis",
155
+ "object identity is the memory address plus type; CPython recycles "
156
+ "addresses,",
157
+ "so a sighting after the object was freed may be a different object that "
158
+ "reused it",
159
+ "a 'spanned by' line below is evidence, not proof: local deltas compare "
160
+ "captures, so a name",
161
+ "rebound to a new object at the same address with equal content records "
162
+ "no change at all",
163
+ )
164
+ #: What the header says instead where the recorder minted the identity
165
+ #: itself. A serial comes from a `WeakMap`, once per object, and is never
166
+ #: reused, so there is no recycling to hedge against and nothing for the gap
167
+ #: analysis to corroborate -- printing the caveat above over it would
168
+ #: understate what the recording holds. The lineage caveat stays: an exact
169
+ #: identity still says nothing about which sighting produced which.
170
+ SERIAL_CAVEAT = (
171
+ "identity is a per-object serial minted once and never reused: every "
172
+ "sighting is the same object",
173
+ "captured-value lineage, not dataflow analysis: the trace records "
174
+ "values, not the edges between them",
175
+ )
176
+ _CAVEATS = {"address": IDENTITY_CAVEAT, "serial": SERIAL_CAVEAT}
177
+ _MAX_OTHER_REFS = 5
178
+ _CTORS = (".__init__", ".__new__")
179
+
180
+
181
+ @dataclass(frozen=True)
182
+ class Unresolved:
183
+ """Why `--object` named nothing, and what the reader should do next.
184
+
185
+ The status travels WITH the message, for the reason `frame._resolve`
186
+ gives: the two say the same thing, and only the resolver knows which of
187
+ the two it is saying. Deciding it in `run` would mean matching on the
188
+ message text, and the text is rewritten whenever it can be made clearer.
189
+
190
+ Carried only on FAILURE, and deliberately: `--object` resolving is not
191
+ yet an answer. Whether this flow says yes or no is the sightings count,
192
+ which is not known until the scan below has run -- so a success status
193
+ handed back from here would be a constant nothing reads, which is the
194
+ shape that left `frame`'s two success statuses dead until a review
195
+ caught them.
196
+ """
197
+ message: str
198
+ status: int
199
+
200
+
201
+ @dataclass(frozen=True)
202
+ class Sighting:
203
+ event: object
204
+ labels: tuple # ("arg items[1].grams", "return", ...)
205
+
206
+
207
+ @dataclass(frozen=True)
208
+ class Binding:
209
+ """A name recorded as holding the target address over [start, end)."""
210
+ frame_id: int
211
+ name: str
212
+ start: int
213
+ end: int
214
+ lines: bool # the frame recorded LINE events at all
215
+
216
+
217
+ @dataclass(frozen=True)
218
+ class Gap:
219
+ a: int
220
+ b: int
221
+ reuse: tuple | None # (event id, the other type seen at this address)
222
+ born: tuple | None # (event id, ctor qualname, caching __new__?)
223
+ held: Binding | None
224
+
225
+
226
+ def roles(e) -> list[tuple[str, dict]]:
227
+ """The (role, capture) pairs an event records.
228
+
229
+ LINE `unbound` names are not roles: they name locals that went OUT of
230
+ scope at this step, and a sighting is a claim about a live binding.
231
+ """
232
+ p = e.payload or {}
233
+ if e.kind == "CALL":
234
+ return [(f"arg {n}", v) for n, v in p.get("args", {}).items()]
235
+ if e.kind == "RETURN":
236
+ v = p.get("value")
237
+ return [("return", v)] if v is not None else []
238
+ if e.kind == "LINE":
239
+ return [(f"local {n}", v) for n, v in p.get("deltas", {}).items()]
240
+ return []
241
+
242
+
243
+ def scan(events, target, write=debug_text) -> tuple[list[Sighting],
244
+ int, int, int]:
245
+ """(sightings, events searched, captures searched, truncated captures)."""
246
+ found: list[Sighting] = []
247
+ searched = seen = trunc = 0
248
+ for e in events:
249
+ pairs = roles(e)
250
+ if pairs:
251
+ searched += 1
252
+ labels = []
253
+ for role, v in pairs:
254
+ for path, cap in _walk(v):
255
+ seen += 1
256
+ if cap.get("trunc"):
257
+ trunc += 1
258
+ if matches(cap, target, write):
259
+ labels.append(role + path)
260
+ if labels:
261
+ found.append(Sighting(e, tuple(labels)))
262
+ return found, searched, seen, trunc
263
+
264
+
265
+ class Index:
266
+ """Every event read once, plus the lookups the gap analysis needs."""
267
+
268
+ def __init__(self, trace) -> None:
269
+ self.trace = trace
270
+ # Read once, here, so every search this index feeds spells a
271
+ # literal the way THIS recorder's formatter would.
272
+ self.dialect = for_trace(trace)
273
+ self.events = trace.events()
274
+ self.by_id = {e.id: e for e in self.events}
275
+ self.by_frame: dict[int, list] = {}
276
+ for e in self.events:
277
+ if e.frame_id is not None:
278
+ self.by_frame.setdefault(e.frame_id, []).append(e)
279
+ self.last_id = self.events[-1].id if self.events else 0
280
+ self.has_line = any(e.kind == "LINE" for e in self.events)
281
+ self.incomplete = bool(trace.meta.get("incomplete"))
282
+
283
+
284
+ def _frame_end(idx: Index, f) -> int:
285
+ """The first event id at which `f` is no longer known to be open.
286
+
287
+ An unwound frame records no end event, so the last event recorded inside
288
+ it is used: that is a lower bound on how long it lived, which understates
289
+ the frame's reach rather than overstating what it can witness.
290
+ """
291
+ if f.return_event_id is not None:
292
+ return f.return_event_id + 1
293
+ if f.closed_by is None:
294
+ return idx.last_id + 1 # never closed: open to the end
295
+ evs = idx.by_frame.get(f.id, ())
296
+ return (evs[-1].id if evs else f.call_event_id) + 1
297
+
298
+
299
+ def bindings(idx: Index, target: ObjTarget) -> list[Binding]:
300
+ """Every recorded name binding that held the target address.
301
+
302
+ Only top-level bindings: a container that was captured holding the object
303
+ also holds a reference, but the trace cannot say it was never mutated.
304
+ """
305
+ out: list[Binding] = []
306
+ for f in idx.trace.frames():
307
+ evs = idx.by_frame.get(f.id, [])
308
+ lines = any(e.kind == "LINE" for e in evs)
309
+ steps: list[tuple[int, dict, tuple]] = []
310
+ call = idx.by_id.get(f.call_event_id)
311
+ if call is not None:
312
+ steps.append((call.id, (call.payload or {}).get("args", {}), ()))
313
+ for e in evs:
314
+ if e.kind == "LINE":
315
+ p = e.payload or {}
316
+ steps.append((e.id, p.get("deltas", {}),
317
+ tuple(p.get("unbound", ()))))
318
+ held: dict[str, int] = {}
319
+ for eid, binds, gone in steps:
320
+ for name, cap in binds.items():
321
+ if matches(cap, target, idx.dialect.write):
322
+ held.setdefault(name, eid)
323
+ elif name in held:
324
+ out.append(Binding(f.id, name, held.pop(name), eid, lines))
325
+ for name in gone:
326
+ if name in held:
327
+ out.append(Binding(f.id, name, held.pop(name), eid, lines))
328
+ end = _frame_end(idx, f)
329
+ for name, start in held.items():
330
+ out.append(Binding(f.id, name, start, end, lines))
331
+ return out
332
+
333
+
334
+ def address_reuses(idx: Index, target: ObjTarget) -> dict[int, str]:
335
+ """event id -> a DIFFERENT type captured at the target's address.
336
+
337
+ Two live objects never share an address, so any such capture proves the
338
+ target object had already been freed by then.
339
+ """
340
+ out: dict[int, str] = {}
341
+ for e in idx.events:
342
+ for _role, v in roles(e):
343
+ for _path, cap in _walk(v):
344
+ if (cap.get("k") in CONTAINER_KINDS
345
+ and cap.get("oid") == target.oid
346
+ and cap.get("type") != target.type):
347
+ out.setdefault(e.id, cap["type"])
348
+ return out
349
+
350
+
351
+ def constructions(trace, idx: Index, target: ObjTarget) -> dict[int, str]:
352
+ """event id -> the constructor recorded running ON the target's address.
353
+
354
+ A `T.__init__` whose RECEIVER is at this address, or a `T.__new__` that
355
+ RETURNED it. Only the receiver -- the first parameter, which is what
356
+ `capture_value` records first because the tracer walks `co_varnames` in
357
+ order. Any other argument is an existing object being handed *into* a
358
+ constructor (`Wrapper.__init__(self, payload)`), and reading that as
359
+ "payload was born here" would split one real object's lineage.
360
+
361
+ `__new__` is read from its RETURN, not its CALL: at call time the instance
362
+ does not exist yet and the first argument is the class.
363
+ """
364
+ out: dict[int, str] = {}
365
+ for e in idx.events:
366
+ if e.code_id is None:
367
+ continue
368
+ q = trace.code(e.code_id).qualname
369
+ p = e.payload or {}
370
+ if e.kind == "CALL" and q.endswith(".__init__"):
371
+ recv = next(iter((p.get("args") or {}).values()), None)
372
+ if recv is not None and matches(recv, target, idx.dialect.write):
373
+ out[e.id] = q
374
+ elif e.kind == "RETURN" and q.endswith(".__new__"):
375
+ if p.get("value") is not None and matches(p["value"], target,
376
+ idx.dialect.write):
377
+ out[e.id] = q
378
+ return out
379
+
380
+
381
+ def caching_new(trace, idx: Index, target: ObjTarget) -> bool:
382
+ """Whether this run defines a `__new__` that hands back instances of the
383
+ target's type -- the one ordinary idiom in which a constructor running on
384
+ a live object does NOT mean a new object.
385
+
386
+ Measured on the textbook caching singleton: `Config.__new__` returns one
387
+ address twice and `Config.__init__` then runs on that same live object
388
+ twice. Without this check the two would be reported as different objects,
389
+ which is the false claim this command exists to avoid.
390
+ """
391
+ for e in idx.events:
392
+ if e.kind != "RETURN" or e.code_id is None:
393
+ continue
394
+ if not trace.code(e.code_id).qualname.endswith(".__new__"):
395
+ continue
396
+ v = (e.payload or {}).get("value") or {}
397
+ if v.get("type") == target.type:
398
+ return True
399
+ return False
400
+
401
+
402
+ def gaps(sights: list[Sighting], binds: list[Binding], reuses: dict[int, str],
403
+ ctors: dict[int, str] = {}, cached: bool = False) -> list[Gap]:
404
+ out = []
405
+ for prev, nxt in zip(sights, sights[1:]):
406
+ a, b = prev.event.id, nxt.event.id
407
+ reuse = next(((eid, t) for eid, t in sorted(reuses.items())
408
+ if a < eid < b), None)
409
+ # `a < c <= b`, not `< b`: the constructor is very often the later
410
+ # SIGHTING itself -- `Node.__init__(self=Node#A)` is both a capture at
411
+ # the address and the proof that what is there now was just built. Its
412
+ # presence at `a` says nothing, since that is the object already seen.
413
+ born = None if reuse else next(
414
+ ((eid, q, cached) for eid, q in sorted(ctors.items())
415
+ if a < eid <= b), None)
416
+ held = None
417
+ if reuse is None and born is None:
418
+ # `end > b`, not `>=`: a binding observed ending exactly at the
419
+ # later sighting is not read as having held the address across
420
+ # the gap. It very likely did -- but that turns on what happened
421
+ # inside the single line that rebound it, which the trace does
422
+ # not record, and an under-claimed witness costs a hedge while an
423
+ # over-claimed one costs a false "same object".
424
+ cands = [x for x in binds if x.start <= a and x.end > b]
425
+ # A frame with line capture is the better witness of the two: a
426
+ # rebinding that CHANGED the capture would have been recorded
427
+ # there. It is not a guarantee -- an identical re-capture records
428
+ # nothing anywhere -- only strictly more than a frame that could
429
+ # not have recorded a rebinding at all.
430
+ held = min(cands, key=lambda x: (not x.lines, x.start),
431
+ default=None)
432
+ out.append(Gap(a, b, reuse, born, held))
433
+ return out
434
+
435
+
436
+ def _witness(g: Gap):
437
+ return (g.held.frame_id, g.held.name, g.held.start) if g.held else None
438
+
439
+
440
+ def held_line(h: Binding, a: int, b: int) -> str:
441
+ """What a covering binding supports -- stated as the fact it is.
442
+
443
+ Never "held by" and never "no rebinding recorded": both are literally
444
+ true of the trace and both read as affirmative continuity evidence, and a
445
+ reader skimming rows meets this line without the header. Deltas compare
446
+ captures,
447
+ so a name rebound to a new object at the same address with equal content
448
+ records nothing to see. What the trace supports is that no DIFFERING
449
+ capture of the name was recorded, and that is what is printed.
450
+ """
451
+ span = f"spanned by f{h.frame_id} across e{a}..e{b}: {h.name!r} bound " \
452
+ f"at e{h.start}"
453
+ if h.lines:
454
+ return (span + f", no differing capture of {h.name!r} recorded "
455
+ f"through e{b}")
456
+ return (span + f"; f{h.frame_id} has no line capture at all, so nothing "
457
+ f"there could have recorded a rebinding before e{b}")
458
+
459
+
460
+ def gap_lines(gs: list[Gap]) -> dict[int, str]:
461
+ """The annotation to print after sighting `i`, for the gaps worth one.
462
+
463
+ A run of consecutive gaps held by the SAME binding is one fact, not one
464
+ per gap: it is emitted once, at the end of the run, naming the whole span
465
+ it covers. Unwitnessed gaps get no line here -- there is nothing to say
466
+ about them beyond the count and the named list in the footer.
467
+ """
468
+ out: dict[int, str] = {}
469
+ for i, g in enumerate(gs):
470
+ if g.reuse:
471
+ eid, typ = g.reuse
472
+ out[i] = (f"ADDRESS REUSED between e{g.a} and e{g.b}: e{eid} "
473
+ f"captured a {typ} at this address -- two live objects "
474
+ "never share one, so these are different objects")
475
+ elif g.born:
476
+ eid, q, cached = g.born
477
+ out[i] = (
478
+ f"CONSTRUCTOR RAN between e{g.a} and e{g.b}: e{eid} is {q} on "
479
+ f"this address, but this run defines {q.rsplit('.', 1)[0]}"
480
+ ".__new__, which hands back instances of this type -- "
481
+ "a caching __new__ re-runs __init__ on a LIVE object, so "
482
+ "the trace cannot say a new one was born here"
483
+ if cached else
484
+ f"NEW OBJECT between e{g.a} and e{g.b}: e{eid} is {q} on this "
485
+ "address -- an object was constructed there, so these are "
486
+ "different objects unless a constructor was re-run on a live "
487
+ "one (a caching __new__ or metaclass __call__ does that)")
488
+ elif g.held:
489
+ start = i
490
+ while start > 0 and _witness(gs[start - 1]) == _witness(g):
491
+ start -= 1
492
+ # Keyed on where the run BEGINS, which is what collapses it: each
493
+ # further gap of the run overwrites the same entry, extending the
494
+ # span, and the line ends up announced once at the sighting that
495
+ # established the binding.
496
+ out[start] = held_line(g.held, gs[start].a, g.b)
497
+ return out
498
+
499
+
500
+ def resolve_object(trace, idx: Index, spec: str):
501
+ """(target, canonical ref, resolution note, `Unresolved` | None).
502
+
503
+ Which status each failure carries is the convention applied to what
504
+ went wrong. A reference the trace simply does not hold -- no such event,
505
+ no CALL of that qualname, that name not captured at that event -- is the
506
+ trace answering "no" about what was recorded (NEGATIVE); only a
507
+ recording that holds it can say otherwise. A spec that cannot name
508
+ anything, and a name whose recorded value is a primitive and so has no
509
+ identity to follow, are the CALL being wrong (BAD_CALL): the trace is
510
+ fine, the command has to change -- and the second one even says which
511
+ command to run instead (`--value`).
512
+ """
513
+ ref, sep, name = spec.rpartition(":")
514
+ if not sep or not ref or not name:
515
+ return None, None, None, Unresolved(
516
+ f"object spec must be e<id>:<name> or <qualname>:<name>; "
517
+ f"got {spec!r}", BAD_CALL)
518
+ note = None
519
+ if ref[0] == "e" and ref[1:].isdigit():
520
+ ev = idx.by_id.get(int(ref[1:]))
521
+ if ev is None:
522
+ return None, None, None, Unresolved(
523
+ f"no event {ref} in this trace", NEGATIVE)
524
+ else:
525
+ calls = [e for e in idx.events
526
+ if e.kind == "CALL" and e.code_id is not None
527
+ and trace.code(e.code_id).qualname == ref]
528
+ if not calls:
529
+ return None, None, None, Unresolved(
530
+ f"no CALL of {ref!r} was recorded", NEGATIVE)
531
+ ev = calls[0]
532
+ note = (f"resolved {spec!r} at e{ev.id} -- the first of {len(calls)} "
533
+ f"recorded CALL(s) of {ref}")
534
+ if len(calls) > 1:
535
+ others = [f"e{c.id}" for c in calls[1:1 + _MAX_OTHER_REFS]]
536
+ extra = len(calls) - 1 - len(others)
537
+ note += ("; others: " + ", ".join(others)
538
+ + (f" (+{extra} more)" if extra else ""))
539
+ v, at, err = _capture_at(trace, idx, ev, name)
540
+ if err:
541
+ # "not captured at eN": the event is real and the trace does not
542
+ # hold that name there. It answers, negatively, about the recording.
543
+ return None, None, None, Unresolved(err, NEGATIVE)
544
+ if at is not ev and note:
545
+ note += f"; its return is captured at e{at.id}"
546
+ if (v.get("redacted") or {}).get("by") == "name":
547
+ # BEFORE the primitive check, which a taken container would pass:
548
+ # the rule keeps `oid` and `type` (an address is a fact about the
549
+ # program), so the resolver would mint a target and follow an
550
+ # address whose occupant nobody recorded.
551
+ return None, None, None, Unresolved(
552
+ f"{name!r} at e{at.id} is redacted (by name) and has no "
553
+ f"identity or value to follow", BAD_CALL)
554
+ if v.get("k") not in CONTAINER_KINDS and "oid" not in v:
555
+ # A rendered capture carries `oid`/`type` when the recorder minted
556
+ # an identity for the value -- an object or a function, never a
557
+ # primitive -- so the two keys, and not the capture's kind, are
558
+ # what says whether there is an identity to follow here.
559
+ return None, None, None, Unresolved(
560
+ f"{name!r} at e{at.id} is a primitive ({fmt_value(v)}) and has no "
561
+ f"identity to follow; use --value {fmt_value(v)}", BAD_CALL)
562
+ if v.get("type") is None:
563
+ # The two keys are minted together by every recorder that mints
564
+ # either -- `record/capture.py` writes both for a container, and
565
+ # `dbg.mjs` sets both or neither -- so one without the other is a
566
+ # malformed capture, not a value with no identity. Refused by name,
567
+ # because a `KeyError` out of a query says nothing a reader can act
568
+ # on.
569
+ return None, None, None, Unresolved(
570
+ f"{name!r} at e{at.id} carries an oid and no type; the capture "
571
+ f"is not the shape 0.3.0 declares", BAD_CALL)
572
+ return ObjTarget(v["oid"], v["type"]), f"e{at.id}:{name}", note, None
573
+
574
+
575
+ def _capture_at(trace, idx: Index, ev, name: str):
576
+ """(capture, the event carrying it, error).
577
+
578
+ A qualname resolves to a CALL, which is where args live but never a
579
+ return value -- so `<qualname>:return` follows that activation's frame to
580
+ its RETURN rather than reporting the name as uncaptured.
581
+ """
582
+ p = ev.payload or {}
583
+ v = p.get("args", {}).get(name) or p.get("deltas", {}).get(name)
584
+ if v is not None:
585
+ return v, ev, None
586
+ if name == "return":
587
+ if p.get("value") is not None:
588
+ return p["value"], ev, None
589
+ ret = _return_of(trace, idx, ev)
590
+ if ret is not None and (ret.payload or {}).get("value") is not None:
591
+ return ret.payload["value"], ret, None
592
+ avail = list(p.get("args", {})) + list(p.get("deltas", {}))
593
+ where = (f"; captured there: {', '.join(avail)}" if avail
594
+ else "; that event captured no named values")
595
+ return None, ev, f"{name!r} is not captured at e{ev.id}{where}"
596
+
597
+
598
+ def _return_of(trace, idx: Index, ev):
599
+ """The RETURN event of the activation this CALL opened, if it returned."""
600
+ if ev.kind != "CALL":
601
+ return None
602
+ f = trace.frame_containing(ev.id)
603
+ if f is None or f.return_event_id is None:
604
+ return None
605
+ return idx.by_id.get(f.return_event_id)
606
+
607
+
608
+ def continue_cmd(args, ref: str | None, last: int) -> str:
609
+ """The exact command that shows the next page of *this* flow."""
610
+ sel = (f"--object={shlex.quote(ref)}" if ref is not None
611
+ else f"--value={shlex.quote(args.value)}")
612
+ return (f"sensorium flow {shlex.quote(args.run)} {sel} "
613
+ f"--limit {args.limit} --after e{last}")
614
+
615
+
616
+ def add_parser(sub) -> None:
617
+ p = sub.add_parser(
618
+ "flow", help="provenance of a value or an object",
619
+ description="`--value` follows a literal by equality through "
620
+ "captured arguments, locals and returns; `--object` "
621
+ "follows one identity from the event that captured "
622
+ "it; one of the two is required, and each refuses by "
623
+ "name what the recording did not capture.",
624
+ epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
625
+ p.add_argument("run", help=RUN_HELP)
626
+ g = p.add_mutually_exclusive_group(required=True)
627
+ g.add_argument("--value", default=None,
628
+ help="literal matched by equality; quote to force a "
629
+ "string, as in \"'1800'\"")
630
+ g.add_argument("--object", default=None,
631
+ help="e<id>:<name>, where <name> was captured at that "
632
+ "event (a CALL's argument, a LINE's local); or "
633
+ "<qualname>:<name>, which resolves to that "
634
+ "function's first CALL and so names one of its "
635
+ "ARGUMENTS -- plus <qualname>:return for what that "
636
+ "activation returned")
637
+ p.add_argument("--after", default=None, help="event ref to resume from")
638
+ p.add_argument("--limit", type=int, default=50,
639
+ help=LIMIT_HELP)
640
+ p.set_defaults(func=run)
641
+
642
+
643
+ def _header(trace, idx: Index, args) -> tuple:
644
+ """(target, canonical ref, header lines, `Unresolved` | None).
645
+
646
+ A failed resolution is passed through whole: this function adds a
647
+ header, never a judgement about why resolution failed.
648
+ """
649
+ if args.object is not None:
650
+ target, ref, note, err = resolve_object(trace, idx, args.object)
651
+ if err:
652
+ return None, None, None, err
653
+ head = [f"flow of object #{target.oid} ({target.type}) in "
654
+ f"{trace.path.stem}"]
655
+ # Strict, like `vocab.terms` itself: the third basis is `"none"`,
656
+ # and a recorder that records no identity refuses `--object`
657
+ # through `object_identity` before this line is reached, so a
658
+ # KeyError here means a caller built a `Trace` around the gate.
659
+ head += [" " + s for s in _CAVEATS[terms(trace).identity_basis]]
660
+ if note:
661
+ head.append(" " + note)
662
+ return target, ref, head, None
663
+ target = parse_literal(args.value)
664
+ # `--value` cannot fail to resolve: any literal is a legal target, and
665
+ # whether anything matched it is the sightings count's answer below.
666
+ return target, None, [
667
+ f"flow of {target!r} ({type(target).__name__}) in {trace.path.stem}",
668
+ " captured-value equality, not true dataflow analysis: the trace "
669
+ "records values, not the edges between them",
670
+ " searched over recorded captures (CALL arguments, RETURN values, "
671
+ "and LINE local deltas where this trace recorded them)"], None
672
+
673
+
674
+ def _is_capture(v) -> bool:
675
+ """A value `scan` can compare, as opposed to one the trace does not hold.
676
+
677
+ `None` is a missing payload key. `{"k": "unread"}` is the recorder
678
+ saying it did not capture the value, so it is not a sighting waiting
679
+ to be found. A truncated capture, a `dbg` rendering and a `none` were
680
+ recorded: a miss over them is an answer about this trace.
681
+ """
682
+ return isinstance(v, dict) and v.get("k") != "unread"
683
+
684
+
685
+ def _value_searchable(trace) -> bool:
686
+ """Whether `--value` has anything recorded to compare.
687
+
688
+ `capabilities.line` is the statement tier. An unfocused Rust or
689
+ TypeScript run leaves it false and still writes RETURN values and
690
+ CALL arguments, which `roles` already reads. Refusing through `line`
691
+ alone would refuse a question those captures answer. Search when any
692
+ of the three was recorded. Refuse only when line is declared absent
693
+ and no CALL argument, RETURN value, or LINE row is in the trace.
694
+
695
+ `declares("line")` is None on a pre-format-4 Python trace. Those are
696
+ searched, the same way `require` lets them through.
697
+ """
698
+ if trace.declares("line") is not False:
699
+ return True
700
+ for e in trace.events(kind=("CALL", "RETURN", "LINE")):
701
+ p = e.payload or {}
702
+ if e.kind == "LINE":
703
+ return True
704
+ if e.kind == "RETURN" and _is_capture(p.get("value")):
705
+ return True
706
+ args = p.get("args")
707
+ if (e.kind == "CALL" and isinstance(args, dict)
708
+ and any(_is_capture(v) for v in args.values())):
709
+ return True
710
+ return False
711
+
712
+
713
+ def run(args) -> int:
714
+ if args.limit < 1:
715
+ print(f"--limit must be >= 1 (got {args.limit}); "
716
+ "there is no useful zero-row page")
717
+ return BAD_CALL
718
+ after = parse_eref(args.after) if args.after else 0
719
+ trace = Trace.open(paths.find_trace(args.run))
720
+ # Ruling R13: an object flow needs `object_identity` and NOT `line`.
721
+ # An identity rides on every capture a recorder that mints one writes
722
+ # -- a RETURN value at the call tier, an argument and a statement's
723
+ # delta under a focus -- so refusing through `line` would refuse a
724
+ # question this recording answers. A value flow refuses only when
725
+ # nothing it can compare was recorded. The sentence is still
726
+ # `require`'s for `line`: the capability that is false, and nothing
727
+ # was checked, because there was nothing to check.
728
+ if args.object is not None:
729
+ refusal = require(trace, "object_identity", "flow --object")
730
+ elif not _value_searchable(trace):
731
+ refusal = require(trace, "line", "flow")
732
+ else:
733
+ refusal = None
734
+ if refusal:
735
+ print(f"REFUSED: {refusal}")
736
+ # Well formed command, readable trace, and what this search
737
+ # compares was not recorded. Re-recording is what changes it.
738
+ return UNSETTLED
739
+ idx = Index(trace)
740
+ target, ref, head, err = _header(trace, idx, args)
741
+ if err:
742
+ print(f"error: {err.message}")
743
+ return err.status
744
+ print_incomplete(trace, "what is missing below is not evidence about "
745
+ "the rest of the run")
746
+ for line in head:
747
+ print(line)
748
+
749
+ found, searched, seen, trunc = scan(idx.events, target, idx.dialect.write)
750
+ scope = [s for s in found if s.event.id > after]
751
+ shown = scope[:args.limit]
752
+ # Gaps are computed over EVERY sighting, then sliced to the page, so the
753
+ # one crossing the page boundary is not lost with --after. On a SERIAL
754
+ # basis none of it runs: every line it produces -- reused, born,
755
+ # spanned by, unwitnessed -- is evidence about whether two sightings
756
+ # are one object, and on a serial they are.
757
+ basis = terms(trace).identity_basis
758
+ exact = isinstance(target, ObjTarget) and basis == "serial"
759
+ all_gaps = (gaps(found, bindings(idx, target), address_reuses(idx, target),
760
+ constructions(trace, idx, target),
761
+ caching_new(trace, idx, target))
762
+ if isinstance(target, ObjTarget) and basis == "address"
763
+ else [])
764
+ counted, visible, lead = page_gaps(all_gaps, len(found) - len(scope),
765
+ len(shown))
766
+ _print_rows(trace, shown, gap_lines(visible), lead)
767
+ _print_footer(args, ref, idx, (len(found), searched, seen, trunc),
768
+ scope, shown, counted, after, exact)
769
+ # The status follows the `sightings:` line the footer just printed, and
770
+ # so is read over `scope` rather than `found`: what this invocation was
771
+ # asked for is the sightings after `--after`, and an empty page is that
772
+ # question answered "none". Reading `found` instead would answer 0 for a
773
+ # page that printed `sightings: 0`, about a run-wide total the caller
774
+ # did not ask for. The count line is already there for the zero case
775
+ # ("sightings: 0 event(s), 0 capture(s)"), so nothing is added to the
776
+ # output -- only the number the caller branches on changes. Whether an
777
+ # empty page is "none" or "the recording stopped" is `none_status`.
778
+ return ANSWERED if scope else none_status(trace)