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/mcp/tools.py ADDED
@@ -0,0 +1,299 @@
1
+ """The tool table: which commands are tools, and what a call becomes.
2
+
3
+ `schema` answers what a tool's fields are by reading its command's own
4
+ parser. This module answers the questions no parser can: which of the
5
+ CLI's commands a client is offered at all, which of those may execute,
6
+ what each tool is called, and what sentence it says about itself.
7
+
8
+ THE TABLES ARE EXPLICIT (P1). `QUERY_MODULES` names ten; `refocus` is
9
+ the one query that runs a program, so it appears only under
10
+ `--allow-run`; `redact` rewrites a stored trace, which is not a
11
+ question anyone asks a debugger, so it is in `NOT_TOOLS`. Deriving the
12
+ table from `cli._QUERY_MODULES` instead would have made `redact` a tool
13
+ the day it was written, and the NEXT command a tool the day IT is
14
+ written -- a silent default a surface with three executing tools cannot
15
+ afford. Field derivation stays automatic; only placement is by hand,
16
+ and `test_every_query_module_is_placed` fails until one is placed.
17
+
18
+ `record` IS THE CLI'S `run` (D2). As a tool name `run` reads as
19
+ "execute" in every client's prior and collides with the `run` FIELD
20
+ every query carries; `record` is the README's first verb. It is also
21
+ the one schema `derive` cannot build (D7): `run`'s target is an
22
+ argparse `REMAINDER` with no help, two of its flags are suppressed, and
23
+ two of its fields -- `cwd` and `python` -- are not argv at all but
24
+ instructions to whoever spawns the child. So `RECORD` is written out
25
+ here, with every sentence it can READ read off `_add_run_parser`: a
26
+ retyped help is right on the day it is typed and wrong the first time
27
+ the flag's own wording improves.
28
+
29
+ `command_argv` is the seam to the child runner: `(argv, extras)`, where
30
+ `extras` is empty for every tool but `record` and `record_c`. `record`
31
+ holds `cwd` and `python`; `record_c` holds `cwd`. Neither reaches argv.
32
+ """
33
+ from __future__ import annotations
34
+
35
+ import argparse
36
+ from dataclasses import dataclass
37
+
38
+ from sensorium import cli
39
+ from sensorium.mcp import schema
40
+ from sensorium.mcp.schema import Field, ToolSchema
41
+ from sensorium.query import (diff_cmd, exceptions_cmd, failures_cmd, flow_cmd,
42
+ frame_cmd, grep_cmd, info_cmd, redact_cmd,
43
+ refocus_cmd, runs_cmd, tree_cmd, watch_cmd)
44
+
45
+ #: The ten a client is always offered, in the order it is shown them.
46
+ QUERY_MODULES = (runs_cmd, info_cmd, tree_cmd, frame_cmd, grep_cmd,
47
+ exceptions_cmd, failures_cmd, flow_cmd, watch_cmd, diff_cmd)
48
+
49
+ #: ...and the one query that re-runs the recorded command: offered only
50
+ #: under `--allow-run`.
51
+ EXECUTE_MODULES = (refocus_cmd,)
52
+
53
+ #: A command, deliberately not a tool: `redact` rewrites a stored trace.
54
+ NOT_TOOLS = (redact_cmd,)
55
+
56
+ #: The fields a capped answer suggests narrowing by, in the order the
57
+ #: trailer lists them (P28: `depth` before `limit`, so `tree` reads
58
+ #: "narrow with: depth, limit, around").
59
+ NARROWING = ("depth", "limit", "after", "around", "context", "misses", "fn",
60
+ "kind")
61
+
62
+ #: D9. Ten tools read a file that is already written...
63
+ ANNOTATIONS_QUERY = {"readOnlyHint": True, "destructiveHint": False,
64
+ "idempotentHint": True, "openWorldHint": False}
65
+
66
+ #: ...and three run a program that may do anything.
67
+ ANNOTATIONS_EXECUTE = {"readOnlyHint": False, "destructiveHint": False,
68
+ "idempotentHint": False, "openWorldHint": True}
69
+
70
+ #: The three sentences `_add_run_parser` cannot supply: `target` is a
71
+ #: `REMAINDER` with no help, and the other two are the child's process.
72
+ _COMMAND_HELP = ("the program to record, as its own argv: a .py file, `-m` "
73
+ "and a module, or a console script, followed by its "
74
+ "arguments; never `python`")
75
+ _CWD_HELP = ("directory to record from; only code under it is recorded; "
76
+ "default the server's")
77
+ _PYTHON_HELP = ("interpreter to record under; must import sensorium and the "
78
+ "program's dependencies; default the server's own")
79
+
80
+
81
+ def _record_schema() -> ToolSchema:
82
+ """`record`'s schema, read off `sensorium run`'s parser (D7).
83
+
84
+ Built the way `derive` builds one -- a private subparsers object --
85
+ so the read does not depend on a live CLI, and REFUSED the way
86
+ `derive` refuses. A hand-written table must not be the one that can
87
+ ship a field saying nothing: a `help=` deleted from
88
+ `_add_run_parser` would otherwise reach a client as `"description":
89
+ null`, and the three sentences below would be all `record` said.
90
+ """
91
+ parser = argparse.ArgumentParser(prog="sensorium", exit_on_error=False)
92
+ sub = parser.add_subparsers(dest="cmd")
93
+ cli._add_run_parser(sub)
94
+ p = sub.choices["run"]
95
+ said = {a.dest: a.help for a in p._actions}
96
+ flag = {a.dest: a.option_strings[0] for a in p._actions
97
+ if a.option_strings}
98
+ spec = (("focus", "array"), ("include", "array"),
99
+ ("exclude", "array"), ("window", "string"),
100
+ ("max_events", "string"), ("max_bytes", "string"),
101
+ ("max_calls", "string"), ("no_cap", "boolean"),
102
+ ("no_children", "boolean"))
103
+ if not p.description:
104
+ raise schema.SchemaError("run: the command has no description; "
105
+ "the server refuses to boot")
106
+ for name, _ in spec:
107
+ if not said.get(name):
108
+ raise schema.SchemaError(f"run: field {name!r} has no help; "
109
+ "the server refuses to boot")
110
+ flags = [Field(name=name, kind=kind, required=False,
111
+ description=said[name], option=flag[name])
112
+ for name, kind in spec]
113
+ fields = (
114
+ Field(name="command", kind="array", required=True,
115
+ description=_COMMAND_HELP, positional=True),
116
+ *flags,
117
+ # The two with no `option`: `command_argv` hands them to the
118
+ # child runner and never to argv.
119
+ Field(name="cwd", kind="string", required=False,
120
+ description=_CWD_HELP),
121
+ Field(name="python", kind="string", required=False,
122
+ description=_PYTHON_HELP),
123
+ )
124
+ # `_command_help` rather than a second copy of the same four lines:
125
+ # a `run` whose help went missing must refuse to boot in the words
126
+ # every other command's would.
127
+ return ToolSchema("run", fields, schema._command_help(sub, "run"),
128
+ p.description, p)
129
+
130
+
131
+ #: The CLI's `run`, as the tool `record`.
132
+ RECORD = _record_schema()
133
+
134
+ _RECORD_C_HELP = "record a C build or program"
135
+ _RECORD_C_DESCRIPTION = (
136
+ "Runs the command under the C recorder and writes one trace; "
137
+ "`command` is the build or program argv, for example `make test` "
138
+ "or `./a.out`, and `strict` refuses optimized translation units.")
139
+ _C_COMMAND_HELP = ("the build or program argv, for example make test "
140
+ "or ./a.out")
141
+ _C_CWD_HELP = "the directory to run in"
142
+ _C_STRICT_HELP = "refuse optimized translation units"
143
+
144
+
145
+ def _record_c_schema() -> ToolSchema:
146
+ """`record_c`, written out rather than read off a parser.
147
+
148
+ `c run`'s parser belongs to the recorder. The argv this tool builds
149
+ is `["c", "run", ...]` by hand, the same way `record` cannot be
150
+ `to_argv`'s, so the schema does not have to be derived to stay true.
151
+ """
152
+ fields = (
153
+ Field(name="command", kind="array", required=True, positional=True,
154
+ description=_C_COMMAND_HELP),
155
+ Field(name="cwd", kind="string", required=False,
156
+ description=_C_CWD_HELP),
157
+ Field(name="strict", kind="boolean", required=False,
158
+ description=_C_STRICT_HELP, option="--strict"),
159
+ )
160
+ # Present because `ToolSchema` requires one. `command_argv` does not
161
+ # parse with it.
162
+ parser = argparse.ArgumentParser(prog="sensorium record_c",
163
+ exit_on_error=False)
164
+ return ToolSchema("record_c", fields, _RECORD_C_HELP,
165
+ _RECORD_C_DESCRIPTION, parser)
166
+
167
+
168
+ #: A C build or program, as the tool `record_c`.
169
+ RECORD_C = _record_c_schema()
170
+
171
+
172
+ @dataclass(frozen=True)
173
+ class Tool:
174
+ """One entry of the table: what a client is offered, and whether
175
+ answering it starts a program."""
176
+
177
+ name: str
178
+ schema: ToolSchema
179
+ executes: bool
180
+
181
+ @property
182
+ def description(self) -> str:
183
+ """D3: the parser's `help=`, a full stop, and its `description=`
184
+ -- the same two strings `sensorium <cmd> --help` prints."""
185
+ return f"{self.schema.help}. {self.schema.description}"
186
+
187
+ @property
188
+ def annotations(self) -> dict:
189
+ return dict(ANNOTATIONS_EXECUTE if self.executes
190
+ else ANNOTATIONS_QUERY)
191
+
192
+
193
+ def table(allow_run: bool) -> dict[str, Tool]:
194
+ """The tools this server offers, in the order it lists them.
195
+
196
+ `schema.SchemaError` propagates: a command whose field lost its help
197
+ is a boot refusal, not a tool with a blank in it."""
198
+ tools = {}
199
+ for module in QUERY_MODULES:
200
+ ts = schema.derive(module)
201
+ tools[ts.command] = Tool(ts.command, ts, executes=False)
202
+ if allow_run:
203
+ for module in EXECUTE_MODULES:
204
+ ts = schema.derive(module)
205
+ tools[ts.command] = Tool(ts.command, ts, executes=True)
206
+ tools["record"] = Tool("record", RECORD, executes=True)
207
+ tools["record_c"] = Tool("record_c", RECORD_C, executes=True)
208
+ return tools
209
+
210
+
211
+ def to_wire(tool: Tool, structured: bool) -> dict:
212
+ """The `tools/list` entry for one tool.
213
+
214
+ `title` arrived in 2025-06-18, so a 2025-03-26 client is not sent
215
+ one: an unknown key is a validation failure in some clients and
216
+ noise in the rest. NO revision gets an `outputSchema` (R18):
217
+ declaring one asks for the structured content the deploy target
218
+ shows a model INSTEAD of the answer. The exit is the header line."""
219
+ wire = {"name": tool.name,
220
+ "description": tool.description,
221
+ "inputSchema": schema.json_schema(tool.schema),
222
+ "annotations": tool.annotations}
223
+ if structured:
224
+ wire["title"] = tool.name
225
+ return wire
226
+
227
+
228
+ def narrowing_fields(tool: Tool) -> tuple[str, ...]:
229
+ """The fields a capped answer tells the caller to narrow by: this
230
+ tool's, in `NARROWING`'s order rather than the parser's."""
231
+ names = {f.name for f in tool.schema.fields}
232
+ return tuple(name for name in NARROWING if name in names)
233
+
234
+
235
+ def _refocus_compact_argv(argv: list[str], arguments: dict) -> list[str]:
236
+ """`--compact` unless the call passed false.
237
+
238
+ The CLI flag defaults off, and `schema.to_argv` therefore emits it
239
+ only when the caller passed true. A model that omits `compact` is
240
+ asking for the short report: the schema's default is true, and the
241
+ long report is `compact: false`. Applying that default inside
242
+ `to_argv` would rebuild every corpus refocus question with a flag
243
+ it never typed, so the default is applied here, at the server's
244
+ argv seam, and nowhere else.
245
+ """
246
+ if arguments.get("compact") is False:
247
+ return [word for word in argv if word != "--compact"]
248
+ if "--compact" in argv:
249
+ return argv
250
+ if "--" in argv:
251
+ at = argv.index("--")
252
+ return [*argv[:at], "--compact", *argv[at:]]
253
+ return [*argv, "--compact"]
254
+
255
+
256
+ def command_argv(tool: Tool, arguments: dict) -> tuple[list[str], dict]:
257
+ """`(argv, extras)` for a call: the child's command line, and what
258
+ the runner must be told that no command line can carry.
259
+
260
+ `record` is the one tool `to_argv` cannot build for. Its target is
261
+ the argv AFTER a `--` -- which is what keeps a target's own `-m` or
262
+ `--include` the target's -- and `cwd`/`python` are the child's
263
+ process, not its arguments. `record_c` is the other: its argv is
264
+ `c run`, with `--strict` before the `--` and `cwd` kept out of argv.
265
+ Both are refused by `schema.validate` first, so an unknown or
266
+ missing field is named here in the words every other tool uses.
267
+ """
268
+ if tool.schema is RECORD_C:
269
+ schema.validate(RECORD_C, arguments)
270
+ argv = ["c", "run"]
271
+ if arguments.get("strict"):
272
+ argv.append("--strict")
273
+ argv.extend(["--", *arguments["command"]])
274
+ return argv, {"cwd": arguments.get("cwd") or None}
275
+ if tool.schema is not RECORD:
276
+ argv = schema.to_argv(tool.schema, arguments)
277
+ if tool.name == "refocus":
278
+ argv = _refocus_compact_argv(argv, arguments)
279
+ return argv, {}
280
+ schema.validate(RECORD, arguments)
281
+ argv = ["run"]
282
+ for f in RECORD.fields:
283
+ if f.option is None or f.name not in arguments:
284
+ continue
285
+ value = arguments[f.name]
286
+ # `--name=value`, as `schema.to_argv` emits (I2): a `--focus`
287
+ # whose value began with `-` was read as the next flag, and the
288
+ # `--` below cannot help -- it separates the TARGET's argv and
289
+ # everything here is before it. A boolean is a bare flag.
290
+ if f.kind == "boolean":
291
+ if value:
292
+ argv.append(f.option)
293
+ elif f.kind == "array":
294
+ argv.extend(f"{f.option}={item}" for item in value)
295
+ else:
296
+ argv.append(f"{f.option}={value}")
297
+ argv.extend(["--", *arguments["command"]])
298
+ return argv, {"cwd": arguments.get("cwd"),
299
+ "python": arguments.get("python")}
sensorium/paths.py ADDED
@@ -0,0 +1,80 @@
1
+ """Trace directory location, run ids, and run-reference resolution."""
2
+ import os
3
+ import time
4
+ import uuid
5
+ from pathlib import Path
6
+
7
+
8
+ class TraceLookupError(Exception):
9
+ pass
10
+
11
+
12
+ class NoSuchTrace(TraceLookupError):
13
+ """No trace in the store has this ref as a prefix.
14
+
15
+ A TYPE and not a sentence. `exceptions_cmd` falls through to the
16
+ invocation namespace on exactly this failure and on no other (design
17
+ N6), and it tested the words `"no trace matches"` to tell them apart --
18
+ correct while nobody reworded the message, and silently wrong the day
19
+ somebody did, because the fall-through would stop happening and the
20
+ only symptom would be a command answering less.
21
+
22
+ A subclass, so `cli.main` and every other caller that catches
23
+ `TraceLookupError` are unchanged.
24
+ """
25
+
26
+
27
+ def trace_root() -> Path:
28
+ return Path(os.environ.get("SENSORIUM_DIR") or Path.home() / ".sensorium")
29
+
30
+
31
+ def traces_dir() -> Path:
32
+ """`<trace root>/traces`, created 0700 the whole way down.
33
+
34
+ The two `mkdir` calls are one rule, not a tidy-up: `Path.mkdir` applies
35
+ `mode` to the directory it names and gives every PARENT it creates on
36
+ the way the default, so a single `traces.mkdir(parents=True,
37
+ mode=0o700)` would leave the store root itself world-readable -- and
38
+ the root is where `redaction.key` and `invocations.jsonl` live. An
39
+ existing directory is never chmod'ed: the user's own permissions on
40
+ their own store are theirs.
41
+ """
42
+ root = trace_root()
43
+ root.mkdir(parents=True, exist_ok=True, mode=0o700)
44
+ d = root / "traces"
45
+ d.mkdir(exist_ok=True, mode=0o700)
46
+ return d
47
+
48
+
49
+ def new_run_id() -> str:
50
+ return time.strftime("%Y%m%d-%H%M%S") + "-" + uuid.uuid4().hex[:6]
51
+
52
+
53
+ def is_valid_run_id(run_id: str) -> bool:
54
+ """Whether `run_id` names ONE file inside the trace store, and cannot
55
+ escape it.
56
+
57
+ A run id flows straight into `traces_dir() / f"{run_id}.db"`, whose parent
58
+ is created with `parents=True`, so a caller-supplied `--run-id` of `../x`,
59
+ `a/b` or `/tmp/x` would create directories and write a trace outside the
60
+ store. Ids the tool mints itself (`new_run_id`) always pass; this guards the
61
+ one place an id comes from outside. A valid id is a single path component:
62
+ non-empty, not `.`/`..`, and equal to its own basename (no separators).
63
+ """
64
+ return (isinstance(run_id, str) and run_id not in ("", ".", "..")
65
+ and run_id == Path(run_id).name)
66
+
67
+
68
+ def find_trace(ref: str) -> Path:
69
+ files = sorted(traces_dir().glob("*.db"))
70
+ if not files:
71
+ raise TraceLookupError("no traces recorded yet")
72
+ if ref == "last":
73
+ return max(files, key=lambda p: p.stat().st_mtime)
74
+ hits = [p for p in files if p.stem.startswith(ref)]
75
+ if not hits:
76
+ raise NoSuchTrace(f"no trace matches {ref!r}")
77
+ if len(hits) > 1:
78
+ names = ", ".join(p.stem for p in hits)
79
+ raise TraceLookupError(f"{ref!r} is ambiguous: {names}")
80
+ return hits[0]
File without changes
@@ -0,0 +1,150 @@
1
+ """What a trace says about its own coverage, read one way by every command.
2
+
3
+ Two declarations live here, because both answer the same question -- may an
4
+ absence in this trace be reported as a fact about the program? -- and both
5
+ must be read identically everywhere, or the same trace answers 1 in one
6
+ command and 3 in another.
7
+
8
+ Capability declarations (spec §5.2): a format-4 trace says what its recorder
9
+ produces. Before format 4 nothing was declared and only the Python recorder
10
+ existed, so an absent key meant "older": the sentence for it says
11
+ "predates". On a format-4 trace an absent record is a declaration, and the
12
+ sentence says so -- never "older", never a zero.
13
+
14
+ The `incomplete` flag: a recording that never reached its finalize pass
15
+ stopped mid-flight, so what it does not hold may simply be what it never got
16
+ to write. `none_status` is that fact applied to the emptiest answer a
17
+ listing command has, and `print_incomplete` is the banner that explains the
18
+ status it returns.
19
+ """
20
+ from sensorium.exit import NEGATIVE, UNSETTLED
21
+
22
+
23
+ def witness_gap(trace, cap: str, keys: str, legacy: str) -> str:
24
+ """Why a record is absent, in the words the trace itself supports.
25
+
26
+ Three states of `trace.declares(cap)`, three different facts:
27
+
28
+ - None: this trace predates the declaration outright -- no
29
+ `capabilities` key, and it is the Python recorder's (the only one
30
+ that existed before format 4). `legacy` is the calling site's own
31
+ pre-format-4 sentence, passed in whole and returned unchanged: every
32
+ trace in this state must read exactly as it did before this module
33
+ existed.
34
+ - False: the recorder declared it does not produce `cap`. The absence
35
+ is what the recorder SAID, not an accident of age.
36
+ - True: the recorder declared it DOES produce `cap`, and the witness
37
+ key is still missing. Not a corner nobody reaches: today's Python
38
+ recorder writes `recorder`/`lang`/`capabilities` (all True) at
39
+ `install()` time, at the START of a run, and writes `threads_started`
40
+ only at the finalize pass (`set_meta_final`) -- so every recording
41
+ still in flight, or that died before finalizing, is in this state,
42
+ and a fixture that deletes a witness key from an otherwise-finalized
43
+ trace lands here too. The honest sentence names the contradiction; it
44
+ must never assert `capabilities.<cap>: false` about a trace whose own
45
+ dict says true.
46
+ """
47
+ declared = trace.declares(cap)
48
+ if declared is None:
49
+ return legacy
50
+ if declared is False:
51
+ return (f"recorder {trace.recorder} declares {cap} not witnessed "
52
+ f"(capabilities.{cap}: false), so there is no {keys} record "
53
+ "to read; absence of the record is not a record of absence")
54
+ return (f"recorder {trace.recorder} declares {cap} witnessed, but this "
55
+ f"trace carries no {keys} record -- the recording did not "
56
+ "finish, or the record was removed; absence of the record is "
57
+ "not a record of absence")
58
+
59
+
60
+ def require(trace, cap: str, command: str) -> str | None:
61
+ """A refusal sentence when `trace` does not produce `cap`, else None.
62
+ The instrument never answers from data it does not have: this is that
63
+ rule applied to a whole command instead of one value."""
64
+ declared = trace.declares(cap)
65
+ if declared is None or declared:
66
+ return None
67
+ return (f"{command} needs {cap}, which recorder {trace.recorder} "
68
+ f"declares it does not produce (capabilities.{cap}: false); "
69
+ "nothing was checked")
70
+
71
+
72
+ def none_status(trace) -> int:
73
+ """The status of an EMPTY answer: "none", or "I never finished looking"?
74
+
75
+ `matches: 0`, `no frames recorded` and `sightings: 0` are the trace
76
+ answering "no" only when the recording is whole. A run whose meta says
77
+ `incomplete` stopped mid-flight and the events after the cut were never
78
+ written, so an empty result there reports where the RECORDING ended, not
79
+ what the program did -- and the fix is to record again, which is what 3
80
+ means. Absence of the record is not a record of absence, applied to the
81
+ emptiest answer each listing command has.
82
+
83
+ One predicate for all of them (the general table row added 2026-09-04),
84
+ so they cannot drift: a status decided command by command is a status
85
+ that reads 1 in `grep` and 3 in `flow` about one trace.
86
+
87
+ `exceptions` on a PYTHON trace is deliberately not a caller. Its empty
88
+ answer already splits three ways on facts this predicate cannot see
89
+ (`no RAISE events recorded (see INCOMPLETE above)` is 3, `no exceptions
90
+ recorded` is 1), and it reads the flag itself to do that. The RUST arm
91
+ (`query/exceptions_rust`, rung 3) IS a caller: it has one empty answer
92
+ and no uncaught record to split it on, so it takes the shared rule.
93
+ """
94
+ if trace.meta.get("incomplete") or trace.meta.get("trace_truncated"):
95
+ # A cap that dropped calls leaves the same kind of gap: an empty
96
+ # answer is where the recording stopped storing, not a fact about
97
+ # the program. A non-empty answer keeps its own status; the banner
98
+ # is what says the trace is partial.
99
+ return UNSETTLED
100
+ return NEGATIVE
101
+
102
+
103
+ def print_truncated(trace) -> None:
104
+ """One line when a cap dropped calls. No-op on a whole trace."""
105
+ if not trace.meta.get("trace_truncated"):
106
+ return
107
+ limits = trace.meta.get("trace_limits") or {}
108
+ hit = limits.get("hit") or []
109
+ which = ", ".join(str(item) for item in hit) if hit else "a cap"
110
+ n = limits.get("calls_elided", 0)
111
+ print(f"TRUNCATED: recording hit its cap ({which}); elided {n} calls. "
112
+ "What was kept is the call-tree skeleton and the frames around "
113
+ "failures.")
114
+
115
+
116
+ def print_elisions(trace, limit: int = 8) -> None:
117
+ """Per-function elision lines, capped so a hot store stays one screen."""
118
+ rows = list(trace.meta.get("elisions") or [])
119
+ if not rows:
120
+ return
121
+ for row in rows[:limit]:
122
+ print(f" elided {row.get('elided', 0)} calls of "
123
+ f"{row.get('qualname')}")
124
+ extra = len(rows) - limit
125
+ if extra > 0:
126
+ print(f" and {extra} more")
127
+
128
+
129
+ def print_incomplete(trace, consequence: str) -> None:
130
+ """The INCOMPLETE banner, in the one wording every command shares.
131
+
132
+ Any command that can answer "none" prints this: `none_status` turns an
133
+ empty answer on an unfinalized trace into a 3, and a 3 whose output
134
+ says nothing about why is a number the reader cannot act on. It is
135
+ printed BEFORE the rows for the same reason `watch` prints its
136
+ NEVER RECORDED banner above the verdict -- what follows cannot be read
137
+ without it.
138
+
139
+ `consequence` is the one clause that differs per command: what
140
+ specifically is missing from THIS command's output. The first line is
141
+ shared, so a trace that stopped mid-run says so in the same words
142
+ wherever the reader meets it. A truncated trace prints its own banner
143
+ first, including when the recording did finalize.
144
+ """
145
+ print_truncated(trace)
146
+ if not trace.meta.get("incomplete"):
147
+ return
148
+ print("INCOMPLETE: this recording never finalized, so it may stop "
149
+ "mid-run")
150
+ print(" " + consequence)
@@ -0,0 +1,64 @@
1
+ """Which language's formatter wrote a `dbg` capture, and the pair that
2
+ reads and writes it.
3
+
4
+ A `dbg` capture is TEXT, and the text alone cannot say what it spells:
5
+ `'rate'` is the string rate to `util.inspect` and a five-character word to
6
+ Rust's `Debug`, and `5` is an integer in one and could be either in the
7
+ other. Two commands read that text -- `watch --expr` through
8
+ `expr.resolve`, `flow --value` through `flow_values.matches` -- and both
9
+ must ask the TRACE which dialect wrote it, never the text and never a
10
+ `lang` branch of their own (the discipline design 2026-09-06 section 4.1
11
+ set for the first two recorders and this rung keeps for the third).
12
+
13
+ So the word lives in the vocabulary table, beside every other sentence
14
+ keyed on `meta["lang"]`, and this module is the one place it becomes a
15
+ pair of functions. A recorder whose captures are TYPED rather than
16
+ rendered -- Python's -- names no dialect at all: no Python trace carries a
17
+ `dbg` capture, so the pair such a trace would hand out is never used.
18
+ `RUST` is the default for a caller that passes none, which keeps every
19
+ call written before the second dialect existed reading exactly as it did
20
+ (plan P10).
21
+
22
+ The `c` dialect is neither of those two. C struct text is `dbg`, and a
23
+ literal inside it must not be parsed as Rust `Debug` or as `util.inspect`.
24
+ `read` returns the text unchanged and `write` returns a string unchanged,
25
+ so `flow --value` matches that rendered text and nothing else.
26
+ """
27
+ from collections import namedtuple
28
+
29
+ from sensorium.query.js_inspect import inspect_text, read_inspect
30
+ from sensorium.query.rust_debug import debug_text, read_debug
31
+ from sensorium.query.vocab import terms
32
+
33
+ #: `read(text) -> value` and `write(literal) -> text | None`, inverses over
34
+ #: the literal domain a command accepts (amendment A11). They travel
35
+ #: together because a reader and a writer that disagree about one capture
36
+ #: let `flow` report a sighting the predicate at that site then denies.
37
+ Dialect = namedtuple("Dialect", "read write")
38
+
39
+ def _read_c(text):
40
+ """C struct text, unchanged. Not parsed."""
41
+ return text
42
+
43
+
44
+ def _write_c(value):
45
+ """The string itself. Anything else is not C struct text."""
46
+ return value if isinstance(value, str) else None
47
+
48
+
49
+ RUST = Dialect(read_debug, debug_text)
50
+ INSPECT = Dialect(read_inspect, inspect_text)
51
+ C = Dialect(_read_c, _write_c)
52
+ BY_NAME = {"rust": RUST, "inspect": INSPECT, "c": C}
53
+
54
+
55
+ def for_trace(trace) -> Dialect:
56
+ """The dialect this trace's captures were written in.
57
+
58
+ A trace whose vocabulary names none is one whose recorder writes no
59
+ `dbg` capture at all, and Rust's pair is what every caller got before
60
+ this module existed: handing it back keeps a Python trace's answers
61
+ byte-identical while never actually being consulted.
62
+ """
63
+ name = terms(trace).dbg_dialect
64
+ return BY_NAME[name] if name else RUST