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,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)