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
sensorium/c/plan.py ADDED
@@ -0,0 +1,277 @@
1
+ """Capture plans. One plan per image, addresses are unrelocated low_pc.
2
+
3
+ SysV x86-64 return class, simplified
4
+ ------------------------------------
5
+ void (no type): RET_VOID, nreg 0, size 0.
6
+
7
+ Base float, double, and a 16-byte float (__float128, and long double,
8
+ which this pass does not put in x87): RET_SSE, nreg 1, or nreg 2 when
9
+ the size is greater than 8 and at most 16. Larger than 16 is RET_MEM.
10
+
11
+ Integers, enums, and pointers: RET_INT, nreg 1, or nreg 2 for a value
12
+ wider than 8 and at most 16 (__int128). Wider than 16 is RET_MEM.
13
+
14
+ Struct, union, class, and array: split into 8-byte eightbytes.
15
+
16
+ * An eightbyte is INTEGER if it holds any integer, pointer, or enum,
17
+ SSE if it holds only float or double.
18
+ * MEMORY if a member crosses an eightbyte boundary, the aggregate is
19
+ larger than 16 bytes, it needs more than two eightbytes, a field is
20
+ unaligned for its type, or it has a flexible array member.
21
+ * Merging two classes in one eightbyte: MEMORY if either is MEMORY,
22
+ else INTEGER if either is INTEGER, else SSE.
23
+ * More than two INTEGER or two SSE registers is MEMORY.
24
+
25
+ A mix of INTEGER and SSE eightbytes does not fit one plan class. INTEGER
26
+ wins for the label (RET_INT) and the eightbyte map is stored on the type
27
+ so the decoder can pull each eightbyte from rax/rdx or xmm0/xmm1. The V
28
+ record always carries all four registers.
29
+
30
+ RET_MEM records the real byte size up to 4096. The runtime caps the copy
31
+ at 256. RET_INT and RET_SSE store ret_size 0 and ret_nreg 1 or 2.
32
+ """
33
+ from __future__ import annotations
34
+
35
+ from sensorium.c.format import (
36
+ FLAG_CSTR, NO_SLOT, RET_INT, RET_MEM, RET_SSE, RET_VOID, FuncPlan,
37
+ ParamPlan, write_plan,
38
+ )
39
+
40
+ _CAP = 4096
41
+
42
+
43
+ def write_image_plan(elf_path, out_path) -> None:
44
+ """Write ``out_path`` for ``elf_path`` via ``format.write_plan``."""
45
+ from sensorium.c.dwarf import DwarfImage
46
+
47
+ image = DwarfImage(elf_path)
48
+ funcs = []
49
+ for addr, fn in image.funcs.items():
50
+ params = []
51
+ for p in fn.params:
52
+ if p.off is None:
53
+ params.append(ParamPlan(NO_SLOT, 0, 0))
54
+ continue
55
+ size = p.typ.size if p.typ is not None else 0
56
+ if size < 0:
57
+ size = 0
58
+ if size > 256:
59
+ size = 256
60
+ flags = FLAG_CSTR if p.typ is not None and p.typ.is_cstr else 0
61
+ params.append(ParamPlan(int(p.off), int(size), int(flags)))
62
+ funcs.append(FuncPlan(int(addr), int(fn.ret_class), int(fn.ret_nreg),
63
+ int(fn.ret_size), tuple(params)))
64
+ write_plan(out_path, funcs)
65
+
66
+
67
+ def classify_return(typ):
68
+ """(ret_class, ret_nreg, ret_size) for a resolved type."""
69
+ if typ is None or typ.kind == "void":
70
+ return RET_VOID, 0, 0
71
+ if typ.kind == "float":
72
+ return _scalar(RET_SSE, typ.size)
73
+ if typ.kind in ("int", "bool", "ptr", "enum"):
74
+ return _scalar(RET_INT, typ.size)
75
+ if typ.kind in ("struct", "union", "array"):
76
+ return _aggregate(typ)
77
+ return _scalar(RET_INT, typ.size)
78
+
79
+
80
+ def _scalar(cls, size):
81
+ size = size or 0
82
+ if size <= 0:
83
+ return cls, 0, 0
84
+ if size <= 8:
85
+ return cls, 1, 0
86
+ if size <= 16:
87
+ return cls, 2, 0
88
+ return RET_MEM, 0, min(size, _CAP)
89
+
90
+
91
+ def _mem(typ):
92
+ return RET_MEM, 0, min(max(typ.size or 0, 0), _CAP)
93
+
94
+
95
+ def _aggregate(typ):
96
+ if _flex(typ, set()) or (typ.size or 0) > 16:
97
+ return _mem(typ)
98
+ if not _aligned(typ, 0, set()):
99
+ return _mem(typ)
100
+ leaves = []
101
+ if not _leaves(typ, 0, leaves, set()):
102
+ return _mem(typ)
103
+ size = typ.size or 0
104
+ if size <= 0:
105
+ return RET_INT, 0, 0
106
+ n = (size + 7) // 8
107
+ if n > 2:
108
+ return _mem(typ)
109
+ classes = ["NO"] * n
110
+ for off, width, cls in leaves:
111
+ if width <= 0:
112
+ continue
113
+ start = off // 8
114
+ end = (off + width - 1) // 8
115
+ if start != end or not 0 <= start < n:
116
+ return _mem(typ)
117
+ classes[start] = _merge(classes[start], cls)
118
+ if "MEM" in classes:
119
+ return _mem(typ)
120
+ ints = sum(c == "INT" for c in classes)
121
+ sses = sum(c == "SSE" for c in classes)
122
+ if ints > 2 or sses > 2:
123
+ return _mem(typ)
124
+ used = tuple(c for c in classes if c in ("INT", "SSE"))
125
+ if not used:
126
+ return RET_INT, 0, 0
127
+ if ints and sses:
128
+ # Both register files. INTEGER wins the plan class; the map tells
129
+ # the decoder which file each eightbyte came from.
130
+ typ.eights = used
131
+ return RET_INT, len(used), 0
132
+ if ints:
133
+ return RET_INT, ints, 0
134
+ return RET_SSE, sses, 0
135
+
136
+
137
+ def _merge(a, b):
138
+ if a == "NO" or a is None:
139
+ return b
140
+ if b == "NO" or b is None:
141
+ return a
142
+ if a == "MEM" or b == "MEM":
143
+ return "MEM"
144
+ if a == "INT" or b == "INT":
145
+ return "INT"
146
+ return "SSE"
147
+
148
+
149
+ def _cross(off, size):
150
+ if size <= 0:
151
+ return False
152
+ return off // 8 != (off + size - 1) // 8
153
+
154
+
155
+ def _leaves(typ, base, out, stack):
156
+ if typ is None:
157
+ return False
158
+ mark = id(typ)
159
+ if mark in stack:
160
+ return False
161
+ if typ.kind in ("struct", "union"):
162
+ stack.add(mark)
163
+ try:
164
+ for m in typ.members or ():
165
+ if m.bit_size:
166
+ if m.bit_pos is None or _bit_cross(m.bit_pos, m.bit_size):
167
+ return False
168
+ out.append((m.bit_pos // 8, 1, "INT"))
169
+ continue
170
+ if not _leaves(m.typ, base + m.offset, out, stack):
171
+ return False
172
+ return True
173
+ finally:
174
+ stack.discard(mark)
175
+ if typ.kind == "array":
176
+ if typ.count is None or typ.elem is None:
177
+ return False
178
+ stack.add(mark)
179
+ try:
180
+ es = typ.elem.size or 0
181
+ for i in range(typ.count):
182
+ if not _leaves(typ.elem, base + i * es, out, stack):
183
+ return False
184
+ return True
185
+ finally:
186
+ stack.discard(mark)
187
+ if typ.kind == "float":
188
+ if _cross(base, typ.size):
189
+ return False
190
+ out.append((base, typ.size, "SSE"))
191
+ return True
192
+ if _cross(base, typ.size or 1):
193
+ return False
194
+ out.append((base, typ.size or 1, "INT"))
195
+ return True
196
+
197
+
198
+ def _bit_cross(bit_pos, bit_size):
199
+ if bit_size <= 0:
200
+ return False
201
+ return bit_pos // 64 != (bit_pos + bit_size - 1) // 64
202
+
203
+
204
+ def _flex(typ, stack):
205
+ if typ is None:
206
+ return False
207
+ mark = id(typ)
208
+ if mark in stack:
209
+ return False
210
+ if typ.kind == "array":
211
+ return typ.count is None
212
+ if typ.kind in ("struct", "union"):
213
+ stack.add(mark)
214
+ try:
215
+ return any(_flex(m.typ, stack) for m in (typ.members or ()))
216
+ finally:
217
+ stack.discard(mark)
218
+ return False
219
+
220
+
221
+ def _nat(size):
222
+ if size >= 16:
223
+ return 16
224
+ if size >= 8:
225
+ return 8
226
+ if size >= 4:
227
+ return 4
228
+ if size >= 2:
229
+ return 2
230
+ return 1
231
+
232
+
233
+ def _align(typ):
234
+ if typ is None:
235
+ return 1
236
+ if typ.kind == "ptr":
237
+ return 8
238
+ if typ.kind in ("int", "bool", "float", "enum"):
239
+ return _nat(typ.size or 1)
240
+ if typ.kind == "array":
241
+ return _align(typ.elem)
242
+ if typ.kind in ("struct", "union"):
243
+ als = [_align(m.typ) for m in (typ.members or ()) if not m.bit_size]
244
+ return max(als) if als else 1
245
+ return 1
246
+
247
+
248
+ def _aligned(typ, base, stack):
249
+ if typ is None:
250
+ return True
251
+ mark = id(typ)
252
+ if mark in stack:
253
+ return True
254
+ if typ.kind == "struct":
255
+ stack.add(mark)
256
+ try:
257
+ for m in typ.members or ():
258
+ if m.bit_size:
259
+ continue
260
+ if (base + m.offset) % _align(m.typ) != 0:
261
+ return False
262
+ if not _aligned(m.typ, base + m.offset, stack):
263
+ return False
264
+ return True
265
+ finally:
266
+ stack.discard(mark)
267
+ if typ.kind == "union":
268
+ stack.add(mark)
269
+ try:
270
+ return all(
271
+ _aligned(m.typ, base + m.offset, stack)
272
+ for m in (typ.members or ()) if not m.bit_size)
273
+ finally:
274
+ stack.discard(mark)
275
+ if typ.kind == "array" and typ.elem is not None:
276
+ return _aligned(typ.elem, base, stack)
277
+ return True
sensorium/cli.py ADDED
@@ -0,0 +1,140 @@
1
+ """sensorium command-line interface.
2
+
3
+ Every `main()` return is appended to the invocation log (see
4
+ `sensorium.invocations`) after dispatch, including the version guard
5
+ below and the three exception classes caught around `args.func(args)`.
6
+ The one shape this never sees is any argparse exit: a parse failure and
7
+ `--help`/`--version` alike raise `SystemExit` straight out of
8
+ `argparse.parse_args`, before dispatch, so both escape `main()` without
9
+ a record -- do not wrap it.
10
+ """
11
+ import argparse
12
+ import sys
13
+
14
+ from sensorium import invocations, paths
15
+ from sensorium.mcp import cmd as mcp_cmd
16
+ from sensorium.query import (diff_cmd, exceptions_cmd, failures_cmd, flow_cmd,
17
+ fmt, frame_cmd, grep_cmd, info_cmd, redact_cmd,
18
+ refocus_cmd, runs_cmd, tree_cmd, watch_cmd)
19
+ from sensorium.store import db
20
+ from sensorium.store.gc import add_parsers as add_gc_parsers
21
+ from sensorium.c import cli as c_cli
22
+ from sensorium.ts import cli as ts_cli
23
+
24
+ _QUERY_MODULES = [runs_cmd, info_cmd, tree_cmd, frame_cmd, grep_cmd,
25
+ exceptions_cmd, failures_cmd, flow_cmd, watch_cmd, diff_cmd,
26
+ refocus_cmd, redact_cmd]
27
+
28
+
29
+ def _add_run_parser(sub):
30
+ p = sub.add_parser(
31
+ "run", help="record one execution",
32
+ description="Runs the command under the recorder from `cwd` and "
33
+ "writes one trace; only code under `cwd` is recorded; "
34
+ "the command is a .py file, a `-m` module or a console "
35
+ "script, never `python` itself.",
36
+ epilog="exit: the target's own status")
37
+ p.add_argument("--focus", action="append", default=[],
38
+ help="pkg.module or pkg.module:qualname; repeatable")
39
+ p.add_argument("--include", action="append", default=[],
40
+ help="glob matched against each file's path relative "
41
+ "to the working directory; when given, only the "
42
+ "files it matches are recorded; repeatable")
43
+ p.add_argument("--exclude", action="append", default=[],
44
+ help="glob matched against each file's path relative "
45
+ "to the working directory; a file it matches is "
46
+ "never recorded; repeatable")
47
+ p.add_argument("--window", default=None,
48
+ help="limit --focus line capture to what runs inside this "
49
+ "function's activations; MODULE:QUALNAME scopes to one "
50
+ "function, a bare QUALNAME matches that name in any "
51
+ "module")
52
+ p.add_argument("--max-events", default=None,
53
+ help="stop storing events after this many (0 is unlimited)")
54
+ p.add_argument("--max-bytes", default=None,
55
+ help="stop storing events after the trace reaches this "
56
+ "size, for example 8M (0 is unlimited)")
57
+ p.add_argument("--max-calls", default=None,
58
+ help="store at most this many calls of each function; "
59
+ "later calls are counted and marked elided "
60
+ "(0 is unlimited)")
61
+ p.add_argument("--no-cap", action="store_true",
62
+ help="record without an event, size, or per-function cap")
63
+ p.add_argument("--no-children", action="store_true",
64
+ help="do not record Python child processes (subprocess, "
65
+ "multiprocessing, pytest-xdist) into this run; "
66
+ "SENSORIUM_NO_CHILDREN=1 does the same")
67
+ p.add_argument("--run-id", default=None, help=argparse.SUPPRESS)
68
+ p.add_argument("--refocus-of", default=None, help=argparse.SUPPRESS)
69
+ p.add_argument("target", nargs=argparse.REMAINDER)
70
+ p.set_defaults(func=_run)
71
+
72
+
73
+ def _run(args) -> int:
74
+ from sensorium.record import boot
75
+ target = list(args.target)
76
+ if target and target[0] == "--":
77
+ target = target[1:]
78
+ if not target:
79
+ print("usage: sensorium run [options] -- <command> [args...]",
80
+ file=sys.stderr)
81
+ return 2
82
+ from sensorium.limits import LimitsError, resolve
83
+ try:
84
+ limits = resolve(max_events=args.max_events, max_bytes=args.max_bytes,
85
+ max_calls=args.max_calls, no_cap=args.no_cap)
86
+ except LimitsError as e:
87
+ print(f"error: {e}", file=sys.stderr)
88
+ return 2
89
+ try:
90
+ from sensorium.record.children import children_enabled
91
+ run_id, exit_status = boot.run_target(
92
+ target, focus=args.focus, include=args.include,
93
+ exclude=args.exclude, window=args.window,
94
+ run_id=args.run_id, refocus_of=args.refocus_of, limits=limits,
95
+ record_children=False if args.no_children else children_enabled())
96
+ except boot.TargetError as e:
97
+ print(f"error: {e}", file=sys.stderr)
98
+ return 2
99
+ print(f"run: {run_id}")
100
+ print(f"trace: {paths.traces_dir() / (run_id + '.db')}")
101
+ return exit_status
102
+
103
+
104
+ def main(argv=None) -> int:
105
+ # The argv the invocation log records: what this call received, never
106
+ # the environment or the working directory.
107
+ recorded_argv = list(argv) if argv is not None else list(sys.argv[1:])
108
+ if sys.version_info < (3, 12):
109
+ print("sensorium requires Python 3.12+ (sys.monitoring); running "
110
+ f"under {sys.version.split()[0]}", file=sys.stderr)
111
+ invocations.record(recorded_argv, 2, None)
112
+ return 2
113
+ parser = argparse.ArgumentParser(
114
+ prog="sensorium",
115
+ description="Record a program's execution; query what actually "
116
+ "happened. `sensorium run` records Python, `cargo "
117
+ "sensorium` records Rust, `sensorium ts run` records "
118
+ "TypeScript and `sensorium c run` records C; every "
119
+ "query below reads any of the four traces.")
120
+ sub = parser.add_subparsers(dest="cmd", required=True)
121
+ _add_run_parser(sub)
122
+ ts_cli.add_parser(sub)
123
+ c_cli.add_parser(sub)
124
+ mcp_cmd.add_parser(sub)
125
+ add_gc_parsers(sub)
126
+ for mod in _QUERY_MODULES:
127
+ mod.add_parser(sub)
128
+ args = parser.parse_args(argv)
129
+ error = None
130
+ try:
131
+ exit_status = args.func(args)
132
+ except (paths.TraceLookupError, fmt.RefError, db.TraceFormatError) as e:
133
+ # "the reference you gave does not name anything", or "this trace is
134
+ # from a newer sensorium" -- user-facing conditions every query command
135
+ # can hit, and never a reason to hand back a traceback.
136
+ print(f"error: {e}", file=sys.stderr)
137
+ exit_status = 2
138
+ error = type(e).__name__
139
+ invocations.record(recorded_argv, exit_status, error)
140
+ return exit_status
sensorium/driver.py ADDED
@@ -0,0 +1,47 @@
1
+ """Which `cargo-sensorium` this box will use, resolved in ONE place.
2
+
3
+ The rule is two lines long and was written out three times: in
4
+ `query/refocus_rust.py` (what a `refocus` re-runs with), in
5
+ `corpus/run_corpus.py` (what a corpus case records with), and in
6
+ `tests/test_focus_refusal.py` (what its skip is decided on). They agreed,
7
+ and a parametrised test held them to it -- but agreement kept by a test is
8
+ agreement that has to be re-established after every edit, and the three
9
+ answers have to be the SAME answer or a corpus case records with one binary
10
+ and its `refocus` question re-runs with another.
11
+
12
+ It lives under `src/sensorium/` because that is the only one of the three
13
+ trees all three can reach. `corpus/` is a development tree beside the
14
+ package and is not in the wheel (`pyproject.toml` packages `src/sensorium`
15
+ only), so a query command importing it would work from a checkout and fail
16
+ from an install; `tests/` is no better. The dependency runs the other way
17
+ here -- the corpus and the suite already require `sensorium` to be
18
+ importable, since the corpus records by running `python -m sensorium`.
19
+ """
20
+ import os
21
+ import shutil
22
+
23
+ #: The variable that names the driver, and the only one. CI's `rust` job
24
+ #: builds a binary and sets it; so does a developer with a release build on
25
+ #: a second disk. Written down here so a reader looking for "how do I point
26
+ #: this at my build" finds one name and not three copies of it.
27
+ ENV_VAR = "SENSORIUM_CARGO_SENSORIUM"
28
+
29
+
30
+ def cargo_sensorium() -> str | None:
31
+ """The `cargo-sensorium` binary to use, or None when there is none.
32
+
33
+ `SENSORIUM_CARGO_SENSORIUM` first, then PATH. An EMPTY variable is not a
34
+ driver -- `or` and not a presence test, so `SENSORIUM_CARGO_SENSORIUM=`
35
+ falls through to PATH rather than resolving to `""` and failing later at
36
+ exec time with a message about an empty command.
37
+
38
+ None is not an error. It is the ordinary state of the Python CI matrix,
39
+ which has no Rust toolchain: the corpus reports the cases it cannot
40
+ record as skipped BY NAME, and `refocus` refuses a Rust re-run with a
41
+ sentence that says what is missing. Both of those readings need to be
42
+ told "no driver" rather than handed a path that does not exist.
43
+
44
+ `shutil.which` is called through the module (never `from shutil import
45
+ which`) so a test can patch it where every caller sees the patch.
46
+ """
47
+ return os.environ.get(ENV_VAR) or shutil.which("cargo-sensorium")
sensorium/exit.py ADDED
@@ -0,0 +1,33 @@
1
+ """The query CLI's exit status is the caller's next action, not a health code.
2
+
3
+ 0 the question was answered affirmatively: the trace says yes.
4
+ 1 the question was answered negatively: the trace says no, or none.
5
+ 2 the call is wrong: edit the command and ask again.
6
+ 3 the trace cannot settle it: change the recording and re-record.
7
+ """
8
+
9
+ ANSWERED = 0
10
+ """The trace answered affirmatively -- what was asked for is in the output."""
11
+
12
+ NEGATIVE = 1
13
+ """The trace answered negatively -- no match, no frame, no exception, none."""
14
+
15
+ BAD_CALL = 2
16
+ """The call is wrong -- a bad flag, a bad ref, an unreadable trace."""
17
+
18
+ UNSETTLED = 3
19
+ """The trace cannot settle the question -- record again with what it lacks."""
20
+
21
+ #: Each status as the sentence a caller is told, for a surface
22
+ #: that hands back a status instead of printing this module's
23
+ #: docstring: an MCP client shows the four words, never the
24
+ #: convention. Keyed by the constants, so a status that moved
25
+ #: takes its sentence with it.
26
+ MEANING = {
27
+ ANSWERED: "the trace answered affirmatively",
28
+ NEGATIVE: "the trace answered negatively -- no match, no frame, "
29
+ "no exception, none",
30
+ BAD_CALL: "the call is wrong -- fix the arguments and ask again",
31
+ UNSETTLED: "the trace cannot settle it -- change the recording "
32
+ "and re-record",
33
+ }
@@ -0,0 +1,83 @@
1
+ """The invocation log: one JSON line per `cli.main` return.
2
+
3
+ `cli.main` calls `record` once per invocation, after dispatch, with the
4
+ argv it was given and the exit status (and, for the three exception
5
+ classes it catches, the exception's class name) it is about to return.
6
+ The log exists to answer "was sensorium called, and how did it end" --
7
+ the census a future on-demand flag would otherwise be arguing from thin
8
+ air (finding §4) -- not to reconstruct the process, so a line carries
9
+ exactly `utc`, `argv`, `exit`, `error`: never the environment, never the
10
+ working directory.
11
+
12
+ Default on. Opt out for one process by setting `SENSORIUM_NO_INVOCATION_LOG`
13
+ to any non-empty value other than `"0"` -- so `=1`, `=true`, `=yes` all
14
+ disable it, `=0` does not (logging stays on), and unset or empty is the
15
+ default (also on).
16
+
17
+ The log lives at `paths.trace_root() / "invocations.jsonl"`, a *sibling*
18
+ of `traces/` -- `runs` and `find_trace` only glob `traces/*.db`, so this
19
+ file is invisible to every trace lookup, by construction rather than by
20
+ filtering.
21
+
22
+ `record` never raises: a location it cannot write to (its directory
23
+ missing and uncreatable, e.g. a regular file sitting where a directory
24
+ belongs) prints one line to stderr and returns, exactly like a dropped
25
+ log line from any other best-effort logger -- a command's exit status is
26
+ never the invocation log's business.
27
+ """
28
+ import json
29
+ import os
30
+ import sys
31
+ from datetime import datetime, timezone
32
+ from pathlib import Path
33
+
34
+ from sensorium import paths
35
+
36
+ _DISABLE_VAR = "SENSORIUM_NO_INVOCATION_LOG"
37
+
38
+
39
+ def path() -> Path:
40
+ return paths.trace_root() / "invocations.jsonl"
41
+
42
+
43
+ def _utc_now() -> str:
44
+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f") + "Z"
45
+
46
+
47
+ def _log_disabled() -> bool:
48
+ """Any non-empty value other than `"0"` disables the log; `"0"` and
49
+ unset/empty both mean "keep logging" -- see the module docstring."""
50
+ value = os.environ.get(_DISABLE_VAR)
51
+ return bool(value) and value != "0"
52
+
53
+
54
+ def record(argv: list[str], exit_status: int, error: str | None) -> None:
55
+ """Append one JSON line to `path()`. Never raises."""
56
+ if _log_disabled():
57
+ return
58
+ line = {"utc": _utc_now(), "argv": list(argv), "exit": exit_status,
59
+ "error": error}
60
+ try:
61
+ p = path()
62
+ # 0700, like `paths.traces_dir` and `redact.Key.load_or_create`:
63
+ # this is the third hand that can create the store root, and the
64
+ # root is where `redaction.key` and this log live. An EXISTING
65
+ # directory keeps its own mode -- `exist_ok=True` ignores this one,
66
+ # which is the intent, and the parents created on the way get the
67
+ # default, exactly as `paths.traces_dir` documents.
68
+ p.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
69
+ # 0600 on creation, not afterwards: the log names every sensorium
70
+ # invocation and its argv, and `p.open("a")` would create it
71
+ # 0666-under-the-umask. The mode is ignored when the file is already
72
+ # there, which is the intent -- an existing log keeps whatever the
73
+ # user gave it.
74
+ fd = os.open(p, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
75
+ with os.fdopen(fd, "a", encoding="utf-8") as f:
76
+ f.write(json.dumps(line) + "\n")
77
+ except (OSError, RuntimeError) as e:
78
+ # OSError: the usual "can't write there" (missing/uncreatable
79
+ # directory, a file sitting where one belongs). RuntimeError:
80
+ # `path()` -> `paths.trace_root()` -> `Path.home()` raises this,
81
+ # not OSError, when no home directory can be determined and
82
+ # SENSORIUM_DIR is unset -- same best-effort drop, same one line.
83
+ print(f"sensorium: invocation log unwritable: {e}", file=sys.stderr)