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,657 @@
1
+ """A predicate at every recorded site, and how close the run came to it.
2
+
3
+ WHAT THIS COMMAND CLAIMS
4
+ ------------------------
5
+ A SITE is one recorded event in a matching frame: a CALL, carrying that
6
+ activation's arguments, or a LINE, carrying that frame's locals folded
7
+ forward. At each site the predicate is applied to the state the trace records
8
+ there, and the site lands in exactly one bucket: HIT, miss, could-not-check,
9
+ or errored. Nothing is skipped, and every bucket is counted in one tally line.
10
+
11
+ WHAT IT REFUSES TO CLAIM
12
+ ------------------------
13
+ That an invariant held. It cannot: a trace holds what was recorded, and
14
+ between two recorded sites the program ran code this command never saw. So
15
+ `hits: 0` is never printed on its own. It is always accompanied by a verdict
16
+ that says which of three different things happened --
17
+
18
+ * every recorded site was evaluated and none satisfied the predicate
19
+ (a fact about the recording, still not a proof about the run),
20
+ * some sites could not be evaluated, so the question is open, or
21
+ * NOTHING was checked at all, and `hits: 0` means "could not evaluate".
22
+
23
+ -- and by the count of sites it could not check, with the reason. The tally
24
+ line carries every bucket (`sites` = `evaluated` + `not-captured` + `errors`)
25
+ so the arithmetic is checkable rather than trusted. A user reading "0 hits"
26
+ as "the invariant held" when the truth was "I could not check" is the single
27
+ worst outcome this command has, and every design choice below is aimed at it.
28
+
29
+ That includes a hole that short-circuiting leaves open: a name the trace has
30
+ no record of ANYWHERE is absorbed silently by `and`/`or` and never reaches
31
+ the not-captured count. `print_never_recorded` closes it, above the verdict,
32
+ and the verdict refuses to come back clean while such a name is in play.
33
+
34
+ FOLDING STATE FORWARD, AND THE KEY THAT MAKES IT HONEST
35
+ -------------------------------------------------------
36
+ LINE payloads carry only the locals whose capture CHANGED. To know what was
37
+ in scope at a site, this command folds those deltas forward through the
38
+ frame. A local that goes AWAY produces no delta -- so a fold that reads
39
+ `deltas` alone keeps a deleted variable alive at its last value for the rest
40
+ of the frame, and reports a HIT on a variable that no longer exists.
41
+
42
+ The tracer emits a sibling `unbound` list for exactly this consumer, and it
43
+ is not a rare case: `del x` does it, and the implicit unbind that ends every
44
+ `except E as e:` block does it far more often. Measured on a three-pass loop
45
+ whose handler rebinds `e` to an int, ignoring `unbound` turns one true hit
46
+ into three. A LINE event may also carry EMPTY deltas and a non-empty
47
+ `unbound` -- a `del` on a line that changes nothing else -- so such an event
48
+ is a site like any other and is never skipped for having no deltas.
49
+
50
+ TRUNCATION
51
+ ----------
52
+ A clipped string capture is a PREFIX; comparing it, or taking its length, is
53
+ a claim about characters the trace does not hold. Those sites are refused and
54
+ counted, not quietly answered. Container captures are unaffected: their
55
+ recorded length is exact even when the sample was capped, and nothing here
56
+ reads a `sample` key (a depth-capped capture omits it entirely).
57
+ """
58
+ import shlex
59
+ from dataclasses import dataclass
60
+ from enum import Enum, auto
61
+
62
+ from sensorium import paths, redact
63
+ from sensorium.exit import ANSWERED, BAD_CALL, NEGATIVE, UNSETTLED
64
+ from sensorium.query.caps import print_incomplete, require
65
+ from sensorium.query.expr import (CLIPPED, CONTAINER, NO_LENGTH, NO_VALUE,
66
+ NOT_CAPTURED, OUT_OF_SCOPE, REDACTED,
67
+ REDACTED_REASON, TRUNCATED, EvalError,
68
+ ExprError, NotCaptured, _Sized,
69
+ compile_expr, resolve)
70
+ from sensorium.query.dbg_dialects import for_trace
71
+ from sensorium.query.fmt import fmt_event, fmt_value, more_note, parse_eref
72
+ from sensorium.query.help import LIMIT_HELP, RUN_HELP
73
+ from sensorium.query.sites import ( # noqa: F401 (re-exported)
74
+ _qual_matches, rerun_command, spell_site)
75
+ from sensorium.query.sites import site_matches as _site_matches
76
+ from sensorium.query.vocab import terms
77
+ from sensorium.store.reader import Trace
78
+
79
+ _MAX_LISTED_CODES = 20
80
+ _MAX_LISTED_ERRORS = 5
81
+
82
+ #: What a state line says for a name the redaction rule took. One constant
83
+ #: because two places read it -- `_render`, which prints it at a site, and
84
+ #: `_guidance`, which quotes it so a reader who never reaches a hit knows
85
+ #: what the words will be. Two literals would drift, and a test or a vector
86
+ #: needle that matched only the quoted one would pin nothing about the
87
+ #: renderer.
88
+ REDACTED_STATE = "<redacted; no comparable value>"
89
+
90
+ CLAIM = (
91
+ "a site is one RECORDED event in a matching frame: a CALL (its arguments)",
92
+ "or a LINE (that frame's locals, folded forward and dropped again when a",
93
+ "name goes out of scope). Whatever ran between two recorded sites",
94
+ "was not checked, and code this run never recorded is not in this trace.",
95
+ )
96
+
97
+
98
+ def add_parser(sub) -> None:
99
+ p = sub.add_parser(
100
+ "watch", help="predicate over captured state",
101
+ description="A gdb-style watchpoint evaluated after the fact at "
102
+ "every recorded site of one function; needs a "
103
+ "`--focus` recording, and NOTHING WAS CHECKED is a "
104
+ "refusal, never a pass.",
105
+ epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
106
+ p.add_argument("run", help=RUN_HELP)
107
+ p.add_argument("--at", required=True, help="module:qualname or qualname")
108
+ p.add_argument("--expr", required=True,
109
+ help="names, literals, one comparison, and/or/not, "
110
+ "arithmetic, len(name)")
111
+ p.add_argument("--after", default=None, help="event ref to resume from")
112
+ p.add_argument("--limit", type=int, default=20,
113
+ help=LIMIT_HELP)
114
+ p.add_argument("--misses", type=int, default=5, dest="misses",
115
+ help="how many near-misses to show when nothing hit")
116
+ p.set_defaults(func=run)
117
+
118
+
119
+ # -- selecting sites -------------------------------------------------------
120
+ def site_matches(code, at: str, trace) -> bool:
121
+ """Whether `--at` selects this code object -- `query/sites`' rule.
122
+
123
+ A delegation and not a copy: the same rule decides what `--at` selects,
124
+ what the no-match listing prints and what `--focus` would re-record, and
125
+ a second implementation here is how those three drift apart.
126
+ """
127
+ return _site_matches(code, at, trace)
128
+
129
+
130
+ @dataclass(frozen=True)
131
+ class Site:
132
+ """One recorded event, with the state the predicate sees there."""
133
+ event: object
134
+ env: dict # name -> resolved value (or a marker saying why not)
135
+ caps: dict # name -> the raw capture behind it, for rendering
136
+
137
+
138
+ def _bind(env: dict, caps: dict, deltas: dict, wanted: set,
139
+ dialect=None) -> None:
140
+ for n, v in deltas.items():
141
+ if n in wanted:
142
+ env[n] = resolve(v, dialect)
143
+ caps[n] = v
144
+
145
+
146
+ def sites_for(trace, code_ids, wanted: set, dialect=None) -> list[Site]:
147
+ """Every recorded site in the matching frames, state folded forward.
148
+
149
+ Only the predicate's own names are tracked, which bounds the copy per
150
+ site and keeps a wide frame from carrying its whole scope into memory.
151
+
152
+ `dialect` is which formatter wrote this trace's `dbg` captures. Absent,
153
+ a rendered capture is read as Rust's -- today's behaviour for every
154
+ caller that predates the second dialect (ruling R2, extending P10).
155
+ """
156
+ frames = sorted((f for cid in code_ids for f in trace.frames(code_id=cid)),
157
+ key=lambda f: f.id)
158
+ out: list[Site] = []
159
+ for f in frames:
160
+ env: dict = {}
161
+ caps: dict = {}
162
+ call = trace.event(f.call_event_id)
163
+ if call is not None:
164
+ _bind(env, caps, (call.payload or {}).get("args", {}), wanted,
165
+ dialect)
166
+ out.append(Site(call, dict(env), dict(caps)))
167
+ for e in trace.frame_events(f.id):
168
+ if e.kind != "LINE":
169
+ continue
170
+ p = e.payload or {}
171
+ _bind(env, caps, p.get("deltas", {}), wanted, dialect)
172
+ # THE fold that makes this command honest -- see the module
173
+ # docstring. Never conditional on there being deltas: a `del` on
174
+ # an otherwise inert line records an empty `deltas` and this list.
175
+ for n in p.get("unbound", []):
176
+ env.pop(n, None)
177
+ caps.pop(n, None)
178
+ out.append(Site(e, dict(env), dict(caps)))
179
+ out.sort(key=lambda s: s.event.id)
180
+ return out
181
+
182
+
183
+ # -- applying the predicate ------------------------------------------------
184
+ @dataclass
185
+ class Outcome:
186
+ hits: list
187
+ near: list # (margin, Site), closest first
188
+ misses: int
189
+ unavailable: dict # (name, reason) -> site count
190
+ errors: list # (Site, EvalError)
191
+
192
+ @property
193
+ def evaluated(self) -> int:
194
+ return len(self.hits) + self.misses
195
+
196
+ @property
197
+ def not_captured(self) -> int:
198
+ return sum(self.unavailable.values())
199
+
200
+
201
+ def evaluate(sites: list[Site], expr) -> Outcome:
202
+ out = Outcome([], [], 0, {}, [])
203
+ for s in sites:
204
+ try:
205
+ got = expr.eval(s.env)
206
+ except NotCaptured as nc:
207
+ key = (nc.name, nc.reason)
208
+ out.unavailable[key] = out.unavailable.get(key, 0) + 1
209
+ continue
210
+ except EvalError as ee:
211
+ out.errors.append((s, ee))
212
+ continue
213
+ if got:
214
+ out.hits.append(s)
215
+ continue
216
+ out.misses += 1
217
+ m = expr.margin(s.env)
218
+ if m is not None:
219
+ out.near.append((m, s))
220
+ out.near.sort(key=lambda t: (t[0], t[1].event.id))
221
+ return out
222
+
223
+
224
+ # -- rendering -------------------------------------------------------------
225
+ def _render(name: str, site: Site) -> str:
226
+ if name not in site.env:
227
+ return "<not in scope>"
228
+ v = site.env[name]
229
+ cap = site.caps.get(name) or {}
230
+ if v is REDACTED:
231
+ # NOT `fmt_value(cap)`, which is right for a listing and wrong
232
+ # here: `<redacted #01234567>` names WHICH value was taken, and
233
+ # what a predicate's state line has to say is that there was
234
+ # nothing to compare it with.
235
+ return REDACTED_STATE
236
+ if v is NOT_CAPTURED:
237
+ return f"<{cap.get('type', 'object')}; no comparable value>"
238
+ if v is TRUNCATED:
239
+ return f"<clipped to {len(cap.get('v', ''))} chars>"
240
+ if isinstance(v, _Sized):
241
+ return f"<{cap.get('type', 'container')} of length {v.n}>"
242
+ return fmt_value(cap)
243
+
244
+
245
+ def state_of(expr, site: Site) -> str:
246
+ return " ".join(f"{n}={_render(n, site)}" for n in sorted(expr.names))
247
+
248
+
249
+ def refocus_cmd(trace, codes) -> str:
250
+ """The exact command that re-records this run with these frames' locals.
251
+
252
+ `query/sites`' template, instantiated from this trace's own meta: the
253
+ command differs per recorder (`sensorium run`, `sensorium ts run`,
254
+ `cargo sensorium`) and naming the wrong one sends the reader to a
255
+ second refusal. Python's bytes are unchanged, and `tests/test_watch.py`
256
+ is the fence around them.
257
+ """
258
+ return rerun_command(trace, codes)
259
+
260
+
261
+ def _unframed(trace, c) -> bool:
262
+ """Coroutine/generator code: CALL events recorded, no frame ever opened.
263
+
264
+ One predicate for both callers below, so the note and the flag that
265
+ rewrites the NEVER RECORDED block can never disagree about which code
266
+ objects they are talking about -- the block's "(see the line above the
267
+ verdict)" points at a line only this decides to print.
268
+ """
269
+ return (bool(trace.unframed_calls(code_id=c.id))
270
+ and not trace.frames(code_id=c.id))
271
+
272
+
273
+ def unframed_note(trace, codes) -> list[str]:
274
+ """Which of the `--at` matches are coroutine/generator code -- recorded
275
+ as calls, never framed, so they contribute NO site. Returned as
276
+ (lines, all_unframed) would be two things; callers get the lines and
277
+ test `all_unframed_codes` separately."""
278
+ unf = [c for c in codes if _unframed(trace, c)]
279
+ if not unf:
280
+ return []
281
+ names = ", ".join(c.qualname for c in unf)
282
+ if len(unf) == len(codes):
283
+ return [f"--at matched only coroutine/generator code ({names}), which "
284
+ "opens no frame in this version: watch sites are frames, so "
285
+ "there are no sites here at all, and refocusing cannot change "
286
+ "that"]
287
+ return [f"{len(unf)} of the {len(codes)} matched code object(s) ({names}) "
288
+ "are coroutine/generator code: recorded as calls, never framed, "
289
+ "and contributed no site"]
290
+
291
+
292
+ def all_unframed_codes(trace, codes) -> bool:
293
+ return bool(codes) and all(_unframed(trace, c) for c in codes)
294
+
295
+
296
+ def _guidance(reason: str, name: str, ever: bool, has_line: bool,
297
+ trace, codes, all_unframed: bool = False) -> list[str]:
298
+ """What to actually do about a name that could not be evaluated.
299
+
300
+ The distinction that matters most: a name recorded at OTHER sites in
301
+ these frames is a scope fact, and telling a reader to refocus there sends
302
+ them to re-record a run that already holds what they need.
303
+ """
304
+ if reason == CONTAINER:
305
+ return ["its length was recorded and its contents only sampled; "
306
+ "compare the length instead"]
307
+ if reason == NO_VALUE:
308
+ return ["only its type and repr were recorded, so there is nothing to "
309
+ "compare; refocusing cannot change that"]
310
+ if reason == NO_LENGTH:
311
+ return ["what the trace holds there is the value itself -- a number, "
312
+ "a bool, or a rendering the recorder could only format -- "
313
+ "and none of those carries a recorded length; compare the "
314
+ "name itself instead"]
315
+ if reason == REDACTED_REASON:
316
+ # Ahead of the `ever` branch below, which would otherwise call this
317
+ # a scope fact and send a reader hunting a binding bug that is not
318
+ # there: the name IS captured at these sites, and the rule took
319
+ # what was in it.
320
+ return ["the redaction rule took it at the recorder, before "
321
+ "anything reached disk, so no re-reading of this trace "
322
+ f"holds a value; a state line shows such a name as "
323
+ f"{REDACTED_STATE}",
324
+ # The REMEDY, not just the diagnosis. The rule runs at
325
+ # record time, so the only thing that changes this answer
326
+ # is recording again with the name allowed -- and the
327
+ # allow list is compared after the same normalisation the
328
+ # rule uses, so the binding's own spelling is the value to
329
+ # set. Named in one command with the re-run, because
330
+ # exporting the variable and forgetting to re-record is
331
+ # the obvious way to follow this advice and get nowhere.
332
+ f"re-record with that name allowed, where its value is "
333
+ f"not a secret: export {redact.ALLOW_VAR}="
334
+ f"{shlex.quote(name)} && {refocus_cmd(trace, codes)}"]
335
+ if reason == CLIPPED:
336
+ return ["the capture is a prefix cut at the string cap, so the value "
337
+ "itself was never recorded",
338
+ f"see the caps this run used with: sensorium info "
339
+ f"{shlex.quote(trace.path.stem)}"]
340
+ if ever:
341
+ # How a name leaves scope is the LANGUAGE's fact, so the tail comes
342
+ # from the trace's own column: this sentence named `del` and
343
+ # `except E as e:` on a Rust and a TypeScript trace alike, which is
344
+ # two Python statements offered as advice to a reader of neither.
345
+ return ["recorded at other sites in these frames, so this is scope, "
346
+ "not capture depth:",
347
+ *terms(trace).scope_exit_note]
348
+ if not has_line:
349
+ if all_unframed:
350
+ return ["no site exists for these code objects: coroutine/"
351
+ "generator code opens no frame in this version"]
352
+ return ["no local of these frames was recorded at all -- line capture "
353
+ "is opt-in at record time",
354
+ "refocus and re-run: " + refocus_cmd(trace, codes)]
355
+ return [f"this run recorded locals for these frames but never a "
356
+ f"{name!r}; check the spelling, or widen --at"]
357
+
358
+
359
+ def print_never_recorded(ghosts: list[str],
360
+ all_unframed: bool = False) -> None:
361
+ """Names the predicate needs that NO site in these frames ever bound.
362
+
363
+ The hole short-circuiting leaves, and it defeats the rule this command is
364
+ built on. `n > 1000 and ghost > 1` is decided entirely by `n` at every
365
+ site where `n` is small -- logically sound, and it means a typo'd or
366
+ never-focused conjunct is absorbed in SILENCE: the tally reports
367
+ `not-captured: 0` and the verdict comes back as strong as this command can
368
+ make it, with no mention of `ghost` anywhere. A predicate the reader
369
+ believes is checking two things, checking one, and reading as maximally
370
+ clean, is exactly the "could not evaluate" masquerading as "the invariant
371
+ held" that everything else here is built to prevent.
372
+
373
+ The `or` mirror is milder only by accident (a hit renders a state line
374
+ naming the name), so it is not relied on: both are warned, above the
375
+ verdict, and the verdict itself refuses to come back clean.
376
+ """
377
+ if not ghosts:
378
+ return
379
+ names = ", ".join(repr(g) for g in ghosts)
380
+ print(f"NEVER RECORDED: {names} -- named by the predicate, captured at NO "
381
+ "site in these frames")
382
+ print(" every result below was decided WITHOUT it: nothing in this trace "
383
+ "witnesses that name")
384
+ if all_unframed:
385
+ print(" there are no frames here at all: --at matched only "
386
+ "coroutine/generator code, which opens no frame in this version "
387
+ "(see the line above the verdict)")
388
+ else:
389
+ print(" either it is misspelled, or it lives in frames this run did "
390
+ "not record")
391
+
392
+
393
+ def print_unavailable(trace, out: Outcome, sites, ever, codes,
394
+ n_sites: int, all_unframed: bool = False) -> None:
395
+ if not out.unavailable:
396
+ return
397
+ has_line = any(s.event.kind == "LINE" for s in sites)
398
+ print(f"not captured at {out.not_captured} of {n_sites} site(s) -- the "
399
+ "predicate could not be checked there:")
400
+ for (name, reason), n in sorted(out.unavailable.items(),
401
+ key=lambda kv: (-kv[1], kv[0])):
402
+ print(f" {name}: {reason.replace('NAME', name)} [{n} site(s)]")
403
+ for line in _guidance(reason, name, name in ever, has_line,
404
+ trace, codes, all_unframed):
405
+ print(f" {line}")
406
+
407
+
408
+ def print_errors(out: Outcome) -> None:
409
+ if not out.errors:
410
+ return
411
+ print(f"errors: {len(out.errors)} site(s) raised while applying the "
412
+ "predicate (neither a hit nor a miss):")
413
+ for site, err in out.errors[:_MAX_LISTED_ERRORS]:
414
+ print(f" e{site.event.id}: {err}")
415
+ extra = len(out.errors) - _MAX_LISTED_ERRORS
416
+ if extra > 0:
417
+ print(f" ... {extra} further site(s) raised the same way")
418
+
419
+
420
+ def unchecked_caveats(out: Outcome, n_sites: int) -> list[str]:
421
+ """The buckets that make ANY verdict partial, hit or no hit.
422
+
423
+ Named separately rather than summed: "could not be evaluated" and "raised
424
+ while being applied" have different causes and different fixes, and a
425
+ reader discounting a verdict needs to know which one they are looking at.
426
+
427
+ Both paths use this. The hit path used to name only the errors, so a
428
+ confident SATISFIED could sit above 14 of 20 sites that went unchecked --
429
+ the same "reads cleaner than the evidence supports" failure as a phantom
430
+ name, arriving through the other branch.
431
+ """
432
+ caveats = []
433
+ if out.not_captured:
434
+ caveats.append(f"{out.not_captured} of {n_sites} recorded site(s) "
435
+ "could NOT be evaluated")
436
+ if out.errors:
437
+ caveats.append(f"{len(out.errors)} of {n_sites} recorded site(s) "
438
+ "raised while the predicate was applied")
439
+ return caveats
440
+
441
+
442
+ class Says(Enum):
443
+ """Which of three things a verdict says, as its own value.
444
+
445
+ The split that has to survive into the exit status is the module
446
+ docstring's last one: `hits: 0` because every evaluated site failed
447
+ (NOT_SATISFIED) versus `hits: 0` because nothing could be evaluated at
448
+ all (NOTHING_CHECKED). An agent branching on the status never reaches
449
+ the prose, so a NOTHING_CHECKED leaving as a 0 is "I could not check"
450
+ read as "the invariant held" -- this command's worst outcome, arriving
451
+ through the one channel the prose cannot qualify.
452
+
453
+ A partially-checked run is NOT a fourth class. Some sites evaluated and
454
+ some did not is still the trace answering "no" about the ones it could
455
+ check, so it reads NOT_SATISFIED, and the count it could not check is
456
+ carried in the caveat line rather than in the status (plan X7). Only a
457
+ run where NOTHING evaluated has no answer to give.
458
+ """
459
+ SATISFIED = auto()
460
+ NOT_SATISFIED = auto()
461
+ NOTHING_CHECKED = auto()
462
+
463
+
464
+ # The convention, applied once. NOT_SATISFIED is the trace answering "no"
465
+ # about what it recorded; NOTHING_CHECKED is the trace unable to answer at
466
+ # all, which is fixed by recording again, not by asking differently.
467
+ STATUS = {Says.SATISFIED: ANSWERED,
468
+ Says.NOT_SATISFIED: NEGATIVE,
469
+ Says.NOTHING_CHECKED: UNSETTLED}
470
+
471
+
472
+ @dataclass(frozen=True)
473
+ class Verdict:
474
+ """What the verdict says, and which of the three it is.
475
+
476
+ The class travels WITH the lines because only `verdict` knows which
477
+ branch it took. `run` could recover it by matching "NOTHING WAS CHECKED"
478
+ in the printed text -- and then the exit status would depend on the
479
+ wording of a sentence this command rewrites whenever it can be made
480
+ clearer, silently turning a 3 back into a 0 on the next rewording. The
481
+ same reasoning, and the same shape, as `frame._resolve`.
482
+ """
483
+ says: Says
484
+ lines: list[str]
485
+
486
+
487
+ def verdict(out: Outcome, n_sites: int, ghosts: list[str]) -> Verdict:
488
+ decided_without = ("the predicate was decided WITHOUT "
489
+ + ", ".join(repr(g) for g in ghosts))
490
+ caveats = unchecked_caveats(out, n_sites)
491
+ if out.hits:
492
+ lines = [f"verdict: SATISFIED at {len(out.hits)} of the "
493
+ f"{out.evaluated} site(s) the predicate could be evaluated "
494
+ "at"]
495
+ if caveats:
496
+ lines.append(" but " + ", and ".join(caveats) + ", so these are "
497
+ "not necessarily every time it held")
498
+ if ghosts:
499
+ lines.append((" and " if caveats else " but ") + decided_without
500
+ + ", so these hits do not answer the whole predicate")
501
+ return Verdict(Says.SATISFIED, lines)
502
+ if out.evaluated == 0:
503
+ return Verdict(Says.NOTHING_CHECKED, [
504
+ "verdict: NOTHING WAS CHECKED -- the predicate could not be "
505
+ f"evaluated at any of the {n_sites} recorded site(s)",
506
+ " 'hits: 0' here means 'could not evaluate', NOT 'the "
507
+ "invariant held'"])
508
+ if ghosts:
509
+ caveats.append(decided_without)
510
+ if caveats:
511
+ return Verdict(Says.NOT_SATISFIED, [
512
+ f"verdict: not satisfied at any of the {out.evaluated} site(s)"
513
+ f" that could be evaluated -- but " + ", and ".join(caveats)
514
+ + ",",
515
+ " so this is not a claim that the invariant held"])
516
+ return Verdict(Says.NOT_SATISFIED, [
517
+ f"verdict: not satisfied at any of the {n_sites} recorded "
518
+ "site(s), every one of which was evaluated",
519
+ " that is a fact about what was RECORDED, not a claim that the "
520
+ "invariant held: only recorded sites were checked"])
521
+
522
+
523
+ def continue_cmd(args, **over) -> str:
524
+ """The exact command that shows more of *this* watch."""
525
+ opts = {"--at": args.at, "--expr": args.expr, "--limit": str(args.limit),
526
+ "--misses": str(args.misses), **over}
527
+ parts = ["sensorium", "watch", shlex.quote(args.run)]
528
+ for flag, val in opts.items():
529
+ parts += [flag, shlex.quote(str(val))]
530
+ return " ".join(parts)
531
+
532
+
533
+ def print_near(trace, expr, out: Outcome, args) -> None:
534
+ if out.hits:
535
+ return
536
+ if not out.near:
537
+ if not expr.has_boundary:
538
+ print("no near-misses: a near-miss distance is only defined for a "
539
+ "single numeric ordering comparison")
540
+ print(f" ({args.expr!r} has no boundary to approach; try one of "
541
+ "< <= > >= over numbers)")
542
+ return
543
+ shown = out.near[:args.misses]
544
+ print(f"near-misses -- the {len(shown)} closest approach(es); every one "
545
+ "of them FAILED the predicate:")
546
+ for m, s in shown:
547
+ print(f" margin {m:g}: {fmt_event(trace, s.event)} "
548
+ f"state: {state_of(expr, s)}")
549
+ withheld = len(out.near) - len(shown)
550
+ if withheld > 0:
551
+ print(f"... {withheld} further near-miss(es) not shown; see them "
552
+ f"with: {continue_cmd(args, **{'--misses': len(out.near)})}")
553
+
554
+
555
+ def print_hits(trace, expr, out: Outcome, args) -> None:
556
+ shown = out.hits[:args.limit]
557
+ for s in shown:
558
+ print(f" HIT {fmt_event(trace, s.event)} "
559
+ f"state: {state_of(expr, s)}")
560
+ if not shown:
561
+ return
562
+ last = f"e{shown[-1].event.id}"
563
+ note = more_note(len(out.hits), len(shown),
564
+ continue_cmd(args, **{"--after": last}))
565
+ if note:
566
+ print(note)
567
+
568
+
569
+ def _no_match(trace, args) -> int:
570
+ print(f"error: no recorded code matches --at {args.at!r}")
571
+ # Spelled the way this recorder's own sites are spelled everywhere
572
+ # else: a listing a reader is meant to pick their next `--at` out of is
573
+ # useless if the forms in it are not forms `--at` takes.
574
+ names = sorted({spell_site(trace, c) for c in trace.codes()})
575
+ print(f"this trace recorded {len(names)} code object(s):")
576
+ for n in names[:_MAX_LISTED_CODES]:
577
+ print(f" {n}")
578
+ extra = len(names) - _MAX_LISTED_CODES
579
+ if extra > 0:
580
+ print(f" ... and {extra} more (sensorium info "
581
+ f"{shlex.quote(args.run)} lists the hot ones)")
582
+ # The trace answering "no": it holds code, and none of it is what --at
583
+ # named. The listing above is what it does hold, so the next move is a
584
+ # different --at, not a different recording.
585
+ return NEGATIVE
586
+
587
+
588
+ def run(args) -> int:
589
+ for flag, val in (("--limit", args.limit), ("--misses", args.misses)):
590
+ if val < 1:
591
+ # `--misses 0` is refused for the same reason as `--limit 0`,
592
+ # and for one more: near-misses are the answer when nothing hit,
593
+ # so a flag that silently suppresses them is a way to make a run
594
+ # look clean without changing a thing about the run.
595
+ print(f"{flag} must be >= 1 (got {val}); "
596
+ "there is no useful zero-row page")
597
+ return BAD_CALL
598
+ try:
599
+ expr = compile_expr(args.expr)
600
+ except ExprError as e:
601
+ print(f"error: {e}")
602
+ return BAD_CALL
603
+ after = parse_eref(args.after) if args.after else 0
604
+ trace = Trace.open(paths.find_trace(args.run))
605
+ refusal = require(trace, "line", "watch")
606
+ if refusal:
607
+ print(f"REFUSED: {refusal}")
608
+ # UNSETTLED, not BAD_CALL: the command is spelled correctly and the
609
+ # trace is readable -- it simply holds no LINE event, because the
610
+ # recorder said it produces none. Nothing about the call can fix
611
+ # that; only a recording that captures lines can.
612
+ return UNSETTLED
613
+ codes = [c for c in trace.codes() if site_matches(c, args.at, trace)]
614
+ if not codes:
615
+ return _no_match(trace, args)
616
+
617
+ # Which formatter wrote this trace's rendered captures, read from the
618
+ # trace and never guessed from a text: `'rate'` is a string in one
619
+ # dialect and a five-character word in the other, and a predicate
620
+ # answered in the wrong one comes back a quiet, wrong False.
621
+ all_sites = sites_for(trace, [c.id for c in codes], expr.names,
622
+ for_trace(trace))
623
+ sites = [s for s in all_sites if s.event.id > after]
624
+ out = evaluate(sites, expr)
625
+ n = len(sites)
626
+ # Computed over the WHOLE run, never the --after page: a name recorded
627
+ # only before the cut is a scope fact, not a name the trace never held.
628
+ ever = {nm for s in all_sites for nm in s.caps}
629
+ ghosts = sorted(expr.names - ever)
630
+
631
+ print(f"watch {args.expr!r} at {args.at} in {trace.path.stem}")
632
+ for line in CLAIM:
633
+ print(" " + line)
634
+ print_incomplete(trace, "the sites below are not all the sites this "
635
+ "run had")
636
+ # Every bucket, so the arithmetic is checkable: sites = evaluated +
637
+ # not-captured + errors.
638
+ print(f"sites: {n} evaluated: {out.evaluated} hits: {len(out.hits)}"
639
+ f" not-captured: {out.not_captured} errors: {len(out.errors)}")
640
+ skipped = len(all_sites) - n
641
+ if skipped:
642
+ print(f"({skipped} earlier site(s) skipped by --after e{after})")
643
+ for line in unframed_note(trace, codes):
644
+ print(line)
645
+ all_unf = all_unframed_codes(trace, codes)
646
+ # Above the verdict on purpose: the verdict cannot be read without it.
647
+ print_never_recorded(ghosts, all_unf)
648
+ v = verdict(out, n, ghosts)
649
+ for line in v.lines:
650
+ print(line)
651
+ print_hits(trace, expr, out, args)
652
+ print_unavailable(trace, out, sites, ever, codes, n, all_unf)
653
+ print_errors(out)
654
+ print_near(trace, expr, out, args)
655
+ # The status IS the verdict, mapped once: the sentence above and the
656
+ # number the caller branches on must never be able to disagree.
657
+ return STATUS[v.says]
File without changes