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,199 @@
|
|
|
1
|
+
"""How many exception objects a thread remembers, and the per-thread tables
|
|
2
|
+
that remember them.
|
|
3
|
+
|
|
4
|
+
Split out of `tracer.py` at that file's 800-line ceiling. The retention bounds
|
|
5
|
+
and the two tables they bound are one subject -- the only place this recorder
|
|
6
|
+
holds a reference to the observed program's own objects -- and the module
|
|
7
|
+
docstring of `tracer.py` still states the contract they implement. `_RETAIN_MAX`
|
|
8
|
+
and `_CONTROL_RETAIN_MAX` are re-exported from `tracer.py` so the names the
|
|
9
|
+
suite already imports keep resolving.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
import threading
|
|
13
|
+
|
|
14
|
+
# How many exception objects one thread remembers. Every one of them is held
|
|
15
|
+
# by a strong reference and pins its traceback, so this is a memory bound on
|
|
16
|
+
# the recorder's influence, not a tuning knob: raising it links more stored
|
|
17
|
+
# re-raises and keeps more of the program's dead frames alive. Exceeding it is
|
|
18
|
+
# not a silent loss -- see the module docstring and exceptions_cmd.
|
|
19
|
+
_RETAIN_MAX = 64
|
|
20
|
+
|
|
21
|
+
# The same bound for CONTROL-FLOW exceptions thrown into a traced frame
|
|
22
|
+
# (GeneratorExit, StopIteration, StopAsyncIteration). They need a serial --
|
|
23
|
+
# `frame_state` calls a frame abandoned only when the RESUME's thrown serial
|
|
24
|
+
# EQUALS the unwind's -- but they are not exceptions any query links across a
|
|
25
|
+
# program: `_exc_event` records no row for them, so the only rows their serial
|
|
26
|
+
# can ever reach are that frame's own RESUME and unwind, written within a few
|
|
27
|
+
# events of each other. Minting them from the table above let 70 early-exit
|
|
28
|
+
# generator expressions -- `any(v > 0 for v in ...)`, ordinary code -- evict a
|
|
29
|
+
# stashed ValueError and degrade its later re-raise to "ambiguous". A small
|
|
30
|
+
# table of their own costs 16 held objects per thread and cannot touch the
|
|
31
|
+
# real one. It is not 1: a generator's cleanup can drop other generators, so
|
|
32
|
+
# several of these can be in flight at once.
|
|
33
|
+
_CONTROL_RETAIN_MAX = 16
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _is_control_flow(exc) -> bool:
|
|
37
|
+
"""True for the interpreter's own iterator/generator control-flow
|
|
38
|
+
exceptions, matched by TYPE IDENTITY.
|
|
39
|
+
|
|
40
|
+
A NAME match dropped any exception whose class merely happened to be
|
|
41
|
+
called ``StopIteration`` -- a user class shadowing the builtin, unrelated
|
|
42
|
+
to the iterator protocol -- with no RAISE, no HANDLED and no serial, so a
|
|
43
|
+
real caught exception surfaced as ``no exceptions recorded``. ``type(exc)``
|
|
44
|
+
is a C-level ``Py_TYPE`` read that cannot run a dunder; ``is`` (not
|
|
45
|
+
``in (...)``) because a hostile metaclass ``__eq__`` could raise inside a
|
|
46
|
+
membership test. When the type is anything else -- including one that lies
|
|
47
|
+
about its name -- the exception is RECORDED, never silently dropped.
|
|
48
|
+
"""
|
|
49
|
+
t = type(exc)
|
|
50
|
+
return t is StopIteration or t is StopAsyncIteration or t is GeneratorExit
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class _ExcRefs:
|
|
54
|
+
"""One thread's exception identity table -- and the only place this
|
|
55
|
+
recorder holds a reference to an exception object.
|
|
56
|
+
|
|
57
|
+
`serials` maps `id(exc)` -> `(exc, serial)`, insertion-ordered, capped at
|
|
58
|
+
`cap` (`_RETAIN_MAX` for a thread's real table, `_CONTROL_RETAIN_MAX` for
|
|
59
|
+
its control-flow side table). Holding the object is what makes `id()` a
|
|
60
|
+
sound key: the address cannot be recycled underneath us, so two distinct
|
|
61
|
+
exceptions can never alias onto one serial. Weak references were tried
|
|
62
|
+
first and are not an option at all -- `BaseException` does not support them
|
|
63
|
+
(`TypeError: cannot create weak reference to 'ValueError' object`), and
|
|
64
|
+
catching that error silently disabled the whole mechanism, which is the
|
|
65
|
+
kind of quiet fallback this project bans.
|
|
66
|
+
|
|
67
|
+
`last_exc` (the exception currently in flight) lives here too, so that
|
|
68
|
+
`clear` really does release everything this recorder is holding, on
|
|
69
|
+
whichever thread it is called for.
|
|
70
|
+
"""
|
|
71
|
+
__slots__ = ("last_exc", "serials", "minted", "cap", "source",
|
|
72
|
+
"__weakref__")
|
|
73
|
+
|
|
74
|
+
def __init__(self, cap: int = _RETAIN_MAX, source=None) -> None:
|
|
75
|
+
self.last_exc = None # exception currently in flight, if any
|
|
76
|
+
self.serials: dict[int, tuple] = {}
|
|
77
|
+
self.minted = 0 # monotonic per-thread serial source
|
|
78
|
+
self.cap = cap # how many objects this table remembers
|
|
79
|
+
# Where serials come from, when not from this table itself. The
|
|
80
|
+
# control-flow table mints from the MAIN one so a thread never issues
|
|
81
|
+
# one number twice: two tables counting separately would eventually
|
|
82
|
+
# give a GeneratorExit and a real exception the same serial, and a
|
|
83
|
+
# frame's `unwind_exc` would then match rows belonging to neither.
|
|
84
|
+
# A plain (one-way) reference, never a back-pointer: a cycle between
|
|
85
|
+
# a thread's two tables would keep both -- and every exception they
|
|
86
|
+
# hold -- alive past the thread, waiting for the cycle collector.
|
|
87
|
+
self.source = source
|
|
88
|
+
|
|
89
|
+
def serial_of(self, exc) -> int | None:
|
|
90
|
+
"""This thread's serial for `exc`, or None if it holds none.
|
|
91
|
+
|
|
92
|
+
`id(exc)` alone is a sound key here, with no `is` re-check needed:
|
|
93
|
+
object and serial go into the table together and only ever leave
|
|
94
|
+
together, so while a key is present this table holds that object and
|
|
95
|
+
no other object can have its address.
|
|
96
|
+
"""
|
|
97
|
+
held = self.serials.get(id(exc))
|
|
98
|
+
return held[1] if held is not None else None
|
|
99
|
+
|
|
100
|
+
def identify(self, exc) -> int:
|
|
101
|
+
"""`exc`'s serial, minting and remembering one if it is new."""
|
|
102
|
+
serial = self.serial_of(exc)
|
|
103
|
+
if serial is not None:
|
|
104
|
+
return serial
|
|
105
|
+
src = self if self.source is None else self.source
|
|
106
|
+
src.minted += 1
|
|
107
|
+
serial = src.minted
|
|
108
|
+
self.serials[id(exc)] = (exc, serial)
|
|
109
|
+
while len(self.serials) > self.cap:
|
|
110
|
+
oldest, held = next(iter(self.serials.items()))
|
|
111
|
+
del self.serials[oldest]
|
|
112
|
+
if held[0] is self.last_exc:
|
|
113
|
+
# Never forget what is arming or propagating right now. An
|
|
114
|
+
# exception paused inside a `finally` is not that -- its
|
|
115
|
+
# EXCEPTION_HANDLED already cleared `last_exc` -- so a long
|
|
116
|
+
# enough cleanup can push it out, and the query side hedges
|
|
117
|
+
# rather than reading the fresh serial as another exception.
|
|
118
|
+
self.serials[oldest] = held
|
|
119
|
+
return serial
|
|
120
|
+
|
|
121
|
+
def clear(self) -> None:
|
|
122
|
+
self.last_exc = None
|
|
123
|
+
self.serials.clear()
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
class _TLS(threading.local):
|
|
127
|
+
"""Per-thread recorder state.
|
|
128
|
+
|
|
129
|
+
`threading.local` calls `__init__` again on every thread that touches the
|
|
130
|
+
object -- which is how each thread gets a fresh `thread_serial` and how its
|
|
131
|
+
`_ExcRefs` gets registered with the tracer. A recycled OS thread id is a
|
|
132
|
+
NEW Python thread with its own `threading.local` storage, so it runs this
|
|
133
|
+
`__init__` again and mints a NEW serial: that is what stops two short-lived
|
|
134
|
+
threads sharing one recorded identity. (Without the registry, `uninstall`
|
|
135
|
+
could only ever drop the exceptions held by the thread that calls it.)
|
|
136
|
+
"""
|
|
137
|
+
def __init__(self, next_serial, register) -> None:
|
|
138
|
+
self.thread_serial: int = next_serial() # stable, never recycled
|
|
139
|
+
# id(frame) -> [frame_id, code, code_id, prev_locals, depth,
|
|
140
|
+
# in_window, suspended]
|
|
141
|
+
# for every OPEN frame this recorder opened on this thread. Slot 5 is
|
|
142
|
+
# `--window` membership, derived from ANCESTRY at PY_START: this code
|
|
143
|
+
# is the window target, or the parent entry is in the window. It is a
|
|
144
|
+
# property of the ACTIVATION, so a suspended windowed frame cannot lend
|
|
145
|
+
# its membership to whatever else happens to run meanwhile. Slot 6 is
|
|
146
|
+
# `suspended`: True between this frame's YIELD and the RESUME that
|
|
147
|
+
# answers it. It is deliberately never written out -- not at
|
|
148
|
+
# `uninstall`, not anywhere (spec D1). A frame still parked when
|
|
149
|
+
# recording stops leaves NO extra row, and the reader derives
|
|
150
|
+
# "suspended" from the frame's last YIELD/RESUME row, which is
|
|
151
|
+
# evidence the trace already holds. A written flag would be the
|
|
152
|
+
# recorder's opinion competing with that evidence, and would go
|
|
153
|
+
# stale for any thread still running when uninstall ran.
|
|
154
|
+
# Replaces the stack that v1 used: "the last frame I opened is the
|
|
155
|
+
# caller" is stack discipline, which a coroutine resumed by the event
|
|
156
|
+
# loop, a generator resumed by its consumer, and a callback from C all
|
|
157
|
+
# break.
|
|
158
|
+
# WHY `id(frame)` IS A SOUND KEY, now that entries suspend. Arc 1
|
|
159
|
+
# could argue it from stack discipline: an ordinary frame always
|
|
160
|
+
# leaves through PY_RETURN or PY_UNWIND -- both subscribed -- so its
|
|
161
|
+
# entry is gone before the address can die. A suspendable frame has
|
|
162
|
+
# no such guarantee from the language, and the argument is now an
|
|
163
|
+
# OBSERVED one: dropping a suspended generator fires
|
|
164
|
+
# PY_THROW(GeneratorExit) then PY_UNWIND, and cancelling a task fires
|
|
165
|
+
# PY_THROW(CancelledError) then PY_UNWIND (spec, "Measurements",
|
|
166
|
+
# facts 1-2), so the entry still leaves before the frame does. That
|
|
167
|
+
# observation is not true of every point release: 3.13.5 closes a
|
|
168
|
+
# simple generator with neither event. Install probes the behavior
|
|
169
|
+
# (`detect_silent_generator_close`) and, when the probe sees a silent
|
|
170
|
+
# close, reconciles a parked entry whose owner has closed before the
|
|
171
|
+
# address is reused. What backs the key up either way is the
|
|
172
|
+
# `entry[1] is code` re-check every reader makes (`_parent_of`,
|
|
173
|
+
# `_live_entry`, `_adopt`): a recycled address can only answer for a
|
|
174
|
+
# frame running the very same code object.
|
|
175
|
+
# THE ONE RESIDUAL is a frame still suspended when recording stops:
|
|
176
|
+
# nothing terminal ever fires for it, so its entry is simply dropped
|
|
177
|
+
# at `uninstall` and the reader derives "suspended at end of
|
|
178
|
+
# recording" from the last YIELD row.
|
|
179
|
+
# An entry does not stay here across a suspension: at YIELD it MOVES
|
|
180
|
+
# to the tracer-level `_parked` table, because the thread that
|
|
181
|
+
# resumes a suspended frame need not be the one that opened it, and
|
|
182
|
+
# it moves into the resuming thread's map at the first lookup that
|
|
183
|
+
# misses (`Tracer._park` / `_adopt`). So this map holds the frames
|
|
184
|
+
# RUNNING on this thread, `_parked` holds the suspended ones, and no
|
|
185
|
+
# entry is ever in both.
|
|
186
|
+
self.live: dict[int, list] = {}
|
|
187
|
+
self.in_hook = False
|
|
188
|
+
self.origin_recorded = False # whether the in-flight exc got a row
|
|
189
|
+
self.exc = _ExcRefs()
|
|
190
|
+
# Serials for control-flow exceptions THROWN INTO a traced frame,
|
|
191
|
+
# kept out of the table above; see `_CONTROL_RETAIN_MAX`.
|
|
192
|
+
self.cf_exc = _ExcRefs(cap=_CONTROL_RETAIN_MAX, source=self.exc)
|
|
193
|
+
# (task, serial) of the last task seen on this thread
|
|
194
|
+
self.task_cache: tuple | None = None
|
|
195
|
+
# Both tables, so `uninstall` releases everything this recorder holds
|
|
196
|
+
# on every thread. The registry is keyed only to keep entries apart
|
|
197
|
+
# and is never looked up by key, so the negative key is enough.
|
|
198
|
+
register(self.thread_serial, self.exc)
|
|
199
|
+
register(-self.thread_serial, self.cf_exc)
|