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,606 @@
1
+ """A restricted predicate language over CAPTURED values.
2
+
3
+ WHAT THIS IS NOT
4
+ ----------------
5
+ It is not `eval`. Nothing here executes program code, reads an attribute,
6
+ subscripts, imports, or touches a live object. The inputs are the primitives
7
+ `capture_value` wrote into a trace database; the operations are one
8
+ comparison, `and`/`or`/`not`, unary minus, five arithmetic operators and
9
+ `len(name)`. Everything else -- attributes, subscripts, calls other than
10
+ `len`, comprehensions, lambdas, f-strings, `is`/`in`, chained comparisons,
11
+ `**`, and every dunder path out of a literal -- is refused at COMPILE time,
12
+ before a single site is read. The refusal is compile-time on purpose: a
13
+ malformed or hostile expression then fails once, on the command line, rather
14
+ than once per site or (worse) not at all.
15
+
16
+ "Fails once" covers exhaustion as well as syntax, and it takes two guards
17
+ because there are two stages that can die. `compile_expr` catches the
18
+ parser's own stack overflow (`RecursionError`/`MemoryError`) as well as
19
+ `SyntaxError`; `_MAX_DEPTH` then guards `_validate`, which only ever runs on
20
+ a tree the parser survived. Either alone leaves a traceback reachable from an
21
+ ordinary command line.
22
+
23
+ The restriction is deliberately a real boundary and not a happy accident of
24
+ the input types. Reading captured primitives means there is nothing to escape
25
+ *to* today; a boundary that only holds because of what happens to be in the
26
+ dict is one refactor away from being `eval`, so it is enforced structurally
27
+ and tested as a boundary.
28
+
29
+ WHY A NAME CAN FAIL TO EVALUATE, AND WHY THE REASON MATTERS
30
+ -----------------------------------------------------------
31
+ A site where the predicate could not be applied is NOT a site where the
32
+ predicate was false, and the four ways it can fail send a reader to four
33
+ different fixes:
34
+
35
+ * OUT_OF_SCOPE -- the name is not bound here. Either it is not bound *yet*
36
+ (or has gone out of scope again, via `del` or the implicit unbind that
37
+ ends `except E as e:`), or this run never recorded that frame's locals at
38
+ all. Only the second is fixed by re-recording with `--focus`, and
39
+ `watch_cmd` tells the two apart before it suggests anything.
40
+ * NO_VALUE -- the name IS bound, to something `capture_value` could only
41
+ record as a type and a repr. Refocusing cannot help; an object has no
42
+ comparable value to record.
43
+ * CONTAINER -- bound to a list/tuple/set/dict, whose length was recorded
44
+ and whose contents were only sampled. `len(name)` works; comparing the
45
+ bare name does not.
46
+ * CLIPPED -- bound to a string longer than the capture cap, so what the
47
+ trace holds is a PREFIX. Comparing a prefix, or taking its length, is a
48
+ claim about characters that were never recorded.
49
+ * REDACTED_REASON -- the redaction rule took the value at the recorder,
50
+ before anything reached disk. Every taken capture holds the same marker
51
+ text, so comparing one would answer the same about two secrets that are
52
+ not equal to each other. Re-recording is what changes this, not asking
53
+ differently.
54
+
55
+ Collapsing any of these into a silent False would let "I could not check"
56
+ read as "the invariant held". That is the failure this whole module exists to
57
+ prevent, so the reason travels on the exception and `watch` prints it.
58
+
59
+ TRUNCATION, AND THE ONE PLACE IT DOES NOT BITE
60
+ ----------------------------------------------
61
+ `trunc` on a container capture means the SAMPLE was capped, or the depth was
62
+ -- never the length: `_capture_sized` writes `len(obj)` before any cap is
63
+ applied. So `len(name)` over a truncated container is exact, and this module
64
+ never reads `sample` at all (a depth-capped capture omits that key entirely).
65
+ A clipped *string* is the real truncation case, and it is refused.
66
+ """
67
+ import ast
68
+ import operator
69
+
70
+ from sensorium.query.rust_debug import read_debug
71
+
72
+ # Why a name the predicate needs has no usable value at some site. `NAME` is
73
+ # substituted with the actual name when the message is rendered.
74
+ OUT_OF_SCOPE = "not in scope at this site"
75
+ NO_VALUE = "recorded as an object, which has no comparable value"
76
+ CONTAINER = "recorded as a container; compare its length with len(NAME)"
77
+ CLIPPED = "recorded truncated, so the trace does not hold the whole value"
78
+ NO_LENGTH = "recorded as a value that has no length"
79
+ SAMPLED = ("recorded as a container whose sample does not decide whether "
80
+ "that value is in NAME (only a sample of its members was "
81
+ "recorded); its length is exact, so len(NAME) still is")
82
+ #: A value the redaction rule took at the RECORDER, before anything reached
83
+ #: disk. Every taken capture of every kind holds the same marker text, so a
84
+ #: predicate applied to one would compare `<redacted>` -- and would answer
85
+ #: the same about two secrets that are not equal to each other. There is
86
+ #: nothing here to compare, and saying so is the only honest answer.
87
+ REDACTED_REASON = "redacted by rule v1; no comparable value"
88
+
89
+
90
+ class ExprError(Exception):
91
+ """Not in this language. Always raised at compile time."""
92
+
93
+
94
+ class NotCaptured(Exception):
95
+ """A name the predicate needs has no usable captured value at this site.
96
+
97
+ Never a verdict. Callers count these and report them; the one thing they
98
+ must not do is treat them as the predicate having come back False.
99
+ """
100
+
101
+ def __init__(self, name: str, reason: str = OUT_OF_SCOPE) -> None:
102
+ super().__init__(f"{name}: {reason.replace('NAME', name)}")
103
+ self.name = name
104
+ self.reason = reason
105
+
106
+
107
+ class EvalError(Exception):
108
+ """The predicate is well-formed but could not be applied to these values.
109
+
110
+ `'five' > 3` and `x / 0` are not misses -- nothing was decided at all.
111
+ Kept apart from `NotCaptured` because the fix is different: the capture is
112
+ fine, the predicate does not fit the data.
113
+ """
114
+
115
+ def __init__(self, cause: BaseException) -> None:
116
+ super().__init__(f"{type(cause).__name__}: {cause}")
117
+ self.cause = cause
118
+
119
+
120
+ class _Marker:
121
+ """A singleton with a readable repr, so a leak into output is obvious."""
122
+ __slots__ = ("_label",)
123
+
124
+ def __init__(self, label: str) -> None:
125
+ self._label = label
126
+
127
+ def __repr__(self) -> str:
128
+ return self._label
129
+
130
+
131
+ NOT_CAPTURED = _Marker("<NOT_CAPTURED>")
132
+ TRUNCATED = _Marker("<TRUNCATED>")
133
+ #: A value the redaction rule took. Its own marker and not NOT_CAPTURED,
134
+ #: because the two are different facts with different fixes: NOT_CAPTURED is
135
+ #: a recorder that could not read a value, and this is a rule that read it
136
+ #: and refused to store it. Equal only to itself, like every marker here --
137
+ #: which is what stops `token == '<redacted>'` from ever answering yes.
138
+ REDACTED = _Marker("<REDACTED>")
139
+ #: JavaScript's second absence. A name bound to `undefined` IS bound, and a
140
+ #: trace that recorded one holds a value -- so it may not read as `None`
141
+ #: (which would make `x == null` answer yes about a site that recorded
142
+ #: `undefined`) and may not read as NOT_CAPTURED (which would report a site
143
+ #: whose value the trace does hold as one the predicate could not be checked
144
+ #: at). Equal only to itself, like every other marker here.
145
+ UNDEFINED = _Marker("<undefined>")
146
+
147
+ #: The four words this language reads as VALUES rather than as names. They
148
+ #: are language-neutral: `x == null` on a Python trace compares with `None`
149
+ #: exactly as `x == None` does, and `x == undefined` is the one predicate
150
+ #: that can tell JavaScript's two absences apart. A program local spelled
151
+ #: `null`, `undefined`, `true` or `false` is SHADOWED by the constant --
152
+ #: declared here and pinned by `v35-predicate-constants`, because the
153
+ #: alternative is a predicate whose meaning depends on what the recorded
154
+ #: frame happened to bind.
155
+ _CONSTANTS = {"null": None, "undefined": UNDEFINED,
156
+ "true": True, "false": False}
157
+
158
+
159
+ class _Sized:
160
+ """A container recorded by its length and, when the capture holds one, a
161
+ sample of its members. `len()` works; `literal in name` works when the
162
+ sample decides it (see `_member`); nothing else."""
163
+ __slots__ = ("n", "members", "complete")
164
+
165
+ def __init__(self, n: int, members=None, complete: bool = False) -> None:
166
+ self.n = n
167
+ self.members = members # frozenset of sampled primitives, or None
168
+ self.complete = complete # True when `members` IS the whole container
169
+
170
+ def __repr__(self) -> str:
171
+ return f"<len {self.n}>"
172
+
173
+
174
+ class _DbgText(str):
175
+ """A string read out of a rendered TEXT capture (Rust's `{:?}`, or
176
+ JavaScript's `util.inspect`).
177
+
178
+ A `str`, because that is what the trace holds and what a predicate may
179
+ compare: `s == "A1"` and `"A" in s` are answered by the very characters
180
+ the recorder wrote, and design 2026-09-06 §4.2 says they are answered.
181
+ Its own class, because `len()` over it is not: `"A1"` is four characters
182
+ as Rust spells it and two as the program held it, and the recorder
183
+ measured NEITHER number -- it recorded a rendering. `_length` refuses it,
184
+ so such a site is reported as one the predicate could not be checked at.
185
+ """
186
+ __slots__ = ()
187
+
188
+
189
+ _CMP = {ast.Lt: operator.lt, ast.LtE: operator.le, ast.Gt: operator.gt,
190
+ ast.GtE: operator.ge, ast.Eq: operator.eq, ast.NotEq: operator.ne}
191
+ _BIN = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
192
+ ast.Div: operator.truediv, ast.Mod: operator.mod}
193
+ # The comparisons that have a boundary to approach. `==`/`!=` do not: the
194
+ # distance from `a == b` to true is not a number a reader can act on.
195
+ _ORDERING = (ast.Lt, ast.LtE, ast.Gt, ast.GtE)
196
+ # Raised by applying a legal operator to captured values of the wrong shape.
197
+ # Caught and re-raised as EvalError so a site can be counted, never crashed on.
198
+ _ARITH = (TypeError, ZeroDivisionError, OverflowError, ValueError)
199
+ # How deep an expression tree may nest. `_validate` and `_eval` both recurse
200
+ # once per node, and `ast.parse` happily builds a tree far deeper than either
201
+ # survives: measured, `x + x + ...` a thousand times parses cleanly and then
202
+ # takes `_validate` out with a RecursionError -- a traceback and a non-2 exit
203
+ # from a command whose whole contract is that a bad expression fails once, on
204
+ # the command line. A fixed cap is used rather than catching RecursionError
205
+ # because it is deterministic (no dependence on the interpreter's remaining
206
+ # stack) and because refusing at 50 in `_validate` is what GUARANTEES `_eval`
207
+ # can never recurse deeply enough to fail at a site. Real predicates nest
208
+ # under 10.
209
+ _MAX_DEPTH = 50
210
+
211
+
212
+ def resolve(v: dict, dialect=None):
213
+ """One capture -> a usable value, or a marker saying why not.
214
+
215
+ Markers rather than exceptions because a caller folds these into an
216
+ environment long before any predicate looks at them: `env[name]` present
217
+ but NOT_CAPTURED means "in scope, no value", which is a different fact
218
+ from the name being absent, and both have to survive the fold.
219
+
220
+ `dialect` is which language's formatter wrote a `dbg` capture, from the
221
+ trace's own vocabulary (`query/dbg_dialects`). Absent, it is Rust's --
222
+ what every caller got before a second dialect existed, and what no
223
+ Python trace ever reaches, since Python's captures are typed (P10).
224
+ """
225
+ # BEFORE the kind dispatch. A taken capture keeps its kind and holds
226
+ # the rule's marker text in the field the value was in, so `num` would
227
+ # hand back the STRING `<redacted>` as a number and `str` would hand it
228
+ # back as a string a predicate can match. A CONTENT hit is not this
229
+ # case and falls through on purpose: the rule replaced a span inside a
230
+ # text the recorder kept, and the text is what the trace holds.
231
+ if (v.get("redacted") or {}).get("by") == "name":
232
+ return REDACTED
233
+ k = v.get("k")
234
+ if k in ("num", "bool"):
235
+ return v["v"]
236
+ if k == "str":
237
+ # What the trace holds is a prefix of the real string. It is not the
238
+ # value and must not be compared as if it were.
239
+ return TRUNCATED if v.get("trunc") else v["v"]
240
+ if k == "none":
241
+ return None
242
+ if k in ("seq", "map"):
243
+ # `len` is exact even here: it is written before any cap is applied,
244
+ # and `trunc` on a container means the sample (or the depth) was cut.
245
+ # It is None only when the object's own `__len__` raised at capture
246
+ # time -- an unread size is not a size, and `len(buf) > 100` must
247
+ # report a site it could not evaluate rather than compare to nothing.
248
+ n = v.get("len")
249
+ if n is None:
250
+ return NOT_CAPTURED
251
+ members, complete = _members(v, n)
252
+ return _Sized(n, members, complete)
253
+ if k == "dbg":
254
+ # A value the recorder could only RENDER, with the language's own
255
+ # formatter, because it cannot decompose the type (Rust's `Debug`,
256
+ # JavaScript's `util.inspect`). The text is the capture, so the
257
+ # value is whatever the text spells IN THAT DIALECT -- and a
258
+ # truncated one is a prefix of the rendering, which spells nothing.
259
+ if v.get("trunc"):
260
+ return TRUNCATED
261
+ t = v.get("v")
262
+ if not isinstance(t, str):
263
+ return NOT_CAPTURED # a `dbg` with no text is malformed
264
+ read = dialect.read if dialect else read_debug
265
+ val = read(t)
266
+ # A dialect may find a prefix the wire flag cannot show (inspect
267
+ # cuts a long string itself), and that stays a prefix.
268
+ if val is TRUNCATED:
269
+ return TRUNCATED
270
+ return _DbgText(val) if isinstance(val, str) else val
271
+ return NOT_CAPTURED
272
+
273
+
274
+ _PRIMITIVE = ("num", "bool", "str", "none")
275
+
276
+
277
+ def _members(v: dict, n: int):
278
+ """The sampled members of a captured container that a literal can be
279
+ compared with, and whether they are ALL of it. A map samples (key, value)
280
+ pairs -- membership is over keys, as in Python. A member that is itself a
281
+ container, an object, or a clipped string is not comparable, so a sample
282
+ holding one can prove presence but never absence.
283
+
284
+ A member the redaction rule TOOK is one of those: every taken capture
285
+ holds the same marker text, so adding it to the set would make
286
+ `'<redacted>' in cfg` a hit, and -- far worse -- would let
287
+ `'hunter2' in cfg` come back a DECIDED False about a container one of
288
+ whose members nobody recorded. It is counted as a member the sample
289
+ does not decide, which is exactly what `complete` already means."""
290
+ sample = v.get("sample")
291
+ if sample is None:
292
+ return None, False
293
+ members, comparable = set(), True
294
+ for entry in sample:
295
+ item = entry[0] if v.get("k") == "map" else entry
296
+ if (not isinstance(item, dict) or item.get("k") not in _PRIMITIVE
297
+ or item.get("trunc")
298
+ or (item.get("redacted") or {}).get("by") == "name"):
299
+ comparable = False
300
+ continue
301
+ members.add(None if item["k"] == "none" else item.get("v"))
302
+ complete = comparable and not v.get("trunc") and len(sample) == n
303
+ return frozenset(members), complete
304
+
305
+
306
+ # -- compiling -------------------------------------------------------------
307
+ def _validate_len(node: ast.Call) -> None:
308
+ if not (isinstance(node.func, ast.Name) and node.func.id == "len"):
309
+ raise ExprError("the only call allowed is len(name)")
310
+ if node.keywords or len(node.args) != 1:
311
+ raise ExprError("len takes exactly one positional argument")
312
+ if not isinstance(node.args[0], ast.Name):
313
+ raise ExprError("len's argument must be a plain name, as in len(buf)")
314
+
315
+
316
+ _EMPTY_LITERALS = (ast.Dict, ast.List, ast.Tuple, ast.Set)
317
+
318
+
319
+ def _is_empty_literal(node) -> bool:
320
+ if isinstance(node, ast.Dict):
321
+ return not node.keys
322
+ if isinstance(node, (ast.List, ast.Tuple, ast.Set)):
323
+ return not node.elts
324
+ return False
325
+
326
+
327
+ def _validate_compare(node: ast.Compare, depth: int) -> None:
328
+ if len(node.ops) != 1:
329
+ raise ExprError("chained comparisons are not allowed; write one "
330
+ "comparison, or join two with `and`")
331
+ op = type(node.ops[0])
332
+ left, right = node.left, node.comparators[0]
333
+ if op in (ast.In, ast.NotIn):
334
+ # Membership is decided from the SAMPLE a capture holds, so it is
335
+ # offered in the one shape a sample can answer: a literal looked up
336
+ # in a named container (or string).
337
+ if not (isinstance(left, ast.Constant) and isinstance(right, ast.Name)
338
+ and right.id != "len"):
339
+ raise ExprError("`in` is only allowed as a literal in a name, as "
340
+ "in 'key' in meta or 3 in xs")
341
+ _validate(left, depth)
342
+ return
343
+ if op not in _CMP:
344
+ raise ExprError("only < <= > >= == != and `in`/`not in` are allowed "
345
+ "as comparisons")
346
+ lits = [n for n in (left, right) if isinstance(n, _EMPTY_LITERALS)]
347
+ if lits:
348
+ # `name == {}` is a length-zero test the trace answers exactly; any
349
+ # non-empty literal would be compared against a SAMPLE, which is not
350
+ # the value.
351
+ other = right if lits[0] is left else left
352
+ if (len(lits) != 1 or op not in (ast.Eq, ast.NotEq)
353
+ or not _is_empty_literal(lits[0])
354
+ or not (isinstance(other, ast.Name) and other.id != "len")):
355
+ raise ExprError("a container literal can only be the empty {} / "
356
+ "[] / () compared with == or != to a name; for "
357
+ "anything else compare len(name), or test "
358
+ "'item' in name")
359
+ return
360
+ _validate(left, depth)
361
+ _validate(right, depth)
362
+
363
+
364
+ def _validate(node, depth: int = 0) -> None:
365
+ if depth > _MAX_DEPTH:
366
+ raise ExprError(f"expression nests deeper than {_MAX_DEPTH} levels; "
367
+ "a predicate over captured values does not need that")
368
+ depth += 1
369
+ if isinstance(node, ast.Expression):
370
+ _validate(node.body, depth)
371
+ elif isinstance(node, ast.Constant):
372
+ if not (isinstance(node.value, (int, float, str, bool))
373
+ or node.value is None):
374
+ raise ExprError(f"unsupported constant {node.value!r}")
375
+ elif isinstance(node, ast.Name):
376
+ # `len` reaches here only as a BARE name -- `_validate_len` checks the
377
+ # callee itself and never recurses into it. Left alone, `len > 1`
378
+ # would compile to a lookup for a variable no capture ever holds and
379
+ # be reported as "not in scope", sending a reader after a builtin.
380
+ if node.id == "len":
381
+ raise ExprError("`len` is only allowed as len(name), as in "
382
+ "len(buf) > 3")
383
+ elif isinstance(node, ast.Call):
384
+ _validate_len(node)
385
+ elif isinstance(node, ast.Compare):
386
+ _validate_compare(node, depth)
387
+ elif isinstance(node, ast.BoolOp):
388
+ for v in node.values:
389
+ _validate(v, depth)
390
+ elif isinstance(node, ast.UnaryOp) and isinstance(node.op,
391
+ (ast.Not, ast.USub)):
392
+ _validate(node.operand, depth)
393
+ elif isinstance(node, ast.BinOp) and type(node.op) in _BIN:
394
+ _validate(node.left, depth)
395
+ _validate(node.right, depth)
396
+ else:
397
+ raise ExprError(f"unsupported syntax: {type(node).__name__}")
398
+
399
+
400
+ def compile_expr(src: str) -> "Expr":
401
+ try:
402
+ tree = ast.parse(src, mode="eval")
403
+ except SyntaxError as e:
404
+ raise ExprError(f"not a valid expression: {e.msg}") from None
405
+ except (RecursionError, MemoryError):
406
+ # The parser has its own bounded stack, and it overflows BEFORE
407
+ # `_MAX_DEPTH` gets a look in -- the cap guards `_validate`, which
408
+ # never runs if there is no tree. Measured: 60000 unary minus, or
409
+ # `not ` 20000 times, raise `MemoryError: Parser stack overflowed`,
410
+ # and both fit inside one argv entry (MAX_ARG_STRLEN is 128 KB), so
411
+ # this is reachable from an ordinary command line. Without this the
412
+ # module's promise of a single clean refusal was false for exactly
413
+ # the inputs most likely to be hostile.
414
+ #
415
+ # Catching MemoryError is normally a bad idea -- the interpreter may
416
+ # be wedged -- but this one is raised deterministically by the parser
417
+ # against its own fixed limit, nothing has been allocated to leak,
418
+ # and it is re-raised immediately as a refusal.
419
+ raise ExprError("expression is too large or too deeply nested for "
420
+ "the parser; a predicate over captured values does "
421
+ "not need that") from None
422
+ _validate(tree)
423
+ names = {n.id for n in ast.walk(tree) if isinstance(n, ast.Name)}
424
+ names.discard("len") # the callee of a validated len(name) call
425
+ # A constant is not a name the trace could witness (plan P11). Left in,
426
+ # `null` would reach `watch`'s NEVER RECORDED banner -- "captured at NO
427
+ # site in these frames", about a word no recorder can capture -- and
428
+ # that banner discredits every verdict printed under it.
429
+ names -= _CONSTANTS.keys()
430
+ return Expr(tree, names, src)
431
+
432
+
433
+ def _is_real(x) -> bool:
434
+ """A number a margin can be measured against. `True` is not one: bools
435
+ compare as 0/1 and would report a distance of 1 from a boundary they have
436
+ no relationship to."""
437
+ return isinstance(x, (int, float)) and not isinstance(x, bool)
438
+
439
+
440
+ class Expr:
441
+ """A compiled predicate. `names` is every name it may need."""
442
+
443
+ def __init__(self, tree: ast.Expression, names: set[str],
444
+ src: str) -> None:
445
+ self._tree = tree
446
+ self.names = names
447
+ self.src = src
448
+
449
+ @property
450
+ def has_boundary(self) -> bool:
451
+ """Whether `margin` can ever return a number for this predicate."""
452
+ node = self._tree.body
453
+ return (isinstance(node, ast.Compare)
454
+ and type(node.ops[0]) in _ORDERING)
455
+
456
+ def eval(self, env: dict) -> bool:
457
+ try:
458
+ return bool(self._eval(self._tree.body, env))
459
+ except _ARITH as e:
460
+ raise EvalError(e) from None
461
+
462
+ def margin(self, env: dict) -> float | None:
463
+ """How far this site was from the boundary, or None if there is none.
464
+
465
+ Defined only for a single numeric ordering comparison at the top: that
466
+ is the only shape where "distance to the boundary" is a number a
467
+ reader can rank sites by.
468
+ """
469
+ if not self.has_boundary:
470
+ return None
471
+ node = self._tree.body
472
+ try:
473
+ lhs = self._eval(node.left, env)
474
+ rhs = self._eval(node.comparators[0], env)
475
+ except (NotCaptured, *_ARITH):
476
+ return None
477
+ return abs(lhs - rhs) if _is_real(lhs) and _is_real(rhs) else None
478
+
479
+ # -- evaluation --------------------------------------------------------
480
+ def _eval(self, node, env):
481
+ if isinstance(node, ast.Constant):
482
+ return node.value
483
+ if isinstance(node, ast.Name):
484
+ if node.id in _CONSTANTS:
485
+ return _CONSTANTS[node.id]
486
+ return _name(node.id, env)
487
+ if isinstance(node, ast.Call): # validated: len(name)
488
+ return _length(node.args[0].id, env)
489
+ if isinstance(node, ast.Compare):
490
+ op = type(node.ops[0])
491
+ left, right = node.left, node.comparators[0]
492
+ if op in (ast.In, ast.NotIn):
493
+ hit = _member(left.value, right.id, env)
494
+ return hit if op is ast.In else not hit
495
+ if isinstance(left, _EMPTY_LITERALS) or isinstance(
496
+ right, _EMPTY_LITERALS):
497
+ name = right if isinstance(left, _EMPTY_LITERALS) else left
498
+ empty = _length(name.id, env) == 0
499
+ return empty if op is ast.Eq else not empty
500
+ return _CMP[op](self._eval(left, env), self._eval(right, env))
501
+ if isinstance(node, ast.BoolOp):
502
+ return self._boolop(node, env)
503
+ if isinstance(node, ast.UnaryOp):
504
+ v = self._eval(node.operand, env)
505
+ return (not v) if isinstance(node.op, ast.Not) else -v
506
+ return _BIN[type(node.op)](self._eval(node.left, env),
507
+ self._eval(node.right, env))
508
+
509
+ def _boolop(self, node: ast.BoolOp, env):
510
+ """Short-circuiting, and that is a correctness property, not speed.
511
+
512
+ `False and <uncaptured>` is False; `True or <uncaptured>` is True. The
513
+ trace decides those sites, so refusing them would move a site out of
514
+ "evaluated" and into "could not check" -- inflating the one number a
515
+ reader uses to discount a run that reported no hits. Where the missing
516
+ half really does decide the answer, the refusal still happens.
517
+ """
518
+ decisive = not isinstance(node.op, ast.And)
519
+ for v in node.values:
520
+ if bool(self._eval(v, env)) is decisive:
521
+ return decisive
522
+ return not decisive
523
+
524
+
525
+ def _bound(name: str, env: dict):
526
+ """What a name stands for: a constant of the language first, then the
527
+ environment.
528
+
529
+ One rule, three readers. `_eval` answers a bare Name from `_CONSTANTS`
530
+ directly, and the other two paths into a name -- `len(name)` and
531
+ `literal in name` -- come through here, so `len(undefined)` reports the
532
+ value it names as having no recorded length rather than reporting the
533
+ word as out of scope, and the shadowing rule cannot differ by path.
534
+ """
535
+ if name in _CONSTANTS:
536
+ return _CONSTANTS[name]
537
+ return env.get(name, NOT_CAPTURED)
538
+
539
+
540
+ def _name(name: str, env: dict):
541
+ val = _bound(name, env)
542
+ if val is REDACTED:
543
+ raise NotCaptured(name, REDACTED_REASON)
544
+ if val is NOT_CAPTURED:
545
+ raise NotCaptured(name, NO_VALUE if name in env else OUT_OF_SCOPE)
546
+ if val is TRUNCATED:
547
+ raise NotCaptured(name, CLIPPED)
548
+ if isinstance(val, _Sized):
549
+ raise NotCaptured(name, CONTAINER)
550
+ return val
551
+
552
+
553
+ def _member(value, name: str, env: dict) -> bool:
554
+ """`value in name`, decided only where the capture decides it.
555
+
556
+ A container's capture is its length plus a SAMPLE of at most
557
+ CAPS["sample"] members. Found in the sample -> True, certainly. Not
558
+ found -> False only when the sample is the whole container and every
559
+ member was a comparable primitive; otherwise the trace does not hold the
560
+ answer and the site is reported, never guessed. A string is a substring
561
+ test; a clipped string cannot answer at all, because the prefix is not
562
+ in the environment.
563
+ """
564
+ val = _bound(name, env)
565
+ if val is REDACTED:
566
+ raise NotCaptured(name, REDACTED_REASON)
567
+ if val is NOT_CAPTURED:
568
+ raise NotCaptured(name, NO_VALUE if name in env else OUT_OF_SCOPE)
569
+ if val is TRUNCATED:
570
+ raise NotCaptured(name, CLIPPED)
571
+ if isinstance(val, _Sized):
572
+ if val.members is not None and value in val.members:
573
+ return True
574
+ if val.complete:
575
+ return False
576
+ raise NotCaptured(name, SAMPLED)
577
+ if isinstance(val, str):
578
+ if not isinstance(value, str):
579
+ raise TypeError(f"'in <string>' needs a string literal, not "
580
+ f"{type(value).__name__}")
581
+ return value in val
582
+ raise NotCaptured(name, NO_LENGTH) # a number, bool or None: no members
583
+
584
+
585
+ def _length(name: str, env: dict) -> int:
586
+ val = _bound(name, env)
587
+ if val is REDACTED:
588
+ # A taken container's LENGTH is recorded and kept -- but it is kept
589
+ # on the capture, and what reached this environment is the marker.
590
+ # `len(token)` over a taken value is refused with every other path
591
+ # into it, so a reader is told one thing rather than three.
592
+ raise NotCaptured(name, REDACTED_REASON)
593
+ if isinstance(val, _Sized):
594
+ return val.n
595
+ if isinstance(val, _DbgText):
596
+ # BEFORE the `str` arm, which it would otherwise satisfy. What the
597
+ # trace holds is a rendering, and a rendering's length is not the
598
+ # value's -- no length was recorded here at all.
599
+ raise NotCaptured(name, NO_LENGTH)
600
+ if isinstance(val, str):
601
+ return len(val)
602
+ if val is NOT_CAPTURED:
603
+ raise NotCaptured(name, NO_VALUE if name in env else OUT_OF_SCOPE)
604
+ if val is TRUNCATED:
605
+ raise NotCaptured(name, CLIPPED)
606
+ raise NotCaptured(name, NO_LENGTH)