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,317 @@
1
+ """The per-store key the digests are taken under: its 32 bytes at
2
+ `<trace root>/redaction.key`, and the once-only creation that publishes that
3
+ file whole.
4
+
5
+ Split out of `redact.py`, which holds rule v1's NAME rule and is about to
6
+ hold the content rule beside it. The key is a third question -- not "which
7
+ names hold a secret" nor "which values look like one", but "what are the
8
+ digests taken under" -- and the three together would have carried one module
9
+ to this repository's 800-line ceiling. `redact.py` imports `Key`, `KEY_VAR`,
10
+ `KEY_FILE`, `KEY_BYTES` and `KEY_MODE` straight back, so `redact.Key` and
11
+ `redact.KEY_VAR` keep resolving for every caller that already spells them
12
+ that way: this is a move, not an interface.
13
+
14
+ Rule v1 replaces a secret-shaped value with `<redacted>` at the WRITER,
15
+ before anything reaches disk, and keeps an HMAC-SHA256 of the plaintext
16
+ under `<trace root>/redaction.key` so `refocus` and `diff` can still say
17
+ "this changed" without printing what it changed to (design §2, §3). That
18
+ sentence came from `redact.py`'s docstring with the code: its second half --
19
+ the file, its bytes, and the digest taken under them -- is this module, and
20
+ its first half stayed with the name rule.
21
+
22
+ Like `redact.py`, this module is pure -- it imports nothing from `record` or
23
+ `query` -- and never raises.
24
+ """
25
+ import errno
26
+ import hashlib
27
+ import hmac
28
+ import os
29
+ import stat
30
+ from dataclasses import dataclass
31
+ from pathlib import Path
32
+
33
+ #: The hex key a driver hands a recorded process. DELETED from every
34
+ #: recorded environment rather than redacted (§3): a digest of the key under
35
+ #: the key is a pointless row, and `keyed: true` already implies it.
36
+ KEY_VAR = "SENSORIUM_REDACT_KEY"
37
+
38
+ #: `os.link` failures that mean "this filesystem cannot do that", not "this
39
+ #: went wrong": a filesystem without hard links (many network and container
40
+ #: mounts), or one that would be crossed. `os.replace` is the fallback there
41
+ #: -- atomic by name, but without `link`'s "loser cannot clobber the winner"
42
+ #: guarantee, which is why it is the fallback and not the mechanism.
43
+ _NO_LINK = frozenset({errno.EPERM, errno.ENOTSUP, errno.EXDEV})
44
+
45
+ #: The key file, a sibling of `traces/`, and its two fixed numbers.
46
+ KEY_FILE = "redaction.key"
47
+ KEY_BYTES = 32
48
+ KEY_MODE = 0o600
49
+ _ROOT_MODE = 0o700
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class Key:
54
+ """The store's redaction key: 32 bytes, or none of them and a reason.
55
+
56
+ Never raises, on any path. `material is None` is the whole of the
57
+ unkeyed state -- `keyed`, `key_id` and `digest` all read from it -- and
58
+ `problem` is the sentence `info` prints when a reader asks why.
59
+ """
60
+ path: Path
61
+ material: bytes | None
62
+ problem: str | None = None
63
+
64
+ @property
65
+ def keyed(self) -> bool:
66
+ return self.material is not None
67
+
68
+ @property
69
+ def key_id(self) -> str | None:
70
+ """`SHA-256(key)`, first 8 hex: whether two traces' digests are
71
+ comparable at all (§6.2)."""
72
+ if self.material is None:
73
+ return None
74
+ return hashlib.sha256(self.material).hexdigest()[:8]
75
+
76
+ @classmethod
77
+ def load(cls, root: Path) -> "Key":
78
+ """Read `root/redaction.key`. Never creates it, never raises."""
79
+ path = Path(root) / KEY_FILE
80
+ try:
81
+ material = path.read_bytes()
82
+ except OSError as e:
83
+ return cls(path, None, f"no {KEY_FILE}: {e}")
84
+ if len(material) != KEY_BYTES:
85
+ return cls(path, None, f"{KEY_FILE} is {len(material)} bytes, "
86
+ f"expected {KEY_BYTES}")
87
+ return cls(path, material)
88
+
89
+ @classmethod
90
+ def load_or_create(cls, root: Path) -> "Key":
91
+ """The key, creating it once at 0600 if it is not there.
92
+
93
+ The key is published BY CONTENT, never by an empty file that is
94
+ filled in a moment later (ruling R15): 32 bytes go into a private
95
+ `redaction.key.<pid>.tmp`, are written whole and fsynced, and only
96
+ then does `os.link` put the finished file at its name. An `O_EXCL`
97
+ open on the final name would be visible at 0 bytes for as long as the
98
+ write takes -- a concurrent recorder arriving in that window reads an
99
+ empty file and records unkeyed, and a process killed in it leaves a
100
+ 0-byte key that silently unkeys the store until a human deletes it.
101
+ Linking cannot do either: the name appears with all 32 bytes behind
102
+ it or not at all, and a loser's `FileExistsError` sends it to read
103
+ the winner's file. The tmp is unlinked on every path.
104
+
105
+ The store root is created 0700 on the way, because the first
106
+ recording into a fresh `SENSORIUM_DIR` would otherwise be unkeyed for
107
+ want of a directory.
108
+ """
109
+ root = Path(root)
110
+ path = root / KEY_FILE
111
+ try:
112
+ root.mkdir(parents=True, exist_ok=True, mode=_ROOT_MODE)
113
+ except OSError:
114
+ pass # the open below reports it, with the name of the file
115
+ # A key that is already there is the answer, whatever it says: a
116
+ # readable one is returned, and an unreadable or wrong-sized one is
117
+ # the user's file and is never written over.
118
+ existing = cls.load(root)
119
+ if existing.keyed or path.exists():
120
+ return existing
121
+ material = os.urandom(KEY_BYTES)
122
+ tmp = root / f"{KEY_FILE}.{os.getpid()}.tmp"
123
+ try:
124
+ problem = _write_key(tmp, material)
125
+ if problem is not None:
126
+ return cls(path, None, problem)
127
+ return cls._publish(root, path, tmp, material)
128
+ finally:
129
+ _unlink(tmp)
130
+
131
+ @classmethod
132
+ def _publish(cls, root: Path, path: Path, tmp: Path,
133
+ material: bytes) -> "Key":
134
+ """`tmp`'s finished content at `path`, or the winner's file re-read.
135
+
136
+ `os.replace` is the fallback for a filesystem that has no hard links:
137
+ it is atomic by name too, but it OVERWRITES, so a loser of the race
138
+ would replace the winner's key and leave two recordings with digests
139
+ that no longer compare. `load` afterwards is what makes that safe --
140
+ whoever wrote last, the material returned is the material the file
141
+ now holds, so the trace and the store never disagree.
142
+ """
143
+ try:
144
+ os.link(tmp, path)
145
+ except FileExistsError:
146
+ return cls.load(root)
147
+ except OSError as e:
148
+ if e.errno not in _NO_LINK:
149
+ return cls(path, None, f"cannot create {KEY_FILE}: {e}")
150
+ try:
151
+ os.replace(tmp, path)
152
+ except OSError as e2:
153
+ return cls(path, None, f"cannot create {KEY_FILE}: {e2}")
154
+ return cls.load(root)
155
+ return cls(path, material)
156
+
157
+ @classmethod
158
+ def from_hex(cls, text: str | None) -> "Key":
159
+ """The key a driver handed over in `SENSORIUM_REDACT_KEY`.
160
+
161
+ Exactly 64 hex characters and nothing else: `bytes.fromhex` accepts
162
+ embedded whitespace, and a key that arrived down a wire between two
163
+ implementations is checked for the shape it was promised in.
164
+ """
165
+ path = Path(KEY_VAR)
166
+ if not text or len(text) != 2 * KEY_BYTES:
167
+ return cls(path, None, f"{KEY_VAR} is not {2 * KEY_BYTES} hex "
168
+ f"characters")
169
+ try:
170
+ return cls(path, bytes.fromhex(text))
171
+ except ValueError:
172
+ return cls(path, None, f"{KEY_VAR} is not hex")
173
+
174
+ def digest(self, text: str) -> str | None:
175
+ """`HMAC-SHA256(key, text)`, first 16 hex -- an equality identity,
176
+ not a commitment -- or None when there is no key.
177
+
178
+ `surrogateescape`, because an environment value arrives from
179
+ `os.environ` with any undecodable byte held as a lone surrogate, and
180
+ a bare `.encode()` raises on those: the whole recording would go down
181
+ over one variable the shell happened to carry.
182
+
183
+ `replace` behind it, because `surrogateescape` round-trips only
184
+ U+DC80-U+DCFF: a LONE surrogate (U+D800, which `os.environ` cannot
185
+ produce but a captured value or a value re-read from JSON can)
186
+ raises there too, out of a module that documents that it never
187
+ raises. Spelled here as a code point and not as an escape, because a
188
+ docstring holding the character itself cannot be encoded by a reader
189
+ that walks this file -- which is this rule, biting its own module. U+FFFD is the right identity for it and not merely a safe
190
+ one -- Node's UTF-8 encoder writes exactly those bytes for the same
191
+ string, so the two languages that can hold a lone surrogate agree on
192
+ its digest; a Rust `String` cannot hold one at all.
193
+ """
194
+ if self.material is None:
195
+ return None
196
+ try:
197
+ raw = text.encode("utf-8", "surrogateescape")
198
+ except UnicodeEncodeError:
199
+ raw = text.encode("utf-8", "replace")
200
+ return hmac.new(self.material, raw, "sha256").hexdigest()[:16]
201
+
202
+ def mode_note(self) -> str | None:
203
+ """`key mode 0644 -- expected 0600` when the file is looser than it
204
+ was created, else None. A loose key is READ anyway and named on
205
+ `info`: refusing to record over the user's own file permissions
206
+ helps nobody (§3). A key from `from_hex` has no file and no mode.
207
+ """
208
+ if self.path.name != KEY_FILE:
209
+ return None
210
+ try:
211
+ mode = stat.S_IMODE(self.path.stat().st_mode)
212
+ except OSError:
213
+ return None
214
+ if mode == KEY_MODE:
215
+ return None
216
+ return f"key mode {mode:04o} -- expected 0600"
217
+
218
+
219
+ def _write_key(tmp: Path, material: bytes) -> str | None:
220
+ """All of `material` into a fresh `tmp`, fsynced and closed. The problem
221
+ sentence, or None when the file on disk is whole.
222
+
223
+ The write is a LOOP and its return value is checked: `os.write` is
224
+ allowed to write fewer bytes than it was given, and a 20-byte key that
225
+ memory believes is 32 is a store whose digests stop matching the day
226
+ another process reads the file instead of inheriting the material.
227
+ """
228
+ try:
229
+ fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, KEY_MODE)
230
+ except OSError as e:
231
+ return f"cannot create {KEY_FILE}: {e}"
232
+ try:
233
+ written = 0
234
+ while written < len(material):
235
+ step = os.write(fd, material[written:])
236
+ if not step:
237
+ return f"cannot write {KEY_FILE}: wrote {written} of "\
238
+ f"{len(material)} bytes"
239
+ written += step
240
+ os.fsync(fd)
241
+ except OSError as e:
242
+ return f"cannot write {KEY_FILE}: {e}"
243
+ finally:
244
+ try:
245
+ os.close(fd)
246
+ except OSError:
247
+ pass # the bytes are fsynced; a failing close is not a key error
248
+ return None
249
+
250
+
251
+ def _unlink(path: Path) -> None:
252
+ """Best effort, on every path out of `load_or_create`: a tmp left behind
253
+ is a 32-byte secret nobody will ever read again."""
254
+ try:
255
+ os.unlink(path)
256
+ except OSError:
257
+ pass
258
+
259
+
260
+ #: A leftover tmp's name, never `KEY_FILE` itself -- the dot before `*`
261
+ #: means the glob cannot match the key file, which has no `.tmp` suffix.
262
+ _TMP_GLOB = f"{KEY_FILE}.*.tmp"
263
+
264
+
265
+ def _pid_alive(pid: int) -> bool:
266
+ """`os.kill(pid, 0)` sends no signal, only asks whether `pid` is still
267
+ a process this box has. `ProcessLookupError` is the one "gone" answer;
268
+ everything else counts as alive, because it means liveness could not
269
+ be checked, not that it was checked and came back dead -- a sweep must
270
+ never unlink a tmp it could not actually prove dead. That "everything
271
+ else" is deliberately broad: `PermissionError` means the pid is real
272
+ but owned by someone else, and `OverflowError` is `os.kill` refusing a
273
+ pid outside the platform's signed-int range before it can even look
274
+ (a real case: a `.tmp` name is trusted only as digits, and digits can
275
+ spell a number no real pid ever is)."""
276
+ try:
277
+ os.kill(pid, 0)
278
+ except ProcessLookupError:
279
+ return False
280
+ except Exception:
281
+ return True
282
+ return True
283
+
284
+
285
+ def sweep_stale(root: Path) -> list[Path]:
286
+ """Unlink every `<root>/redaction.key.<pid>.tmp` whose writer is dead:
287
+ the one hazard `load_or_create`'s own `finally` cannot cover (R15) is a
288
+ process KILLED between `_write_key` finishing and that `finally`
289
+ running, which leaves a 32-byte secret half nobody will ever finish
290
+ writing. A name whose middle does not parse as a positive int, or
291
+ whose pid is still alive, is left untouched -- `os.kill` treats a
292
+ negative number as a process GROUP, not the pid the name encodes, so
293
+ zero and negative middles are refused the same as `abc` would be.
294
+ Never raises: a file this cannot unlink (permissions, a race) is
295
+ simply absent from the result.
296
+
297
+ Not called by any recorder -- a recorder deleting files at its own
298
+ startup is a different threat model than a `redact` pass that, by
299
+ design, visits the whole store once (C13); today only `redact` calls
300
+ this, and only once per invocation.
301
+ """
302
+ root = Path(root)
303
+ swept = []
304
+ for tmp in sorted(root.glob(_TMP_GLOB)):
305
+ middle = tmp.name.removeprefix(f"{KEY_FILE}.").removesuffix(".tmp")
306
+ try:
307
+ pid = int(middle)
308
+ except ValueError:
309
+ continue
310
+ if pid <= 0:
311
+ continue
312
+ if _pid_alive(pid):
313
+ continue
314
+ _unlink(tmp)
315
+ if not tmp.exists():
316
+ swept.append(tmp)
317
+ return swept