sensorium-trace 0.18.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,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)
|