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,304 @@
1
+ """`sensorium redact` -- rule v1 applied to traces that are already on disk.
2
+
3
+ Parts A and B put the rule at the three recorders' writers, so nothing NEW
4
+ reaches the store in plaintext. Everything already there still is. One pass
5
+ of this command over one trace does what a recorder would have done to it
6
+ at birth (§7): the environment through the NAME rule, with the digests
7
+ under the store's key and `env_hash` recomputed under the trace's own
8
+ language formula; every captured value the writers reach -- `args` and
9
+ `deltas` bindings, map keys, a RETURN under its callee's last qualname
10
+ segment, exception messages, `unwind_exc`, every `output` row, every
11
+ `children` element; the `redaction` stamp rewritten with `by: "retrofit"`
12
+ and `mode: "on"`; and the file left at 0600. It decides nothing itself:
13
+ `redact_store.plan` is the whole judgement and `redact_store.apply` the
14
+ only writer (C14). This module is the part a person and a script meet --
15
+ the lines, the exits, the sweep, the directory.
16
+
17
+ **The knobs are the CALLER's** (C4). `SENSORIUM_REDACT_NAMES` and
18
+ `SENSORIUM_REDACT_ALLOW` are read from this command's own environment,
19
+ because the shell that made the recording has ended and the person asking
20
+ is the one in front of the store; they are stamped, so the trace records
21
+ which pass took what. `SENSORIUM_NO_REDACT` is IGNORED -- `plan` forces it
22
+ off at the one point the knobs enter, and the reason it is forced there
23
+ rather than here is that the judgement must be incapable of obeying it:
24
+ running this command IS the decision (§7), and a stale export in somebody's
25
+ shell profile must not be able to turn a retrofit into a no-op that still
26
+ prints lines.
27
+
28
+ **`--dry-run` is `plan` alone, and its stdout is byte-identical to the real
29
+ run's** (C10) -- the same per-trace lines, the same summary, in the same
30
+ order -- with `dry run: no trace was changed` on STDERR. The line says
31
+ TRACE and not "nothing" on purpose (R19): a dry run is not a read-only
32
+ call, and the two corners below name what it does leave. That is not a
33
+ courtesy: E16's H4 reads the two stdouts and DIFFS them, so a dry run that
34
+ printed anything of its own would turn a measurement into a judgement about
35
+ wording. Both modes run the same loop with a single branch around `apply`,
36
+ so the two cannot drift. Exit codes are the real run's: 0 if anything
37
+ changed or would.
38
+
39
+ Identical for the SAME store in the SAME state -- H4's case, since it
40
+ copies a store once and runs both passes over it. Two corners, named rather
41
+ than left to be discovered: on a store with no `redaction.key` yet the dry
42
+ run reads `Key.load` and the real run mints one, so a C5 refusal naming the
43
+ store's key says `none` in the first and a key id in the second (every
44
+ other line carries names, counts and modes, which no key decides); and
45
+ across two CONSECUTIVE invocations the sweep is real in both modes (P3), so
46
+ a dry run consumes the litter and the run after it counts none.
47
+
48
+ **What a dry run DOES leave** (R19), so the stderr line is read for what it
49
+ says and not for more: no TRACE is changed -- not a byte, not a mode -- and
50
+ no `redaction.key` is minted (R1); but the call is logged to
51
+ `invocations.jsonl` like every other, the sweep is real (P3, above), and a
52
+ store that did not exist is CREATED as a side effect of looking for its
53
+ traces, `paths.traces_dir()` making the root and `traces/` at 0700. A dry
54
+ run over an absent store therefore leaves an empty store behind and says
55
+ `redacted 0 of 0 traces`.
56
+
57
+ **Modes** (C11): a rewritten trace is 0600 by creation, and a trace that
58
+ needs no rewrite but sits at another mode is tightened in place and counts
59
+ as changed -- a 0644 trace is readable by everyone on the box whatever its
60
+ contents now say. `--all` also tightens `traces/` to 0700 and says so on
61
+ the summary, because a loose directory hands over every file in it; a
62
+ single-run pass never touches the directory.
63
+
64
+ **The lines** (C12) are pinned to the character: `corpus/redact_retrofit`
65
+ and E16 part C parse them, and an instrument that reads nothing reports a
66
+ green run over an unmeasured claim. One flushed line per trace as it is
67
+ finished, so a `--all` pass over a real store is watchable rather than
68
+ silent for a minute; then the summary, which names the spools as out of
69
+ reach instead of omitting them, since a count that quietly excluded them
70
+ would read as a claim about the whole disk.
71
+
72
+ **The stale-key sweep** (C13) runs once per invocation, before any trace,
73
+ in BOTH modes (P3): a `redaction.key.<pid>.tmp` left by a killed
74
+ `load_or_create` is 32 bytes of secret and not a trace, so §7's "change
75
+ nothing" does not cover it -- and skipping it under `--dry-run` would make
76
+ the two stdouts differ exactly when a reader is comparing them.
77
+
78
+ `nothing to redact` is P5's line, and it belongs to a trace that is NOT
79
+ REWRITTEN: one already `mode: "on"` whose pass finds nothing, even when the
80
+ caller's knobs differ from the recorded ones, because a stamp is a statement
81
+ about what was taken and rewriting one over an unchanged trace would date a
82
+ file to say nothing new. A pre-rule or `mode: "off"` trace whose pass finds
83
+ nothing is the other case and NOT this line: it still gains its stamp (P5),
84
+ so the file changed, the summary counts it redacted and the call exits 0 --
85
+ it prints the counted form with zeros, `env 0 redacted (); values 0; <mode>`
86
+ (R19). The line, the summary and the exit then say the same thing, which is
87
+ the whole of what a reader can check without opening the trace.
88
+ """
89
+ import os
90
+ import sqlite3
91
+ import stat
92
+ import sys
93
+ from collections.abc import Sequence
94
+ from dataclasses import replace
95
+ from pathlib import Path
96
+
97
+ from sensorium import paths, redact, redact_store
98
+ from sensorium.exit import ANSWERED, BAD_CALL, NEGATIVE
99
+ from sensorium.query.refocus_world import _capped
100
+ from sensorium.redact_key import Key, sweep_stale
101
+ from sensorium.redact_store import TIGHT, Plan
102
+
103
+ #: What `--all` leaves `traces/` at (C11). The files' own 0600 is
104
+ #: `redact_store.TIGHT`; a directory needs its execute bit to be entered.
105
+ DIR_TIGHT = 0o700
106
+
107
+ #: Named on every summary rather than silently left out: a count of
108
+ #: traces that quietly excluded the spools would read as a claim
109
+ #: about the whole disk (C20, §11).
110
+ SPOOLS = ("; spools under target/ and the TypeScript spool dirs are "
111
+ "not reached")
112
+
113
+
114
+ def add_parser(sub) -> None:
115
+ p = sub.add_parser(
116
+ "redact", help="apply rule v1 to traces already in the store",
117
+ epilog="exit: 0 something changed (or would), 1 nothing to do, "
118
+ "2 a refusal (the others continue)")
119
+ p.add_argument("run", nargs="?", default=None)
120
+ p.add_argument("--all", action="store_true",
121
+ help="every trace in the store")
122
+ p.add_argument("--dry-run", action="store_true",
123
+ help="print what would change; change nothing")
124
+ # The parser itself, so `run` can refuse a call argparse cannot
125
+ # express: `run` and `--all` are exclusive AND one is required, which
126
+ # is two rules over a positional and a flag, not one group.
127
+ p.set_defaults(func=run, parser=p)
128
+
129
+
130
+ def capped(names: Sequence[str]) -> str:
131
+ """`info`'s cap -- eight names, then a count of the rest. Imported and
132
+ not re-spelled: two commands printing the same list under two caps is
133
+ how a reader learns to distrust both."""
134
+ return _capped(list(names))
135
+
136
+
137
+ def _mode_clause(p: Plan) -> str:
138
+ """`mode 600`, or the arrow that says what it was. Present on every
139
+ line form that names a trace's contents (C12), because the mode is
140
+ half of what a retrofit changes and the half a reader cannot see by
141
+ querying the trace."""
142
+ if not p.tightens:
143
+ return f"mode {TIGHT:o}"
144
+ return f"mode {p.mode_before:o} -> {TIGHT:o}"
145
+
146
+
147
+ def line_for(p: Plan) -> str:
148
+ """One trace's whole outcome, in C12's words."""
149
+ if p.refused:
150
+ return f"run {p.run}: REFUSED: {p.refused}"
151
+ if p.skipped:
152
+ return f"run {p.run}: {p.skipped}, skipped"
153
+ if p.env_names or p.values or p.rewrites:
154
+ # `rewrites` and not the two counters alone (R19): a pre-rule or
155
+ # `mode: "off"` trace with no firing name and no firing value is
156
+ # still STAMPED (P5), so the file changes, the summary counts it
157
+ # redacted and the call exits 0. Printing `nothing to redact` over
158
+ # that would make the line the one place in the pass that says
159
+ # nothing happened -- the degenerate `env 0 redacted (); values 0`
160
+ # is C12's own spelling with the numbers it actually took.
161
+ return (f"run {p.run}: env {len(p.env_names)} redacted "
162
+ f"({capped(p.env_names)}); values {p.values}; "
163
+ f"{_mode_clause(p)}")
164
+ return f"run {p.run}: nothing to redact; {_mode_clause(p)}"
165
+
166
+
167
+ def summary(plans: list[Plan], swept: int,
168
+ dir_mode: tuple[int, int] | None) -> str:
169
+ """The one line that accounts for every trace the pass reached.
170
+
171
+ A plan that was REFUSED after its rewrite failed carries both the rows
172
+ it wanted to write and the sentence saying it could not, so `redacted`
173
+ is counted over the plans that were neither refused nor skipped: a
174
+ trace whose rewrite raised was not redacted, and counting it twice --
175
+ once as done, once as refused -- would leave the four numbers unable
176
+ to add up to the traces walked.
177
+ """
178
+ skipped = sum(1 for p in plans if p.skipped)
179
+ refused = sum(1 for p in plans if p.refused)
180
+ done = sum(1 for p in plans
181
+ if not p.refused and not p.skipped and p.rewrites)
182
+ clean = len(plans) - done - skipped - refused
183
+ line = (f"redacted {done} of {len(plans)} traces ({clean} already clean, "
184
+ f"{skipped} skipped, {refused} refused){SPOOLS}")
185
+ if swept:
186
+ line += f"; swept {swept} stale key tmp file(s)"
187
+ if dir_mode:
188
+ line += f"; traces/ mode {dir_mode[0]:o} -> {dir_mode[1]:o}"
189
+ return line
190
+
191
+
192
+ def _dir_mode(dry: bool) -> tuple[int, int] | None:
193
+ """`traces/`'s mode change, applied unless this is a dry run, and
194
+ reported either way (C11, P3). `--all` only: a pass over one trace was
195
+ not asked about the store.
196
+
197
+ A directory whose mode cannot be read or set is a note on stderr and no
198
+ clause at all (R10): the traces themselves are already done and their
199
+ lines already printed, so raising here would end a pass that succeeded
200
+ -- and printing `traces/ mode 755 -> 700` for a `chmod` that failed
201
+ would be a claim about a mode nobody set.
202
+ """
203
+ try:
204
+ d = paths.traces_dir()
205
+ before = stat.S_IMODE(d.stat().st_mode)
206
+ if before == DIR_TIGHT:
207
+ return None
208
+ if not dry:
209
+ os.chmod(d, DIR_TIGHT)
210
+ except OSError as e:
211
+ print(f"traces/ mode: {e}", file=sys.stderr)
212
+ return None
213
+ return (before, DIR_TIGHT)
214
+
215
+
216
+ def _targets(args) -> list[Path]:
217
+ """The traces this call names, in sorted run-id order (C12).
218
+
219
+ `*.db` and nothing else: the converters' and the ingest's in-flight
220
+ files are `.<run>.db.tmp` and this command's own workspace is
221
+ `.<run>.db.redact.<pid>.tmp`, both dotfiles, both walked past (C8).
222
+ A bad reference is `paths`' own error and reaches `cli.main`, which
223
+ ends the call at exit 2 before any line is printed.
224
+ """
225
+ if args.all:
226
+ return sorted(paths.traces_dir().glob("*.db"))
227
+ return [paths.find_trace(args.run)]
228
+
229
+
230
+ def run(args) -> int:
231
+ if args.run and args.all:
232
+ args.parser.error("give a run reference or --all, not both")
233
+ if not args.run and not args.all:
234
+ args.parser.error("give a run reference or --all")
235
+ root = paths.trace_root()
236
+ # A store that cannot key records unkeyed digests (§3) -- but a DRY
237
+ # run must leave the store exactly as it found it, and minting
238
+ # `redaction.key` is a write. The lines are identical either way:
239
+ # what they carry is names, counts and modes, none of which a key
240
+ # decides.
241
+ key = Key.load(root) if args.dry_run else Key.load_or_create(root)
242
+ knobs = redact.Knobs.from_environ(os.environ)
243
+ swept = len(sweep_stale(root))
244
+ plans = []
245
+ for path in _targets(args):
246
+ try:
247
+ p = redact_store.plan(path, key, knobs)
248
+ except Exception as e:
249
+ # `plan` names every condition it FORESEES as a sentence on
250
+ # the Plan, but sqlite reads pages lazily: a corrupt row, a
251
+ # payload that is not JSON, a file another process moved
252
+ # under it can all surface from inside the walk. C9 says the
253
+ # others continue, so an unforeseen one is a refusal too
254
+ # rather than a traceback that ends the pass (R10).
255
+ #
256
+ # `Exception` and not a tuple (R19): a `meta.env` holding a
257
+ # non-string value raises `AttributeError` out of
258
+ # `key.digest`, and a previous stamp whose `env` is a scalar
259
+ # raises `TypeError` out of `dict()` -- neither is an OSError,
260
+ # a sqlite error or a ValueError, so a tuple of the three let
261
+ # ONE odd trace end an `--all` pass over 273 of them. The
262
+ # judgement is pure, so anything it raises is a statement
263
+ # about that trace. `KeyboardInterrupt` is a `BaseException`
264
+ # and still ends the pass, which is what a person asking it to
265
+ # stop means.
266
+ p = Plan(path, Path(path).stem, "",
267
+ refused=f"cannot judge: {e}")
268
+ else:
269
+ if not args.dry_run:
270
+ try:
271
+ redact_store.apply(p)
272
+ except redact_store.SidecarLeft as e:
273
+ # The rewrite LANDED (R19): the rename is past, the
274
+ # trace on disk is the redacted one, and what failed
275
+ # was removing the displaced inode's log afterwards.
276
+ # Calling that "the rewrite failed" would refuse a
277
+ # trace that was redacted; the note says what is
278
+ # actually wrong, on STDERR so the two stdouts stay
279
+ # the same bytes (C10), and the trace counts as done.
280
+ print(f"run {p.run}: {e}", file=sys.stderr)
281
+ except (OSError, sqlite3.Error) as e:
282
+ # The original is untouched (C7), so this is a
283
+ # refusal like any other: named on its own line, the
284
+ # rest of the pass continuing, exit 2 at the end.
285
+ p = replace(p, refused=f"the rewrite failed: {e}")
286
+ plans.append(p)
287
+ print(line_for(p), flush=True)
288
+ dir_mode = _dir_mode(args.dry_run) if args.all else None
289
+ print(summary(plans, swept, dir_mode))
290
+ if args.dry_run:
291
+ # On STDERR, so the two stdouts are the same bytes (C10). "no trace
292
+ # was changed" and not "nothing was written" (R19): the call is
293
+ # logged, the sweep is real, and an absent store was created by the
294
+ # walk that looked for its traces -- the docstring lists all three.
295
+ print("dry run: no trace was changed", file=sys.stderr)
296
+ if any(p.refused for p in plans):
297
+ return BAD_CALL
298
+ # The directory joins the predicate (R11): a store of settled traces
299
+ # whose `traces/` was 0755 HAS something to change, and the epilog
300
+ # promises 0 when something changed or would. Exit 1 there would tell
301
+ # a script the pass was a no-op on the run it just tightened.
302
+ if dir_mode or any(p.changes for p in plans):
303
+ return ANSWERED
304
+ return NEGATIVE