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,141 @@
1
+ """Stream interception: what the recorder puts in front of `sys.stdout`,
2
+ `sys.stderr` and `sys.stdin` while the target runs.
3
+
4
+ Split out of `boot.py` at that file's 800-line ceiling, along the seam the
5
+ material has. These two proxies are the only part of the recorder the TARGET
6
+ touches directly -- by writing to a stream, or by reading one -- and they
7
+ know nothing about resolving a target, installing monitoring, the audit hook
8
+ or the writer's lifecycle, which is the rest of `boot`. Both are re-exported
9
+ there, so a caller (or a test) that reaches for `boot._Tee` still finds it,
10
+ and finds the same class object.
11
+
12
+ Both are delegating proxies rather than stream subclasses, and both
13
+ normalise through `capture.plain_str` before they test or store anything.
14
+ The reason is stated at each and is one reason: a `str` subclass with live
15
+ dunders would otherwise run the program's own code from inside the
16
+ instrument, at the program's own line.
17
+ """
18
+ from sensorium import redact_values as rv
19
+ from sensorium.record import capture
20
+
21
+
22
+ # -- stream interception ---------------------------------------------------
23
+ class _Tee:
24
+ """Pass writes through to the real stream and into the trace.
25
+
26
+ A delegating proxy rather than a TextIOBase subclass: programs reach for
27
+ `sys.stdout.buffer`, `.fileno()`, `.encoding` and `.isatty()`, and a
28
+ subclass would answer those for itself instead of for the stream the
29
+ program actually has. Output written straight to the file descriptor
30
+ (`os.write(1, ...)`, a child process) bypasses this and is not captured;
31
+ the trace holds what went through the Python stream object.
32
+ """
33
+
34
+ def __init__(self, orig, name, writer) -> None:
35
+ self._orig = orig
36
+ self._name = name
37
+ self._writer = writer
38
+
39
+ def write(self, s):
40
+ n = self._orig.write(s)
41
+ # Normalise BEFORE testing or storing. `s` is whatever the program
42
+ # passed to `print`, which may be a `str` subclass with live dunders:
43
+ # `if s:` ran its `__bool__`/`__len__` from inside the program's own
44
+ # call, the instance was then held in the writer's buffer until the
45
+ # next flush, and bound into sqlite from there. An exception out of
46
+ # any of that is the recorder killing the program it observes, at the
47
+ # program's own line. Found by the sweep for item 7, not reported.
48
+ # Normalised first, then rule v1's CONTENT half over the chunk.
49
+ # One `write()` at a time is the boundary this proxy has: a secret
50
+ # split across two writes is not seen. The real stream above got
51
+ # the bytes the program wrote -- an instrument that changed what a
52
+ # program SHOWS would be a worse instrument -- so what the rule
53
+ # applies to is this proxy's own copy, the one that reaches disk.
54
+ text, hit = rv.text(capture.plain_str(s))
55
+ if text:
56
+ # Counted here, at the write, like every capture the tracer
57
+ # stores: `values` is what the trace holds (B3).
58
+ if hit:
59
+ rv.stats["values"] += 1
60
+ self._writer.add_output(self._writer.last_event_id, self._name,
61
+ text)
62
+ return n
63
+
64
+ def writelines(self, lines) -> None:
65
+ for line in lines:
66
+ self.write(line)
67
+
68
+ def flush(self) -> None:
69
+ self._orig.flush()
70
+
71
+ def __getattr__(self, name):
72
+ return getattr(self._orig, name)
73
+
74
+
75
+ _MARK_ON_CALL = ("read", "readline", "readlines", "readinto", "read1")
76
+ _MARK_ON_ACCESS = ("buffer", "detach")
77
+
78
+
79
+ class _StdinProxy:
80
+ """Mark the run as having consumed stdin, so replay knows it is not pure.
81
+
82
+ Only reads that go through the Python object are seen. An interactive
83
+ `input()` on a real tty is served by the readline fast path against fd 0
84
+ and does not touch this proxy; piped and redirected stdin, which is what
85
+ a recorded run almost always has, does.
86
+
87
+ Everything else about the stream must behave exactly as it would without
88
+ the recorder -- an instrument that changes the program it observes is
89
+ worse than no instrument.
90
+ """
91
+
92
+ def __init__(self, orig) -> None:
93
+ self._orig = orig
94
+ self.consumed = False
95
+
96
+ def _marking(self, fn):
97
+ def inner(*a, **k):
98
+ self.consumed = True
99
+ return fn(*a, **k)
100
+ return inner
101
+
102
+ def __getattr__(self, name):
103
+ attr = getattr(self._orig, name) # raises first: absent is not use
104
+ # `name` is whatever the program passed to `getattr`, and CPython
105
+ # hands a `str` SUBCLASS straight through -- so the two membership
106
+ # tests below would run its `__eq__` and `__hash__`, from inside the
107
+ # program's own `getattr(sys.stdin, ...)` call, where without the
108
+ # recorder no comparison happens at all. Measured; found by the
109
+ # general-case audit for item 7.
110
+ name = capture.plain_str(name)
111
+ if name in _MARK_ON_CALL:
112
+ return self._marking(attr)
113
+ if name in _MARK_ON_ACCESS:
114
+ # Handing out the binary layer forfeits the ability to see the
115
+ # read, so the access itself counts. Over-marking is the safe
116
+ # direction: it costs a refused refocus, where a missed mark
117
+ # costs a MATCH verdict on a run that was never repeatable.
118
+ self.consumed = True
119
+ return attr
120
+
121
+ # Implicit special-method lookup goes to the type, not to __getattr__, so
122
+ # every dunder a program might use on a stream is spelled out here. A
123
+ # missing one is not a missed mark -- it is a TypeError in a program that
124
+ # ran fine without the recorder.
125
+ def __iter__(self):
126
+ self.consumed = True
127
+ return self # a file is its own iterator; so is this
128
+
129
+ def __next__(self):
130
+ self.consumed = True
131
+ return next(self._orig)
132
+
133
+ def __enter__(self):
134
+ self._orig.__enter__()
135
+ return self # never the raw stream: reads must stay seen
136
+
137
+ def __exit__(self, *exc_info):
138
+ return self._orig.__exit__(*exc_info)
139
+
140
+ def __repr__(self) -> str:
141
+ return repr(self._orig) # the instrument does not announce itself
@@ -0,0 +1,135 @@
1
+ """Which activations of one run are stored, and which are only counted.
2
+
3
+ The first ``max_calls`` activations of each function are recorded in full.
4
+ Further activations of that function, and every activation once the trace
5
+ has hit its event or byte cap, are counted and not stored. A failure still
6
+ materializes the raising frame, so the exception stays in the trace.
7
+
8
+ ``report`` is ``None`` unless at least one call was dropped. Callers write
9
+ that dict as trace meta only then, so a run that stayed inside the cap is
10
+ unchanged.
11
+ """
12
+ from __future__ import annotations
13
+
14
+ import threading
15
+ from collections import deque
16
+
17
+ _FAILURE_WINDOW = 8
18
+
19
+
20
+ class Budget:
21
+ """The cap decision for one ``Tracer``. ``writer`` supplies the counters."""
22
+
23
+ def __init__(self, limits, writer) -> None:
24
+ self.limits = limits
25
+ self.writer = writer
26
+ self._lock = threading.Lock()
27
+ # code id -> [elided, file, qualname, firstlineno, kept, reason]
28
+ self._hot: dict[int, list] = {}
29
+ self._kept: dict[int, int] = {}
30
+ self._hits: list[str] = []
31
+ self._hitset: set[str] = set()
32
+ self.failures_kept = 0
33
+ self._recent: deque = deque(maxlen=_FAILURE_WINDOW)
34
+
35
+ def slot(self, code_id: int):
36
+ """The hot-function row, or ``None`` when this code is still stored."""
37
+ return self._hot.get(code_id)
38
+
39
+ def bump(self, slot) -> None:
40
+ """One more elided activation of a function that is already hot."""
41
+ with self._lock:
42
+ self._drop(slot, slot[1], slot[2], slot[3])
43
+
44
+ def should_elide(self, code_id: int, file: str, qual: str,
45
+ lineno: int) -> bool:
46
+ """True when this activation must not be stored."""
47
+ with self._lock:
48
+ slot = self._hot.get(code_id)
49
+ if slot is not None:
50
+ self._drop(slot, file, qual, lineno)
51
+ return True
52
+ kept = self._kept.get(code_id, 0)
53
+ events = self.writer.last_event_id
54
+ nbytes = self.writer.bytes_estimate
55
+ reasons = []
56
+ if self.limits.max_calls and kept >= self.limits.max_calls:
57
+ reasons.append("max_calls")
58
+ if self.limits.max_events and events >= self.limits.max_events:
59
+ reasons.append("max_events")
60
+ if self.limits.max_bytes and nbytes >= self.limits.max_bytes:
61
+ reasons.append("max_bytes")
62
+ if not reasons:
63
+ return False
64
+ for reason in reasons:
65
+ self._mark(reason)
66
+ self._hot[code_id] = [1, file, qual, lineno, kept, reasons[0]]
67
+ self._recent.append((file, qual, lineno))
68
+ return True
69
+
70
+ def note_kept(self, code_id: int, file: str, qual: str, lineno: int) -> None:
71
+ """A call that was stored. Arms the fast path once the quota is full."""
72
+ with self._lock:
73
+ n = self._kept.get(code_id, 0) + 1
74
+ self._kept[code_id] = n
75
+ if (self.limits.max_calls and n >= self.limits.max_calls
76
+ and code_id not in self._hot):
77
+ self._hot[code_id] = [0, file, qual, lineno, n, "max_calls"]
78
+
79
+ def note_failure(self, code_id: int) -> bool:
80
+ """A failure frame kept after it had been counted as elided.
81
+
82
+ Returns True when the count moved, so the caller writes the skeleton
83
+ once. A second walk of the same frame finds the count already spent.
84
+ """
85
+ with self._lock:
86
+ slot = self._hot.get(code_id)
87
+ if slot is None or slot[0] <= 0:
88
+ return False
89
+ slot[0] -= 1
90
+ slot[4] += 1
91
+ self.failures_kept += 1
92
+ return True
93
+
94
+ def report(self) -> dict | None:
95
+ with self._lock:
96
+ elided = sum(slot[0] for slot in self._hot.values())
97
+ if elided <= 0:
98
+ return None
99
+ elisions = [
100
+ {"file": slot[1], "qualname": slot[2], "firstlineno": slot[3],
101
+ "elided": slot[0], "kept": slot[4]}
102
+ for slot in self._hot.values() if slot[0] > 0
103
+ ]
104
+ limits = {
105
+ "max_events": self.limits.max_events,
106
+ "max_bytes": self.limits.max_bytes,
107
+ "max_calls": self.limits.max_calls,
108
+ "hit": list(self._hits),
109
+ "events_recorded": self.writer.last_event_id,
110
+ "calls_elided": elided,
111
+ }
112
+ if self.failures_kept:
113
+ limits["failures_kept"] = self.failures_kept
114
+ out = {
115
+ "trace_truncated": True,
116
+ "trace_limits": limits,
117
+ "elisions": elisions,
118
+ }
119
+ if self.failures_kept and self._recent:
120
+ out["failure_context"] = [
121
+ {"file": file, "qualname": qual, "firstlineno": line}
122
+ for file, qual, line in self._recent
123
+ ]
124
+ return out
125
+
126
+ def _drop(self, slot, file: str, qual: str, lineno: int) -> None:
127
+ slot[0] += 1
128
+ if slot[0] == 1:
129
+ self._mark(slot[5])
130
+ self._recent.append((file, qual, lineno))
131
+
132
+ def _mark(self, name: str) -> None:
133
+ if name not in self._hitset:
134
+ self._hitset.add(name)
135
+ self._hits.append(name)