sensorium-trace 0.18.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,213 @@
1
+ """List recorded traces, newest-last."""
2
+ from sensorium import paths
3
+ from sensorium.exit import ANSWERED, NEGATIVE
4
+ from sensorium.query.vocab import exit_brief
5
+ from sensorium.store.reader import Trace
6
+
7
+
8
+ def _licence_flag(m: dict) -> str:
9
+ """`(granted)` is not what was granted.
10
+
11
+ A bare "granted" here reads as unbounded, which is the same failure this
12
+ listing already refuses for a bare "refocus-of" and a bare "MATCH", one
13
+ step further along: what `refocus` actually grants is a licence over a
14
+ counted, itemised set of points, and `sensorium info` prints them. Say
15
+ how many, and where to read them. A withheld licence keeps its own count
16
+ for the same reason.
17
+ """
18
+ licence = m.get("refocus_licence")
19
+ if not licence:
20
+ return ""
21
+ key = ("refocus_licence_verified" if licence == "granted"
22
+ else "refocus_licence_reasons")
23
+ n = len(m.get(key) or [])
24
+ if not n:
25
+ return f"({licence},points-not-recorded)"
26
+ return f"({licence}:{n},see-info)"
27
+
28
+
29
+ def add_parser(sub) -> None:
30
+ p = sub.add_parser(
31
+ "runs", help="list recorded traces",
32
+ description="One line per trace, oldest first: run id, exit, event "
33
+ "count, the command; a refocus rerun names its original "
34
+ "and its verdict.",
35
+ epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
36
+ p.set_defaults(func=run)
37
+
38
+
39
+ def _cmd(m: dict) -> str:
40
+ """What was run, as short as it can be said without losing it.
41
+
42
+ A Rust trace's `argv[0]` is the absolute path of a test binary under
43
+ `target/`, which is 90 characters of build directory and one useful
44
+ word. The basename of `exe` is that word; `info` prints the full path,
45
+ so nothing is lost -- it moves to the view that has room for it. A trace
46
+ with no `exe` (every Python one) is unchanged: its whole argv.
47
+ """
48
+ argv = m.get("argv") or []
49
+ exe = m.get("exe")
50
+ if not exe:
51
+ return " ".join(argv)
52
+ return " ".join([str(exe).rsplit("/", 1)[-1], *argv[1:]])
53
+
54
+
55
+ def _row(stem: str, trace: Trace) -> str:
56
+ m = trace.meta
57
+ flags = []
58
+ if m.get("incomplete"):
59
+ flags.append("INCOMPLETE")
60
+ if m.get("trace_truncated"):
61
+ flags.append("TRUNCATED")
62
+ if m.get("refocus_of"):
63
+ # The verdict rides with the label, and the licence rides with
64
+ # the verdict. A bare "refocus-of" reads as a pedigree; a bare
65
+ # "verdict:MATCH" reads as a clean bill of health for a rerun
66
+ # whose licence was withheld on every count. Same failure, one
67
+ # level down.
68
+ flags.append(f"refocus-of:{m['refocus_of']}")
69
+ flags.append(f"verdict:{m.get('refocus_verdict', 'UNVERIFIED')}"
70
+ + _licence_flag(m))
71
+ suffix = f" [{','.join(flags)}]" if flags else ""
72
+ return (f"{stem} exit:{exit_brief(m)} "
73
+ f"events:{sum(trace.counts().values())} "
74
+ f"{_what(m, trace.lang)}{suffix}")
75
+
76
+
77
+ def _what(m: dict, lang: str) -> str:
78
+ """Which process this row is, in the fewest words that still tell it
79
+ apart from the others in its invocation.
80
+
81
+ A Rust invocation's members are distinct BINARIES, so the command is
82
+ what tells them apart. A vitest invocation's members are workers of one
83
+ harness: every one of them has the same
84
+ `node .../vitest/dist/workers/forks.js` command line, and a listing of
85
+ them by argv is a column of identical strings. What differs is the test
86
+ FILE the container ran, which the converter records as `test_file`
87
+ (`typescript/HONESTY.md` section 6) -- so that is what the row shows,
88
+ and `info` keeps the whole command line.
89
+
90
+ A reused worker ran several files and carries `test_files`: the count,
91
+ not the list, because a row is one line. A container that ran none -- a
92
+ `globalSetup` in the main process, any `node --test` process -- carries
93
+ neither key and keeps its argv, and that ABSENCE is the recorder's
94
+ statement rather than a gap.
95
+
96
+ GATED ON `lang`, NOT ON THE KEY BEING THERE (R27a). `info` has always
97
+ decided its language-specific blocks by `trace.lang` and never by
98
+ sniffing a key, for the reason `vocab` exists: a key name is not a
99
+ recorder's signature, and one recorder reading another's key off a
100
+ trace is the same class of error as reading another's WORD off it. Two
101
+ commands over one trace must not disagree about which recorder wrote
102
+ it, so `runs` reads the language the same way.
103
+ """
104
+ if lang != "typescript":
105
+ return f"cmd: {_cmd(m)}"
106
+ one = m.get("test_file")
107
+ if one:
108
+ return f"file: {one}"
109
+ several = m.get("test_files")
110
+ if several:
111
+ return f"files: {len(several)}"
112
+ return f"cmd: {_cmd(m)}"
113
+
114
+
115
+ def _header(m: dict, lang: str) -> str:
116
+ """The command one invocation's traces all came out of, in the words of
117
+ whatever ran it.
118
+
119
+ Without it a `cargo test` run is 30 unrelated-looking rows with 30
120
+ build-directory paths, and a `vitest run` is a dozen rows of the same
121
+ worker script; with it they are one command's processes, and the reader
122
+ can see at a glance that they belong together.
123
+
124
+ THE EXIT STATUS IS THE DIFFERENCE BETWEEN THE TWO HEADERS, and it is a
125
+ difference in what was RECORDED, not in taste. The cargo runner shim
126
+ waits for each test binary and nothing waits for cargo, so a Rust
127
+ invocation has no status to print and this line does not claim one. The
128
+ TypeScript driver spawns the harness and waits for the harness, so
129
+ `harness_exit` is a status somebody really did observe -- carried with
130
+ its own basis, and printed with it (`(waited)`), because that is the
131
+ whole of what makes it different from the `unwitnessed` on every member
132
+ row below it.
133
+
134
+ Which of the two is decided by `lang` and never by the presence of a
135
+ `harness` key, for the reason `_what` gives at length (R27a).
136
+ """
137
+ if lang == "typescript":
138
+ return (f"invocation {m['invocation']}: {_harness_cmd(m)}"
139
+ + _harness_exit(m))
140
+ if lang == "c":
141
+ # The command the driver was given. Never `cargo`: that word is
142
+ # the Rust header's, and a C invocation does not run it. The
143
+ # harness exit is the same witness the TypeScript header prints.
144
+ command = " ".join(str(a) for a in (m.get("driver_command") or []))
145
+ return (f"invocation {m['invocation']}: {command}".rstrip()
146
+ + _harness_exit(m))
147
+ args = " ".join(m.get("cargo_args") or [])
148
+ return (f"invocation {m['invocation']}: cargo"
149
+ + (f" {args}" if args else ""))
150
+
151
+
152
+ def _harness_cmd(m: dict) -> str:
153
+ """The command the user typed, verbatim (R26).
154
+
155
+ `harness_command` is those tokens before the driver consumed or
156
+ re-issued anything, and it is the only list here that is a command.
157
+ The fallback is for a trace whose converter predates the key, and it
158
+ is what this line printed before: `harness` + `harness_args`, which
159
+ reconstructs a plausible-looking command rather than the real one --
160
+ `node-test --test test/` names no program, and a `--root` the user
161
+ passed is missing from it. Kept because the alternative for such a
162
+ trace is printing nothing at all; corrected by re-recording.
163
+ """
164
+ typed = m.get("harness_command")
165
+ if typed:
166
+ return " ".join(typed)
167
+ return " ".join([m["harness"], *(m.get("harness_args") or [])]).rstrip()
168
+
169
+
170
+ def _harness_exit(m: dict) -> str:
171
+ """How the harness ended, when somebody waited for it -- and nothing at
172
+ all when the record is absent, which is a driver killed before the
173
+ harness returned rather than a harness that ended at 0.
174
+
175
+ `status` and `signal` are exclusive: a process killed by a signal chose
176
+ no status, and printing `exit:None` for one is the failure the whole
177
+ exit rule exists to stop (TRACE-FORMAT section 4).
178
+ """
179
+ ending = m.get("harness_exit")
180
+ if not ending:
181
+ return ""
182
+ basis = ending.get("basis", "waited")
183
+ if ending.get("status") is not None:
184
+ return f" exit:{ending['status']} ({basis})"
185
+ if ending.get("signal") is not None:
186
+ return f" exit:signal {ending['signal']} ({basis})"
187
+ return ""
188
+
189
+
190
+ def run(args) -> int:
191
+ files = sorted(paths.traces_dir().glob("*.db"), key=lambda p: p.name)
192
+ if not files:
193
+ print("no traces recorded")
194
+ return NEGATIVE
195
+ # Opened in name order, exactly as before, and rendered in one pass
196
+ # afterwards: a group's members are its whole invocation, which can be
197
+ # anywhere in the listing, so the rows have to exist before the first
198
+ # header can be printed.
199
+ rows = [(f.stem, Trace.open(f)) for f in files]
200
+ seen: set = set()
201
+ for stem, trace in rows:
202
+ inv = trace.meta.get("invocation")
203
+ if inv is None:
204
+ print(_row(stem, trace))
205
+ continue
206
+ if inv in seen:
207
+ continue # printed under its own header
208
+ seen.add(inv)
209
+ print(_header(trace.meta, trace.lang))
210
+ for stem2, t2 in rows:
211
+ if t2.meta.get("invocation") == inv:
212
+ print(" " + _row(stem2, t2))
213
+ return ANSWERED
@@ -0,0 +1,176 @@
1
+ """Rust `Debug` text: read one way, written one way, one escape table.
2
+
3
+ A `dbg` capture is what a probe got out of a value's own `Debug` impl --
4
+ TEXT, and the only thing a recorder can get for a type it cannot decompose.
5
+ Two commands have to make sense of that text and they must not disagree:
6
+ `watch --expr` READS it (`read_debug`, the value the text spells) and
7
+ `flow --value` WRITES it (`debug_text`, the rendering a literal would have).
8
+ An escape undone in one and re-applied differently in the other would report
9
+ a sighting that the predicate at the same site then denies, so both live
10
+ here, over one table.
11
+
12
+ WHAT IS PINNED, AND HOW IT WAS ESTABLISHED
13
+ ------------------------------------------
14
+ Rust's spellings were MEASURED with `rustc` (2026-09-06), not assumed, and
15
+ two of them differ from Python's `repr` in ways no reader would guess:
16
+
17
+ 2.0 -> "2.0" (same as repr)
18
+ 1e20 -> "1e20" (repr says `1e+20`)
19
+ 1e-5 -> "1e-5" (repr says `1e-05`)
20
+ "café" -> "café" (Debug escapes neither: non-ASCII is printable)
21
+ inf/-inf -> "inf"/"-inf" and NaN -> "NaN" (measured, all three)
22
+ "a\"b" -> "a\\"b" (`"` and `\\` are escaped, `'` is NOT)
23
+ '\\x07' -> "\\u{7}" (unprintables, minimal lowercase hex)
24
+ None -> "None" (an `Option`, printed as the word)
25
+
26
+ THE TWO DIRECTIONS ARE INVERSES ON THE LITERAL DOMAIN
27
+ -----------------------------------------------------
28
+ Design amendment A11: `read_debug` parses exactly what `debug_text` can
29
+ spell, so `resolve(dbg(debug_text(L))) == L` for every literal `L` a
30
+ command accepts. This is not tidiness -- it is the fix for a measured
31
+ disagreement. With `read_debug` stopping at the decimal forms, `flow
32
+ --value 1e20` reported a sighting of a capture that `watch --expr x ==
33
+ 1e20` at that same site then denied (a plain False out of comparing text
34
+ with a float), and the same went for `1e400`/`inf` and for `None`. One
35
+ instrument answering yes and no about one capture is worse than either
36
+ answer, so the domains are pinned together: integers, floats in every
37
+ Debug spelling Rust uses (`2.5`, `1e20`, `1e-5`, `inf`, `-inf`, `NaN`),
38
+ `true`/`false`, the bare `None`, and quoted strings.
39
+
40
+ THE ONE THING NEITHER DIRECTION DOES
41
+ ------------------------------------
42
+ Guess. `read_debug` returns the text itself whenever the text spells no
43
+ literal (a struct, an enum, a `Vec`), because the text is what the trace
44
+ holds; `debug_text` returns None for a target that has no Rust spelling,
45
+ and a capture then matches nothing rather than matching approximately.
46
+ """
47
+ import re
48
+
49
+ # A Debug integer, and a Debug float -- a decimal POINT, an EXPONENT, or
50
+ # both, which is every shape Rust prints (`2.5`, `1e20`, `1e-5`, `1.5e-7`).
51
+ # The integer is tried first, so `5` is an int and never a float.
52
+ _INT = re.compile(r"-?\d+")
53
+ _FLOAT = re.compile(r"-?\d+\.\d+([eE][-+]?\d+)?|-?\d+([eE][-+]?\d+)")
54
+ # The three floats Rust spells as words rather than digits (measured).
55
+ _WORD_FLOATS = {"inf": float("inf"), "-inf": float("-inf"),
56
+ "NaN": float("nan")}
57
+ # Python's repr writes an exponent's sign and pads it to two digits; Rust
58
+ # writes neither. `1e+20` -> `1e20`, `1e-05` -> `1e-5`.
59
+ _EXP = re.compile(r"e\+?(-?)0*(\d)")
60
+
61
+ # `\'` never appears in a string's Debug (Rust escapes a single quote only
62
+ # inside a char's), and it is read anyway: undoing an escape the writer did
63
+ # not have to make is harmless, refusing one is not.
64
+ _UNESCAPE = {"n": "\n", "t": "\t", "r": "\r", "0": "\0",
65
+ "\\": "\\", '"': '"', "'": "'"}
66
+ _ESCAPE = {"\\": "\\\\", '"': '\\"', "\n": "\\n", "\t": "\\t",
67
+ "\r": "\\r", "\0": "\\0"}
68
+ _HEX = "0123456789abcdefABCDEF"
69
+
70
+
71
+ def read_debug(text: str):
72
+ """The value a Debug text spells: int, float, bool, None, str, or text.
73
+
74
+ The caller has already dealt with truncation -- a clipped rendering is
75
+ not a rendering, and nothing here may be applied to a prefix.
76
+ """
77
+ if _INT.fullmatch(text):
78
+ return int(text)
79
+ if _FLOAT.fullmatch(text):
80
+ return float(text)
81
+ if text in _WORD_FLOATS:
82
+ return _WORD_FLOATS[text]
83
+ if text in ("true", "false"):
84
+ return text == "true"
85
+ if text == "None":
86
+ # `Option::None`, and the one way a reader can name it: `flow
87
+ # --value None` already searches for this text, so a predicate at
88
+ # the same site has to see the same thing (A11).
89
+ return None
90
+ if len(text) >= 2 and text[0] == '"' == text[-1]:
91
+ return unescape_debug(text[1:-1])
92
+ return text
93
+
94
+
95
+ def unescape_debug(inner: str) -> str:
96
+ r"""The characters a Debug string's body stands for.
97
+
98
+ Hand-written rather than `codecs.decode(.., "unicode_escape")`, which
99
+ decodes latin-1 and so turns every non-ASCII character Rust printed
100
+ literally into mojibake -- `"café"` would come back as `café` and
101
+ compare unequal to the string the program held.
102
+
103
+ An escape this table does not know is left EXACTLY as it was read: a
104
+ reader comparing against text sees the same characters the trace holds,
105
+ rather than a silent reinterpretation of them.
106
+ """
107
+ out: list[str] = []
108
+ i, n = 0, len(inner)
109
+ while i < n:
110
+ ch = inner[i]
111
+ if ch != "\\" or i + 1 >= n:
112
+ out.append(ch)
113
+ i += 1
114
+ continue
115
+ nxt = inner[i + 1]
116
+ if nxt in _UNESCAPE:
117
+ out.append(_UNESCAPE[nxt])
118
+ i += 2
119
+ continue
120
+ if nxt == "u" and inner[i + 2:i + 3] == "{":
121
+ end = inner.find("}", i + 3)
122
+ digits = inner[i + 3:end] if end != -1 else ""
123
+ if digits and all(c in _HEX for c in digits):
124
+ try:
125
+ out.append(chr(int(digits, 16)))
126
+ except ValueError:
127
+ pass # beyond U+10FFFF: leave it read
128
+ else:
129
+ i = end + 1
130
+ continue
131
+ out.append(ch)
132
+ i += 1
133
+ return "".join(out)
134
+
135
+
136
+ def escape_debug(s: str) -> str:
137
+ """A string's characters as Rust's `Debug` prints them, without quotes.
138
+
139
+ `str::escape_debug` escapes `\\` `"` and the unprintables and leaves
140
+ everything else alone; `'` is escaped only in a char's Debug, never in a
141
+ string's. `str.isprintable()` is Python's name for the same category
142
+ test (Cc, Cf, Cs, Co, Cn, Zl, Zp and the non-space Zs are not printable
143
+ in either language), so the two agree on which characters need `\\u{..}`.
144
+ """
145
+ out = []
146
+ for ch in s:
147
+ esc = _ESCAPE.get(ch)
148
+ if esc is not None:
149
+ out.append(esc)
150
+ elif ch.isprintable():
151
+ out.append(ch)
152
+ else:
153
+ out.append(f"\\u{{{ord(ch):x}}}")
154
+ return "".join(out)
155
+
156
+
157
+ def debug_text(target) -> str | None:
158
+ """How Rust's `Debug` would spell this literal, or None if it would not.
159
+
160
+ None is the honest answer for anything with no Rust spelling (an
161
+ `ObjTarget`, say): a capture then matches it nowhere, rather than
162
+ matching something adjacent.
163
+ """
164
+ if target is None:
165
+ return "None" # `Option::None`, as Rust prints
166
+ if isinstance(target, bool): # before int: a bool IS an int
167
+ return "true" if target else "false"
168
+ if isinstance(target, int):
169
+ return str(target)
170
+ if isinstance(target, float):
171
+ if target != target:
172
+ return "NaN" # `repr` says `nan`; Rust `NaN`
173
+ return _EXP.sub(r"e\1\2", repr(target))
174
+ if isinstance(target, str):
175
+ return '"' + escape_debug(target) + '"'
176
+ return None
@@ -0,0 +1,171 @@
1
+ """One recorded site: how a reader names it, and how a reader is shown it.
2
+
3
+ A SITE is a code object -- a file and a qualname -- and three commands have
4
+ to agree about how it is written down: `watch --at` reads a spelling from
5
+ the command line, `watch`'s no-match listing and its re-record guidance
6
+ write one back, and `sensorium ts run --focus` (a different program, in a
7
+ different language) reads one before a run. A reader who focused a function
8
+ and then asks about it types the SAME characters both times, or the second
9
+ command answers "no recorded code matches" about the function they just
10
+ recorded.
11
+
12
+ So the spelling lives here, once, keyed on the trace's own vocabulary:
13
+
14
+ * `"module"` -- Python's dotted module name, derived from the run's root,
15
+ which is what `watch` has always printed and what Rust's listings quote
16
+ (plan P8: the design's `"stem"` for Rust would move a closed record's
17
+ bytes for no gain).
18
+ * `"rel"` -- the path relative to the invocation's root, which is what a
19
+ TypeScript `--focus` is typed with and what `meta.focus_matched`
20
+ records.
21
+
22
+ WHAT `--at` ACCEPTS, AND WHY IT IS WIDER THAN WHAT IT PRINTS
23
+ ------------------------------------------------------------
24
+ Matching is deliberately wider than spelling: the file half of a spec may
25
+ be the dotted module, the stem, the basename or the root-relative path, in
26
+ every language. That is additive -- nothing that matched before stops
27
+ matching -- and it is what makes every `--focus` spelling an `--at`
28
+ spelling. It stays a real boundary all the same: `lib` is a directory,
29
+ `src/cache.ts` is a path this trace does not hold, and neither selects
30
+ `src/lib/cache.ts`. Answering about a file the reader did not name is worse
31
+ than refusing, because the answer looks right.
32
+
33
+ TWO IMPLEMENTATIONS OF ONE RULE, ON PURPOSE
34
+ -------------------------------------------
35
+ `typescript/src/focus.mjs` applies the same rule to source before a run;
36
+ this applies it to a recorded trace after one. They cannot be one function
37
+ -- they are in different languages and see different inputs -- so they are
38
+ held to one example table instead,
39
+ `typescript/test/fixtures/site-spellings.json`. `focus.test.mjs` reads it
40
+ on that side and `tests/test_watch_typescript.py` on this one, and
41
+ `v39-site-spellings` asks the CLI those same ten rows as questions
42
+ (design 2026-09-11 section 4.3, ruling R7).
43
+ """
44
+ import shlex
45
+ from pathlib import Path
46
+
47
+ from sensorium.query.vocab import terms
48
+ from sensorium.record.tracer import module_name_for
49
+
50
+
51
+ def _anchor(trace) -> Path | None:
52
+ """The directory every relative path in this trace is relative to.
53
+
54
+ `root` is the invocation's, written by the TypeScript driver because
55
+ every `rel` in that trace -- the fingerprint's paths, the test file, a
56
+ `focus_matched` entry -- was made relative to it (plan P9); `cwd` is
57
+ what the Python recorder has always had. A trace with neither can still
58
+ be matched by stem and basename, which need no anchor at all.
59
+ """
60
+ root = trace.meta.get("root") or trace.meta.get("cwd")
61
+ return Path(root).resolve() if root else None
62
+
63
+
64
+ def _relative(file: str, anchor: Path | None) -> str | None:
65
+ """This file as the invocation named it, or None if it lies outside."""
66
+ if anchor is None:
67
+ return None
68
+ try:
69
+ return Path(file).resolve().relative_to(anchor).as_posix()
70
+ except ValueError:
71
+ return None
72
+
73
+
74
+ def _rel_site(trace, code) -> str:
75
+ rel = _relative(code.file, _anchor(trace))
76
+ # The basename is the honest fallback for a file outside the root (or a
77
+ # trace that records none): it is still a spelling `--at` accepts, and
78
+ # it never claims a path this recording cannot support.
79
+ return f"{rel or Path(code.file).name}:{code.qualname}"
80
+
81
+
82
+ def _module_site(trace, code) -> str:
83
+ anchor = _anchor(trace)
84
+ mod = module_name_for(code.file, anchor) if anchor else None
85
+ return f"{mod or Path(code.file).stem}:{code.qualname}"
86
+
87
+
88
+ _SPELLERS = {"rel": _rel_site, "module": _module_site}
89
+
90
+
91
+ def spell_site(trace, code) -> str:
92
+ """`<file>:<qualname>`, in this recorder's own spelling.
93
+
94
+ Strict, like `vocab.terms` itself: a `site_spelling` no speller answers
95
+ for is a programming error, not a trace a user can produce -- the
96
+ vocabulary table is closed and `tests/test_vocab.py` pins every
97
+ column's word.
98
+ """
99
+ return _SPELLERS[terms(trace).site_spelling](trace, code)
100
+
101
+
102
+ def file_names(trace, code) -> set[str]:
103
+ """Every spelling of this code object's FILE that `--at` accepts."""
104
+ path = Path(code.file)
105
+ anchor = _anchor(trace)
106
+ names = {path.stem, path.name}
107
+ if anchor is not None:
108
+ names.add(module_name_for(code.file, anchor))
109
+ names.add(_relative(code.file, anchor))
110
+ names.discard(None)
111
+ return names
112
+
113
+
114
+ def _qual_matches(qualname: str, spec: str) -> bool:
115
+ """`Pot` selects `Pot.add`, and `Counter` selects `Counter::new`.
116
+
117
+ A prefix counts only where it ends at a BOUNDARY -- Python's `.` or
118
+ Rust's `::` -- or `--at Counter` would quietly answer about
119
+ `Counters::new`, a different function the reader never named. One rule
120
+ holding both separators, and no `lang` branch anywhere near it: `watch`
121
+ takes the qualname its own recorder printed (design 2026-09-06 §4.1).
122
+ JavaScript's boundary is `.` as well, so the third recorder needed no
123
+ third separator -- `Fog` selects `Fog.compute` and `Fogs` selects
124
+ neither.
125
+
126
+ This is the only prefix rule in `query/`. `flow --object
127
+ <qualname>:<name>` names ONE function and resolves it by equality, so
128
+ there is no second copy of the rule to keep in step with this one; the
129
+ recorder's own focus matchers (`record/tracer`,
130
+ `typescript/src/focus.mjs`) are a different question, asked of source
131
+ before a run rather than of a recorded trace.
132
+ """
133
+ return (qualname == spec or qualname.startswith(spec + ".")
134
+ or qualname.startswith(spec + "::"))
135
+
136
+
137
+ def site_matches(code, at: str, trace) -> bool:
138
+ """Whether `--at <at>` selects this code object."""
139
+ mod, sep, qual = at.partition(":")
140
+ if sep:
141
+ if qual and not _qual_matches(code.qualname, qual):
142
+ return False
143
+ return not mod or mod in file_names(trace, code)
144
+ return (_qual_matches(code.qualname, at)
145
+ or at in file_names(trace, code))
146
+
147
+
148
+ def rerun_command(trace, codes) -> str:
149
+ """The exact command that records this run again with these frames'
150
+ locals.
151
+
152
+ Fully instantiated, including the run's own command line and any focus
153
+ it already had: a hint carrying a literal MODULE:QUALNAME placeholder is
154
+ a template, not an answer, and an agent reading it has to guess. The
155
+ focus already in the meta travels AS TYPED -- that is what its author
156
+ will recognise -- and the sites asked about are added in this
157
+ recorder's own spelling, which is what its `--focus` resolves.
158
+ """
159
+ words = terms(trace)
160
+ meta = trace.meta
161
+ specs = [*(meta.get("focus") or []),
162
+ *(spell_site(trace, c) for c in codes)]
163
+ focus = "".join(f" --focus {shlex.quote(s)}" for s in specs)
164
+ command = " ".join(shlex.quote(str(a))
165
+ for a in (meta.get(words.command_key) or []))
166
+ # `rstrip`, because a template whose `{command}` came back empty would
167
+ # otherwise end in a space -- and the Python column's bytes, which the
168
+ # legacy suite fences, have never had one (ruling R3).
169
+ body = words.rerun_command.format(focus=focus, command=command).rstrip()
170
+ cwd = meta.get("cwd")
171
+ return f"cd {shlex.quote(cwd)} && {body}" if cwd else body