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/ts/cli.py ADDED
@@ -0,0 +1,130 @@
1
+ """`sensorium ts` -- the TypeScript recorder's own subcommands.
2
+
3
+ Two subcommands. `run` records a test run: it recognises the harness, wires
4
+ it, spawns the command as typed, waits, and converts what the run spooled.
5
+ `ingest` is the second half of that on its own, over a spool directory a run
6
+ already left behind -- deterministic and re-runnable, so a driver killed
7
+ between the harness's exit and the conversion leaves nothing that cannot be
8
+ finished by hand.
9
+
10
+ Every word printed by this file is about test files, containers and the
11
+ harness that ran them. Nothing here borrows a word from another recorder's
12
+ machinery: a reader who meets `asyncio` or `cargo` in a TypeScript command's
13
+ help has been told about something that is not there.
14
+ """
15
+ import argparse
16
+ import sys
17
+
18
+ from sensorium import exit as ex
19
+ from sensorium import paths
20
+ from sensorium.ts import ingest, invocation
21
+
22
+
23
+ def add_parser(sub) -> None:
24
+ p = sub.add_parser("ts", help="record and read a TypeScript test run",
25
+ description="Record a TypeScript or JavaScript test "
26
+ "run under vitest or node --test; read "
27
+ "back what actually ran.")
28
+ ts = p.add_subparsers(dest="ts_cmd", required=True)
29
+ _add_run_parser(ts)
30
+ _add_ingest_parser(ts)
31
+
32
+
33
+ def _add_run_parser(sub) -> None:
34
+ p = sub.add_parser(
35
+ "run", help="record a test run under vitest or node --test",
36
+ description="Record one test run. Give the harness command after "
37
+ "`--`, exactly as you would type it; the recorder wires "
38
+ "itself in and takes the wiring out again when the run "
39
+ "ends.",
40
+ epilog="exit: the harness's own status, or 2 to fix the call")
41
+ p.add_argument("--tier", choices=("off", "call"), default="call",
42
+ help="what the recorder emits: `call` records calls, "
43
+ "returns and awaits; `off` records nothing (the "
44
+ "control arm -- the same code still runs)")
45
+ p.add_argument("--focus", action="append", default=[], metavar="SPEC",
46
+ help="a function to record per statement: <qualname> or "
47
+ "<file>:<qualname>, as tree prints it; repeatable")
48
+ p.add_argument("--jobs", type=int, default=None, metavar="N",
49
+ help="how many spools to convert at once (default: one "
50
+ "per core)")
51
+ p.add_argument("--refocus-of", default=None, metavar="RUN",
52
+ help="the run this recording re-runs one flag deeper; "
53
+ "stamps refocus_of into every trace of the "
54
+ "invocation (set by `sensorium refocus`)")
55
+ p.add_argument("--max-events", default=None,
56
+ help="stop storing events after this many (0 is unlimited)")
57
+ p.add_argument("--max-bytes", default=None,
58
+ help="stop storing events after the trace reaches this "
59
+ "size, for example 8M (0 is unlimited)")
60
+ p.add_argument("--max-calls", default=None,
61
+ help="store at most this many calls of each function; "
62
+ "later calls are counted and marked elided "
63
+ "(0 is unlimited)")
64
+ p.add_argument("--no-cap", action="store_true",
65
+ help="record without an event, size, or per-function cap")
66
+ p.add_argument("command", nargs=argparse.REMAINDER,
67
+ help="-- followed by the harness command: vitest run …, "
68
+ "npx vitest run …, node --test …")
69
+ p.set_defaults(func=run_run)
70
+
71
+
72
+ def run_run(args) -> int:
73
+ if args.jobs is not None and args.jobs < 1:
74
+ print(f"--jobs must be >= 1 (got {args.jobs})", file=sys.stderr)
75
+ return ex.BAD_CALL
76
+ # Imported here and not above: the driver imports this module back for
77
+ # its own reporting, and one of the two has to be the late one.
78
+ from sensorium.ts import driver
79
+ return driver.run(args)
80
+
81
+
82
+ def _add_ingest_parser(sub) -> None:
83
+ p = sub.add_parser(
84
+ "ingest", help="turn a recorded spool directory into traces",
85
+ description="Convert every spool a recorded run left behind -- one "
86
+ "per container -- into one trace each.",
87
+ epilog="exit: 0 every spool converted, 2 fix the call or the "
88
+ "directory")
89
+ p.add_argument("spool_dir",
90
+ help="the directory the run wrote its spools into")
91
+ p.add_argument("--jobs", type=int, default=None, metavar="N",
92
+ help="how many spools to convert at once (default: one "
93
+ "per core)")
94
+ p.set_defaults(func=run_ingest)
95
+
96
+
97
+ def run_ingest(args) -> int:
98
+ if args.jobs is not None and args.jobs < 1:
99
+ print(f"--jobs must be >= 1 (got {args.jobs})", file=sys.stderr)
100
+ return ex.BAD_CALL
101
+ try:
102
+ summaries = ingest.ingest_dir(args.spool_dir, paths.trace_root(),
103
+ jobs=args.jobs)
104
+ # Read back rather than passed down: `ingest_dir` returns what
105
+ # happened to the SPOOLS, and the invocation is a property of the
106
+ # directory, not of any of them.
107
+ invocation_id = invocation.read_invocation(args.spool_dir).invocation
108
+ except (ingest.IngestError, invocation.InvocationError) as e:
109
+ print(f"error: {e}", file=sys.stderr)
110
+ return ex.BAD_CALL
111
+ return _report(summaries, invocation_id)
112
+
113
+
114
+ def _report(summaries, invocation_id: str, harness: str | None = None) -> int:
115
+ """One line per spool, then the invocation and what it converted to.
116
+
117
+ A refused spool takes the place of its own `run:` line rather than being
118
+ collected at the end, so the order on screen is the order on disk and a
119
+ reader can see which container is missing from the count.
120
+
121
+ `harness` is the ending the driver WITNESSED, and only a driver has one:
122
+ an ingest of a directory read the same fact out of a file, which is a
123
+ different claim, and the line does not make it.
124
+ """
125
+ for summary in summaries:
126
+ print(summary.line())
127
+ converted = [s for s in summaries if s.refused is None]
128
+ tail = "" if harness is None else f" harness exit: {harness}"
129
+ print(f"invocation: {invocation_id} traces: {len(converted)}{tail}")
130
+ return ex.ANSWERED if len(converted) == len(summaries) else ex.BAD_CALL
sensorium/ts/driver.py ADDED
@@ -0,0 +1,472 @@
1
+ """`sensorium ts run`: recognise, wire, spawn, wait, convert.
2
+
3
+ The order is the design, and every step of it is there because the step
4
+ before it can fail in a way that would otherwise leave something behind:
5
+
6
+ --refocus-of refused before the Node check: it is about the
7
+ call and nothing else, so a bad link costs no
8
+ version probe and no spawn
9
+ node --version refused below 24 (D2) before anything is minted
10
+ the package refused uninstalled before anything is minted
11
+ recognise refused before a spool directory exists
12
+ the root's typescript refused once the plan names the root, and still
13
+ before anything is minted
14
+ --focus resolved against the root by the recorder's own
15
+ resolver, and refused there
16
+ the caps resolved before anything is minted: a bad size is
17
+ a bad call, and the harness then sees only integers
18
+ mint, invocation.json the record of what is about to be spawned
19
+ the wrapper two files, in a `finally` from here on
20
+ spawn, wait the harness's stdio is the user's; the driver
21
+ only holds the clock
22
+ harness.json written whether the harness passed or failed --
23
+ the run an agent most wants to read is the red one
24
+ remove the wrapper on every path, exception included
25
+ ingest one trace per container, into the same store
26
+
27
+ The driver never applies the query CLI's 0/1/2/3 table to itself: it exits
28
+ with the harness's own status, and `128 + n` when a signal ended it. A
29
+ recorder whose exit status meant something different from the command it
30
+ wrapped could not be put in front of an existing command line at all.
31
+ """
32
+ import importlib.metadata
33
+ import json
34
+ import os
35
+ import re
36
+ import signal
37
+ import subprocess
38
+ import sys
39
+ import time
40
+ from collections.abc import Sequence
41
+ from pathlib import Path
42
+
43
+ from sensorium import exit as ex
44
+ from sensorium import paths, redact
45
+ from sensorium.ts import focus as focus_mod
46
+ from sensorium.ts import harness as harness_mod
47
+ from sensorium.ts import ingest, invocation, pkg as pkg_mod, wrapper
48
+
49
+ #: Where a run's spools live, under the trace store. One directory per
50
+ #: invocation, named by it, holding the record, the spools and the marker.
51
+ SPOOL_DIR = "spool"
52
+
53
+
54
+ class LinkError(Exception):
55
+ """`--refocus-of` named something this store cannot link to. A refusal
56
+ like every other bad call, and the FIRST of them: the value is about
57
+ the call and nothing else, so it is settled before the Node version,
58
+ the package and `recognise` -- none of which could make a bad link
59
+ good, and all of which cost something to ask."""
60
+
61
+
62
+ class SpawnError(Exception):
63
+ """The harness binary could not be started at all. `recognise` reads a
64
+ command and does not check that the program exists -- which `vitest`
65
+ runs is the user's choice, and resolving it there would resolve a
66
+ different one -- so this is where a name that is not a program is
67
+ found, and it is a refusal like every other bad call."""
68
+
69
+
70
+ def run(args) -> int:
71
+ """The `ts run` verb. See the module docstring for the order."""
72
+ command = list(getattr(args, "command", []))
73
+ if command and command[0] == "--":
74
+ command = command[1:]
75
+ try:
76
+ link = _refocus_link(getattr(args, "refocus_of", None))
77
+ except LinkError as e:
78
+ return _refuse(str(e))
79
+ try:
80
+ node = pkg_mod.check_node()
81
+ package = pkg_mod.locate()
82
+ pkg_mod.check(package)
83
+ except pkg_mod.PackageError as e:
84
+ return _refuse(str(e))
85
+ cwd = Path.cwd()
86
+ plan = harness_mod.recognise(command, cwd)
87
+ if isinstance(plan, harness_mod.Refusal):
88
+ return _refuse(plan.message)
89
+ # After `recognise`, because only the plan knows the root -- and still
90
+ # before anything is minted.
91
+ try:
92
+ pkg_mod.check_root(plan.root)
93
+ except pkg_mod.PackageError as e:
94
+ return _refuse(str(e))
95
+ # And after THAT, because resolving a focus parses the root's files with
96
+ # the root's own TypeScript. Still nothing minted: a focus that selects
97
+ # nothing is a call to fix, and a half-recorded run of it would be a
98
+ # recording of a question nobody asked (spec section 2.2).
99
+ focus = list(args.focus or [])
100
+ resolution = None
101
+ if any(spec.strip() == "" for spec in focus):
102
+ # An empty spec has an empty qualname, and an empty qualname is a
103
+ # prefix of every name there is: dropped it does nothing, honoured
104
+ # it records the whole program. Neither is what was typed.
105
+ return _refuse("--focus was given nothing to name: a spec is a "
106
+ "<qualname> or a <file>:<qualname>")
107
+ if focus:
108
+ try:
109
+ # `node` here is the VERSION `check_node` read, not a program:
110
+ # the resolver runs the same `node` on PATH the harness will.
111
+ resolution = focus_mod.resolve(plan.root, package, focus)
112
+ except pkg_mod.PackageError as e:
113
+ return _refuse(str(e))
114
+ bad = focus_mod.refusals(resolution, plan.root)
115
+ if bad:
116
+ return _refuse(*bad)
117
+ from sensorium.limits import LimitsError
118
+ try:
119
+ _caps(args)
120
+ except LimitsError as e:
121
+ return _refuse(str(e))
122
+ try:
123
+ return _record(plan, package, node, cwd, args, focus, resolution,
124
+ link)
125
+ except (wrapper.WrapperError, SpawnError) as e:
126
+ return _refuse(str(e))
127
+
128
+
129
+ def _refuse(*messages: str) -> int:
130
+ """One line on stderr per refusal, exit 2, nothing left behind. Every
131
+ refusal this driver makes before the harness is spawned goes through
132
+ here, so they are one shape and not six -- and a call with two mistakes
133
+ in it is told both, rather than sent round the loop twice."""
134
+ for message in messages:
135
+ print(f"error: {message}", file=sys.stderr)
136
+ return ex.BAD_CALL
137
+
138
+
139
+ def _refocus_link(value: str | None) -> str | None:
140
+ """The run id `--refocus-of` names, or None where it was not given.
141
+
142
+ One trailing `.db` is stripped rather than refused: the store holds
143
+ `<id>.db` files, so that is what tab-completion and a copied `ls` line
144
+ hand a person, and the id inside it is unambiguous.
145
+
146
+ Both refusals end `nothing was run.` because that is the fact the
147
+ caller needs: this check happens before anything is minted or spawned,
148
+ so a re-run refused here has left no half-recording behind to clean up.
149
+ The second names the STORE, not the file it looked for -- a person
150
+ given the directory can list it; a person given a path that does not
151
+ exist has been told what they already knew.
152
+ """
153
+ if value is None:
154
+ return None
155
+ run_id = value[:-3] if value.endswith(".db") else value
156
+ if not paths.is_valid_run_id(run_id):
157
+ # `../x`, `a/b`, `.`: an id flows straight into `traces_dir() /
158
+ # f"{id}.db"`, so one that is not a single path component would
159
+ # read outside the store. The value is echoed AS GIVEN, suffix and
160
+ # all, because that is what the caller typed and has to correct.
161
+ raise LinkError(f"--refocus-of {value} is not a run id; "
162
+ "nothing was run.")
163
+ if not (paths.traces_dir() / f"{run_id}.db").is_file():
164
+ raise LinkError(f"--refocus-of {run_id} names no trace in "
165
+ f"{paths.trace_root()}; nothing was run.")
166
+ return run_id
167
+
168
+
169
+ def _record(plan, package: Path, node: str, cwd: Path, args,
170
+ focus: Sequence[str], resolution,
171
+ link: str | None = None) -> int:
172
+ """Everything from the mint to the conversion."""
173
+ inv_id = paths.new_run_id()
174
+ # One level at a time, 0700 each, for `paths.traces_dir()`'s reason:
175
+ # `Path.mkdir(parents=True, mode=...)` applies the mode to the directory
176
+ # it NAMES and gives every parent it creates on the way the default, so
177
+ # a single `spool.mkdir(parents=True, mode=0o700)` would leave
178
+ # `<store>/spool` -- and the store root above it, where `redaction.key`
179
+ # lives -- at 0775. Measured at 0775 by E16 part A (H2). An existing
180
+ # directory is never chmod'ed: the user's own store is theirs.
181
+ root = paths.trace_root()
182
+ root.mkdir(parents=True, exist_ok=True, mode=0o700)
183
+ (root / SPOOL_DIR).mkdir(exist_ok=True, mode=0o700)
184
+ spool = root / SPOOL_DIR / inv_id
185
+ spool.mkdir(exist_ok=True, mode=0o700)
186
+ config = (wrapper.home(plan.root) /
187
+ f"{inv_id}{wrapper.CONFIG_SUFFIX}"
188
+ if plan.kind == "vitest" else None)
189
+ _write_record(spool, plan, inv_id, node, package, config, focus,
190
+ [] if resolution is None else resolution.matched_specs,
191
+ None if resolution is None else resolution.wall,
192
+ refocus_of=link)
193
+
194
+ files: tuple = ()
195
+ try:
196
+ if plan.kind == "vitest":
197
+ files = wrapper.write(plan.root, inv_id, package,
198
+ plan.user_config)
199
+ argv = plan.vitest_command(files[0])
200
+ else:
201
+ argv = plan.node_command(package / "src" / "register.mjs")
202
+ try:
203
+ ending = _spawn(argv,
204
+ _env(spool, inv_id, plan, package, args.tier,
205
+ focus, args=args),
206
+ cwd)
207
+ except OSError as e:
208
+ # Nothing ran, so there is nothing to convert and nothing to
209
+ # keep: the record of an invocation that never happened would
210
+ # be listed by `runs` forever.
211
+ _discard(spool)
212
+ raise SpawnError(
213
+ f"{argv[0]} could not be started: {e.strerror}") from None
214
+ invocation.write_record(
215
+ spool / invocation.HARNESS_FILE,
216
+ json.dumps(ending.to_json(), indent=2) + "\n")
217
+ finally:
218
+ wrapper.remove(files)
219
+ return _convert(spool, inv_id, ending, getattr(args, "jobs", None),
220
+ args.tier)
221
+
222
+
223
+ def _discard(spool: Path) -> None:
224
+ """Take back a spool directory nothing was recorded into, and the
225
+ `spool/` above it when this invocation is what made it. Stops at a
226
+ directory another invocation is still using, exactly as
227
+ `wrapper.remove` does."""
228
+ for path in sorted(spool.iterdir()):
229
+ path.unlink(missing_ok=True)
230
+ for directory in (spool, spool.parent):
231
+ try:
232
+ directory.rmdir()
233
+ except OSError:
234
+ return
235
+
236
+
237
+ # -- the record --------------------------------------------------------------
238
+
239
+
240
+ def _write_record(spool: Path, plan, inv_id: str, node: str, package: Path,
241
+ config: Path | None, focus: Sequence[str] = (),
242
+ focus_matched: Sequence[str] = (),
243
+ resolver_wall_s: float | None = None,
244
+ refocus_of: str | None = None) -> None:
245
+ """`invocation.json`, written BEFORE the harness is spawned.
246
+
247
+ It is the only thing that can say what a spool directory came out of: a
248
+ container knows its own pid and its own environment, but not which
249
+ command produced it and not where the project root is.
250
+ """
251
+ record = invocation.Invocation(
252
+ invocation=inv_id, harness=plan.kind,
253
+ harness_args=list(plan.harness_args), root=str(plan.root),
254
+ # `plan.argv` is the tokens as typed, kept whole by `recognise`
255
+ # before `_consume` takes `--root`/`--config` out and before either
256
+ # `vitest_command`/`node_command` re-issues anything. That is the
257
+ # one list a reader can be shown and recognise as their own (R26).
258
+ command=list(plan.argv),
259
+ cwd=str(Path.cwd()), argv=list(plan.argv), env_hash=_env_hash(),
260
+ start_ts=time.time(), wrapper="" if config is None else str(config),
261
+ vitest=_vitest_version(plan), node=node,
262
+ driver_version=_driver_version(),
263
+ recorder=f"sensorium-ts {pkg_mod.version(package)}",
264
+ # Both, and always: the specs as typed and the functions they
265
+ # selected. A reader of this directory should not have to know which
266
+ # driver version wrote it to know that nothing was focused.
267
+ focus=list(focus), focus_matched=list(focus_matched),
268
+ # What resolving them cost, so an instrument can time the resolver
269
+ # without timing the driver around it. `None` where no focus was
270
+ # given: the resolver did not run, and 0.0 would say it did.
271
+ resolver_wall_s=resolver_wall_s,
272
+ # The run this one re-runs, validated before anything was minted.
273
+ # `None` is a command a person typed, and the converter then writes
274
+ # no `refocus_of` key at all: an absent key is what every reader of
275
+ # a trace branches on.
276
+ refocus_of=refocus_of)
277
+ invocation.write_record(spool / invocation.INVOCATION_FILE,
278
+ json.dumps(record.to_json(), indent=2) + "\n")
279
+
280
+
281
+ def _env_hash() -> str:
282
+ """A digest of the DRIVER's environment, by the recipe both this
283
+ recorder's halves use (`invocation.env_hash`).
284
+
285
+ The driver's and not the harness's: the harness's differs from it by the
286
+ variables written two functions below, which are the recorder's own and
287
+ would make every invocation's hash unique by construction -- the
288
+ redaction key most of all, which is 64 characters no two stores share.
289
+ """
290
+ return invocation.env_hash(os.environ)
291
+
292
+
293
+ def _driver_version() -> str:
294
+ try:
295
+ return importlib.metadata.version("sensorium-trace")
296
+ except importlib.metadata.PackageNotFoundError:
297
+ return "sensorium (uninstalled source tree)"
298
+
299
+
300
+ def _vitest_version(plan) -> str | None:
301
+ """Which vitest the consumer's tree holds, or None.
302
+
303
+ None for `node --test`, which has no vitest, and None for a vitest run
304
+ whose package cannot be read -- an absent version is written as no key
305
+ at all by the converter, never as an empty string.
306
+ """
307
+ if plan.kind != "vitest":
308
+ return None
309
+ manifest = plan.root / "node_modules" / "vitest" / "package.json"
310
+ try:
311
+ text = manifest.read_text(encoding="utf-8")
312
+ except OSError:
313
+ return None
314
+ m = re.search(r'"version"\s*:\s*"([^"]*)"', text)
315
+ return m.group(1) if m else None
316
+
317
+
318
+ def _env(spool: Path, inv_id: str, plan, package: Path, tier: str,
319
+ focus: Sequence[str], args=None) -> dict:
320
+ """The harness's environment: the driver's own, plus what the recorder
321
+ inside the harness cannot work out for itself.
322
+
323
+ `SENSORIUM_FOCUS` is set only when there IS a focus, and holds the specs
324
+ as typed, joined by the separator. One variable answers for all three
325
+ readers inside the harness -- the Vite plugin, the loader hook and the
326
+ runtime -- and an EMPTY one is not the same as an absent one to the last
327
+ of them: the runtime declares `line` and `locals` from its presence, and
328
+ an empty value would declare capabilities nothing was going to write.
329
+
330
+ It is the one inherited variable this driver overrides rather than
331
+ passes on. A `SENSORIUM_FOCUS` left in a shell would otherwise focus a
332
+ run whose own record says `focus: []` -- the recording would carry
333
+ statement rows nobody asked for, and the record beside it would deny it.
334
+
335
+ `SENSORIUM_REDACT_KEY` is the eighth, and the one the harness could not
336
+ work out even in principle: the runtime only ever PARSES a key, because
337
+ creating one means a directory, a temporary, a link and a race and the
338
+ runtime is linked into somebody else's test suite (design section 3). So
339
+ the STORE's key -- the same `<trace root>/redaction.key` the Python
340
+ recorder and `cargo-sensorium` use, minted here on first use -- is handed
341
+ down as hex. Set only when there IS a key: absent and malformed read
342
+ identically to the runtime, and an unkeyed store POPS whatever the
343
+ launching shell was carrying, because a key from some other store would
344
+ have the recorder write digests nothing here can verify.
345
+
346
+ The three cap variables are resolved here, once, from the command, the
347
+ environment and the store config, and written as integers. The runtime
348
+ reads the numbers and does not open the config. ``0`` is unlimited. A
349
+ value already in the environment is overwritten: the command wins, then
350
+ the environment, then the config, then the default.
351
+ """
352
+ env = dict(os.environ,
353
+ SENSORIUM_SPOOL=str(spool),
354
+ SENSORIUM_TIER=tier,
355
+ SENSORIUM_TS_ROOT=str(plan.root),
356
+ SENSORIUM_TS_PKG=str(package),
357
+ SENSORIUM_INVOCATION=inv_id,
358
+ SENSORIUM_MANIFEST_DIR=str(spool / ingest.MANIFEST_DIR))
359
+ if focus:
360
+ env["SENSORIUM_FOCUS"] = focus_mod.SEP.join(focus)
361
+ else:
362
+ env.pop("SENSORIUM_FOCUS", None)
363
+ key = redact.Key.load_or_create(paths.trace_root())
364
+ if key.material is None:
365
+ env.pop(redact.KEY_VAR, None)
366
+ else:
367
+ env[redact.KEY_VAR] = key.material.hex()
368
+ limits = _caps(args)
369
+ env["SENSORIUM_MAX_EVENTS"] = str(limits.max_events)
370
+ env["SENSORIUM_MAX_BYTES"] = str(limits.max_bytes)
371
+ env["SENSORIUM_MAX_CALLS"] = str(limits.max_calls)
372
+ return env
373
+
374
+
375
+ def _caps(args):
376
+ """The cap for this run. ``args`` may be None when a caller of `_env`
377
+ has no command object; the environment and the config still apply."""
378
+ from sensorium.limits import resolve
379
+ return resolve(
380
+ max_events=getattr(args, "max_events", None),
381
+ max_bytes=getattr(args, "max_bytes", None),
382
+ max_calls=getattr(args, "max_calls", None),
383
+ no_cap=bool(getattr(args, "no_cap", False)),
384
+ )
385
+
386
+
387
+ # -- the run -----------------------------------------------------------------
388
+
389
+
390
+ def _spawn(argv: list[str], env: dict, cwd: Path) -> invocation.HarnessExit:
391
+ """Run the harness with the caller's own stdio and wait for it.
392
+
393
+ Inherited stdio, not captured: the harness's output is what the user
394
+ came for, it is often interactive, and a recorder that buffered a
395
+ ten-minute test run would look like a hang.
396
+ """
397
+ start = time.time()
398
+ completed = subprocess.run(argv, env=env, cwd=cwd)
399
+ end = time.time()
400
+ if completed.returncode < 0:
401
+ name = signal.Signals(-completed.returncode).name
402
+ return invocation.HarnessExit(None, name, start, end)
403
+ return invocation.HarnessExit(completed.returncode, None, start, end)
404
+
405
+
406
+ def _status(ending: invocation.HarnessExit) -> int:
407
+ """The driver's own exit status: the harness's, `128 + n` on a signal --
408
+ the number a shell reports for exactly that death."""
409
+ if ending.signal is not None:
410
+ return 128 + int(signal.Signals[ending.signal])
411
+ return ending.status or 0
412
+
413
+
414
+ def _ending(ending: invocation.HarnessExit) -> str:
415
+ """How the run line says the harness ended. `basis` is always `waited`
416
+ and is printed: it is the one exit fact in a TypeScript recording that
417
+ somebody actually witnessed."""
418
+ if ending.signal is not None:
419
+ return f"signal {ending.signal} (waited)"
420
+ return f"{ending.status} (waited)"
421
+
422
+
423
+ def _convert(spool: Path, inv_id: str, ending, jobs: int | None,
424
+ tier: str) -> int:
425
+ """One trace per container, then the run's own lines.
426
+
427
+ A spool the converter refuses prints its refusal and does NOT change the
428
+ exit status: the status belongs to the harness. An ingest that could not
429
+ start at all is the exception -- there is no recording to report, and
430
+ exit 2 says the call or the directory has to be fixed. Where the WRAPPER
431
+ is what refused, its own sentence is printed instead of the converter's
432
+ (R41): only it knows why the run recorded nothing.
433
+
434
+ At tier `off` there is nothing to convert BY DESIGN -- the transform
435
+ still runs, the runtime emits nothing, and the invocation's whole value
436
+ is the harness's own wall time. So the empty directory is reported as
437
+ the zero it is, and never as the failure it would be at tier `call`,
438
+ where an empty directory means the recorder was wired in and recorded
439
+ nothing.
440
+ """
441
+ from sensorium.ts import cli as ts_cli
442
+ if tier == "off":
443
+ ts_cli._report([], inv_id, harness=_ending(ending))
444
+ return _after(_status(ending))
445
+ try:
446
+ summaries = ingest.ingest_dir(spool, paths.trace_root(), jobs=jobs)
447
+ except (ingest.IngestError, invocation.InvocationError) as e:
448
+ # The wrapper's own refusal FIRST (R41). "nothing was recorded, or
449
+ # the recorder wrote somewhere else" is what this looks like from
450
+ # here, and it names neither the cause nor the fix; the config that
451
+ # refused knows both, and left the sentence behind.
452
+ return _refuse(wrapper.refusal(spool) or str(e))
453
+ ts_cli._report(summaries, inv_id, harness=_ending(ending))
454
+ return _after(_status(ending))
455
+
456
+
457
+ def _after(status: int) -> int:
458
+ """The harness status, after the store applies its retention rule.
459
+
460
+ ``maybe_auto`` is a no-op when no rule is configured. A failure is
461
+ printed and does not replace the status: the status belongs to the
462
+ harness.
463
+ """
464
+ try:
465
+ from sensorium.store.gc import maybe_auto
466
+ note = maybe_auto()
467
+ except Exception as e:
468
+ print(f"sensorium: gc failed: {e}", file=sys.stderr)
469
+ return status
470
+ if note:
471
+ print(note, file=sys.stderr)
472
+ return status