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.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- 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
|
sensorium/query/caps.py
ADDED
|
@@ -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
|