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,433 @@
1
+ """Rule v1 applied to a CAPTURE: the two operations of §2.3, at every text
2
+ a recorder stores.
3
+
4
+ `redact.py` answers "is this a secret-shaped NAME" and `redact_content.py`
5
+ answers "does this text hold a secret-shaped SPAN". Neither knows what a
6
+ payload looks like. This module is the one place that does: it takes the
7
+ capture dialect (`{"k": "str", "v": …}`, a `seq`/`map` sample, an `exc`
8
+ object, an output chunk) and applies whichever operation the rule calls for.
9
+
10
+ TWO OPERATIONS, NEVER BOTH
11
+ --------------------------
12
+ A NAME hit takes the whole capture (B4): the text becomes `<redacted>` and a
13
+ `redacted` object carries the digest of what was taken, so `diff`, `refocus`
14
+ and `watch` can still say "this is the same value" without printing it. A
15
+ CONTENT hit replaces only the matched span and keeps the sentence around it
16
+ (`postgres://u:<redacted>@h/db`), and carries no digest -- a partial cannot
17
+ honestly commit to the whole. The two never land on one capture: a value
18
+ already taken by name has no text left to scan, and the content rule refuses
19
+ anything already carrying `redacted` (§2.3).
20
+
21
+ THE STATE
22
+ ---------
23
+ One module-level `State` (B6). `boot.run_target` installs the store key and
24
+ the knobs it read before the target resolved; a process that never installs
25
+ -- an in-process recording, the TypeScript ingest -- gets the default, which
26
+ is the rule ON and UNKEYED. That default is deliberate: "no key" must mean
27
+ "redacted, with no digest to compare", never "plaintext".
28
+
29
+ THE COUNT
30
+ ---------
31
+ Nothing here counts. The transforms are pure: they take a capture and give
32
+ one back. `count(payload)` and `count_capture(capture)` READ a finished
33
+ payload and say how many values it withholds, and the recorder adds that at
34
+ each WRITE -- `tracer` at every `add_event`, the unwind exception it hands
35
+ `close_frame`, `boot` at the uncaught record, the tee at a chunk it stores.
36
+ `boot` publishes the run's delta as `redaction.values` (B3).
37
+
38
+ That shape is the whole of the count's honesty. The rule runs over values
39
+ the trace does not keep (`_on_line` re-captures every local at every line
40
+ and stores only the ones that CHANGED), and building a capture inside a
41
+ capture runs the observed program's own `__repr__`, which may itself print
42
+ -- reaching the tee, and the count -- from inside the window. A counter
43
+ bumped as the rule fires had to be rolled back for the dropped ones, and an
44
+ absolute roll-back erases whatever else landed in that window. Counting what
45
+ was WRITTEN needs no window: `values` is a function of the trace, which is
46
+ what B3 says it is and what the two converters independently compute.
47
+
48
+ This module imports `redact` and `redact_content` only -- nothing from
49
+ `record` or `query` -- and never raises. Like `capture.py`, everything here
50
+ runs from inside a `sys.monitoring` callback, so it touches nothing but
51
+ plain dicts, plain strings and the compiled patterns: every capture it is
52
+ handed has already been normalised (`capture.plain_str`, `plain_num`), and
53
+ no value in one can run the observed program's code.
54
+ """
55
+ from dataclasses import dataclass
56
+ from pathlib import Path
57
+
58
+ from sensorium import redact
59
+ from sensorium.redact_content import content
60
+
61
+ #: Which rule took a value. The `redacted` object is exactly `{"by", "digest"}`
62
+ #: and nothing else, in every language that writes one (§4.2).
63
+ BY_NAME = "name"
64
+ BY_CONTENT = "content"
65
+
66
+ #: Where each capture kind keeps the value a NAME hit takes: the field the
67
+ #: marker replaces, and the field the digest is over (`num` through `repr`,
68
+ #: see `_text_of`).
69
+ _MARKER_FIELD = {"str": "v", "num": "v", "dbg": "v", "obj": "repr"}
70
+
71
+ #: Where the CONTENT rule reads. `num` is absent on purpose: a number holds
72
+ #: no text for a pattern to match, and scanning `repr(v)` would be scanning
73
+ #: a rendering the trace does not hold.
74
+ _SCAN_FIELD = {"str": "v", "dbg": "v", "obj": "repr"}
75
+
76
+ #: The kinds that withhold nothing, so the name rule leaves them alone: a
77
+ #: `None`, a truth value, and a value the object refused to hand over at all.
78
+ #: Redacting one would cost a reader a fact and hide no secret.
79
+ _WITHHOLDS_NOTHING = frozenset({"none", "bool", "unread"})
80
+
81
+ #: The same judgement over a TEXT, for the one kind that has no type of its
82
+ #: own (ruling R19). `undefined` and `null` are how node's inspector spells a
83
+ #: function that returned nothing; `()` is how Rust's `Debug` does (R17), and
84
+ #: this module reads both dialects. Whole texts, never a shape: `NaN` is a
85
+ #: value the program had, and a text that merely contains one of these is
86
+ #: taken like any other.
87
+ _DBG_WITHHOLDS_NOTHING = frozenset({"undefined", "null", "()"})
88
+
89
+ #: What a redacted container keeps (B4). Its size and its address are facts
90
+ #: about the program, not about the value; the sample is the value.
91
+ _CONTAINER_KEEPS = frozenset({"k", "type", "len", "oid"})
92
+
93
+ #: Every capture kind this module has a rule for. `record/capture.py`
94
+ #: produces all of these but `dbg`, which is the Rust and TypeScript
95
+ #: recorders' kind, and `tests/test_redact_values.py` pins that containment
96
+ #: against `capture.py` itself -- a kind added there without a rule here
97
+ #: would otherwise be stored as typed under a name that fires.
98
+ KINDS = frozenset(_MARKER_FIELD) | {"seq", "map"} | _WITHHOLDS_NOTHING
99
+
100
+ #: Where a payload keeps a capture, and where it keeps a map of them. Every
101
+ #: payload this recorder writes is built from these five keys.
102
+ _PAYLOAD_CAPTURES = ("value", "exc", "thrown")
103
+ _PAYLOAD_MAPS = ("args", "deltas")
104
+
105
+
106
+ @dataclass(frozen=True)
107
+ class State:
108
+ """The key the digests are taken under, and the knobs the recording was
109
+ made under -- read once, at the start of a run, and never re-read."""
110
+ key: redact.Key
111
+ knobs: redact.Knobs
112
+
113
+
114
+ #: The never-installed state: rule ON, no key, and a `problem` that says why
115
+ #: rather than pretending a key was looked for.
116
+ _UNINSTALLED = State(redact.Key(Path("unset"), None, "not installed"),
117
+ redact.Knobs(False, frozenset(), frozenset()))
118
+
119
+ _state = _UNINSTALLED
120
+
121
+ #: Read by `boot` as a before/after delta, exactly as `capture_stats` is.
122
+ #: Added to by the WRITE sites, from `count`/`count_capture` below -- never
123
+ #: by the transforms in this module.
124
+ stats = {"values": 0}
125
+
126
+
127
+ def install(key: redact.Key, knobs: redact.Knobs) -> None:
128
+ global _state
129
+ _state = State(key, knobs)
130
+
131
+
132
+ def reset() -> None:
133
+ global _state
134
+ _state = _UNINSTALLED
135
+
136
+
137
+ def state() -> State:
138
+ return _state
139
+
140
+
141
+ def last_segment(qualname: str) -> str:
142
+ """The name a returned value was asked for by (B7): `Cls.get_api_key` ->
143
+ `get_api_key`, `outer.<locals>.inner` -> `inner`.
144
+
145
+ `<lambda>`, `<module>` and `<genexpr>` come through unchanged and fire on
146
+ nothing -- their segments are words in no set -- which is the answer, not
147
+ a special case.
148
+ """
149
+ return qualname.rpartition(".")[2] or qualname
150
+
151
+
152
+ def _text_of(capture: dict) -> str | None:
153
+ """The text this capture holds, or None where it holds none.
154
+
155
+ A container's sample is not text: it is other captures, each with its
156
+ own. That is why a redacted container has `digest: null` rather than a
157
+ digest of some rendering the trace never held.
158
+ """
159
+ kind = capture.get("k")
160
+ field = _MARKER_FIELD.get(kind)
161
+ if field is None:
162
+ return None
163
+ text = capture.get(field)
164
+ if kind == "num":
165
+ # A number's text is its `repr`, computed here rather than stored:
166
+ # the capture holds the number itself, and `1234` and `"1234"` must
167
+ # not share a digest.
168
+ return None if text is None else repr(text)
169
+ return text if isinstance(text, str) else None
170
+
171
+
172
+ def digest_of(capture: dict) -> str | None:
173
+ """`HMAC(key, the capture's own text)`, or None with no key and None for
174
+ a kind that stores no text.
175
+
176
+ Over the CLIPPED text, because that is what the trace would otherwise
177
+ have held (§2.3): a digest of the 300 characters the program had could
178
+ never be checked against a trace that only ever stores 200.
179
+ """
180
+ text = _text_of(capture)
181
+ return None if text is None else _state.key.digest(text)
182
+
183
+
184
+ def named(name: str, capture: dict) -> dict:
185
+ """`capture` under the name it was bound to: taken whole if the NAME rule
186
+ fires, else offered to the content rule.
187
+
188
+ The argument is never mutated, and an untouched capture is returned as it
189
+ arrived -- the recorder compares captures with `!=` to find a line's
190
+ deltas, and a copy that differed in nothing would still be a copy.
191
+ """
192
+ st = _state
193
+ if st.knobs.off or "redacted" in capture:
194
+ return capture
195
+ if not redact.fires(name, st.knobs):
196
+ return value(capture)
197
+ kind = capture.get("k")
198
+ if kind in _WITHHOLDS_NOTHING:
199
+ return capture
200
+ if kind == "dbg" and capture.get("v") in _DBG_WITHHOLDS_NOTHING:
201
+ return capture
202
+ return _taken(capture, kind)
203
+
204
+
205
+ def named_return(qualname: str, capture: dict) -> dict:
206
+ """A RETURN value, under the last segment of the callee's qualname."""
207
+ return named(last_segment(qualname), capture)
208
+
209
+
210
+ def _taken(capture: dict, kind: str) -> dict:
211
+ """B4's per-kind table: the whole value, gone, and a digest of it."""
212
+ digest = digest_of(capture)
213
+ if kind in ("seq", "map"):
214
+ out = {n: v for n, v in capture.items() if n in _CONTAINER_KEEPS}
215
+ elif kind in _MARKER_FIELD:
216
+ out = dict(capture)
217
+ out.pop("trunc", None) # nothing was clipped: it was taken
218
+ if kind == "obj":
219
+ # The repr is the text the digest covers. Fields are more of
220
+ # the same value: a name hit takes the object, so a secret that
221
+ # lived only in a field must not survive beside the marker.
222
+ out.pop("fields", None)
223
+ out.pop("fields_trunc", None)
224
+ out[_MARKER_FIELD[kind]] = redact.REDACTED
225
+ if kind == "dbg":
226
+ # Always present on a `dbg` capture, so it is written FALSE
227
+ # rather than dropped: a reader that met it missing would have
228
+ # to guess whether the formatter had been cut short.
229
+ out["trunc"] = False
230
+ else:
231
+ # A kind this rule has never heard of, under a name that fires. The
232
+ # only honest answer to "I do not know this shape" is to withhold
233
+ # the whole of it: keeping it would store a secret the rule was
234
+ # asked to take, and this control's failure direction has to be a
235
+ # lost fact, never a kept secret. The kind itself stays -- a reader
236
+ # has to be able to see WHAT was withheld -- and there is no digest,
237
+ # because nothing here knows which field held the value.
238
+ out = {n: v for n, v in capture.items() if n == "k"}
239
+ digest = None
240
+ out["redacted"] = {"by": BY_NAME, "digest": digest}
241
+ return out
242
+
243
+
244
+ def value(capture: dict) -> dict:
245
+ """`capture` with the CONTENT rule run over every text it holds --
246
+ its own, and recursively those of a `seq`/`map` sample's captures.
247
+
248
+ A capture already carrying `redacted` is returned as is: it was taken by
249
+ name, so there is no text left to scan, and re-marking it would claim a
250
+ second operation that never happened.
251
+ """
252
+ if _state.knobs.off or "redacted" in capture:
253
+ return capture
254
+ kind = capture.get("k")
255
+ if kind == "obj":
256
+ return _object(capture)
257
+ field = _SCAN_FIELD.get(kind)
258
+ if field is not None:
259
+ return _scanned(capture, field)
260
+ if kind == "seq":
261
+ return _sampled(capture, _item)
262
+ if kind == "map":
263
+ return _sampled(capture, _pair)
264
+ # A kind with no text this scanner knows, `none`/`bool`/`unread`
265
+ # included. Pass-through is right HERE and wrong in `named`: the content
266
+ # rule replaces a span it FOUND, and it found nothing; the name rule was
267
+ # told the whole value is a secret.
268
+ return capture
269
+
270
+
271
+ def _object(capture: dict) -> dict:
272
+ """An object's repr, then each field under that field's own name.
273
+
274
+ A field is a value held under a name, the same way a map entry is: a
275
+ field called `api_key` is taken whole, and every other field is offered
276
+ to the content rule. The object's own repr is still scanned. A name hit
277
+ on the object itself never reaches here (`named` takes it first and
278
+ drops `fields`).
279
+ """
280
+ scanned = _scanned(capture, "repr")
281
+ fields = scanned.get("fields")
282
+ if not isinstance(fields, dict):
283
+ return scanned
284
+ after = {}
285
+ changed = False
286
+ for name, child in fields.items():
287
+ if isinstance(name, str) and isinstance(child, dict):
288
+ new = named(name, child)
289
+ elif isinstance(child, dict):
290
+ new = value(child)
291
+ else:
292
+ new = child
293
+ after[name] = new
294
+ if new is not child:
295
+ changed = True
296
+ if not changed:
297
+ return scanned
298
+ out = dict(scanned)
299
+ out["fields"] = after
300
+ return out
301
+
302
+
303
+ def _scanned(capture: dict, field: str) -> dict:
304
+ text = capture.get(field)
305
+ if not isinstance(text, str):
306
+ return capture
307
+ after, hit = content(text)
308
+ if not hit:
309
+ return capture
310
+ out = dict(capture)
311
+ out[field] = after
312
+ # `trunc` stays: the text WAS clipped, and a span inside it was replaced.
313
+ out["redacted"] = {"by": BY_CONTENT, "digest": None}
314
+ return out
315
+
316
+
317
+ def _sampled(capture: dict, through) -> dict:
318
+ """The container, with `through` applied to each sampled entry.
319
+
320
+ A depth-capped or unreadable capture has no `sample` at all (never an
321
+ empty one), so this is a read with `.get`, and a container whose entries
322
+ all came back untouched is returned untouched itself.
323
+ """
324
+ sample = capture.get("sample")
325
+ if not isinstance(sample, list):
326
+ return capture
327
+ after = [through(entry) for entry in sample]
328
+ if all(a is b for a, b in zip(after, sample)):
329
+ return capture
330
+ out = dict(capture)
331
+ out["sample"] = after
332
+ return out
333
+
334
+
335
+ def _item(entry):
336
+ return value(entry) if isinstance(entry, dict) else entry
337
+
338
+
339
+ def _pair(entry):
340
+ """One `map` sample pair. B8: a value held under a firing KEY is a secret
341
+ held under a name, exactly as a local is -- a header dict's
342
+ `authorization` entry is the case this exists for. The key itself is a
343
+ name, not a secret, so only the content rule reaches it.
344
+ """
345
+ if not isinstance(entry, list) or len(entry) != 2:
346
+ return entry
347
+ key_cap, value_cap = entry
348
+ if not isinstance(key_cap, dict) or not isinstance(value_cap, dict):
349
+ return entry
350
+ name = key_cap.get("v") if key_cap.get("k") == "str" else None
351
+ after_key = value(key_cap)
352
+ after_value = (named(name, value_cap) if isinstance(name, str)
353
+ else value(value_cap))
354
+ if after_key is key_cap and after_value is value_cap:
355
+ return entry
356
+ return [after_key, after_value]
357
+
358
+
359
+ def exc(e: dict) -> dict:
360
+ """One captured exception, with the content rule over its message.
361
+
362
+ A message is a sentence the program wrote, not a value with an identity,
363
+ so a hit is marked on the `exc` object itself and carries no digest --
364
+ the same span operation, at the one text the format holds outside a
365
+ capture. A message that could not be READ is left alone: there is no
366
+ text to run the rule over, and there is nothing to withhold.
367
+ """
368
+ if _state.knobs.off or "redacted" in e:
369
+ return e
370
+ return _scanned(e, "msg")
371
+
372
+
373
+ def text(chunk: str) -> tuple[str, bool]:
374
+ """One output chunk, as the program wrote it, with the content rule over
375
+ it -- and whether anything CHANGED.
376
+
377
+ The pair is `redact_content.content`'s own shape, and it is what lets the
378
+ tee count a chunk it stores without comparing two strings it has already
379
+ compared inside the rule.
380
+
381
+ One `write()` at a time, which is the boundary the tee has: a secret
382
+ split across two writes is not seen. A known limit of this rule, not an
383
+ accident of it -- the tee holds no state between writes, and one that
384
+ did would be a buffer of the program's output living in the instrument.
385
+ """
386
+ if _state.knobs.off or not isinstance(chunk, str):
387
+ return chunk, False
388
+ return content(chunk)
389
+
390
+
391
+ def count_capture(capture) -> int:
392
+ """How many values one capture withholds: itself if it carries a
393
+ `redacted` object, plus however many nested captures do.
394
+
395
+ A capture taken by NAME has no sample and no fields left, so that arm
396
+ returns 1 and stops. A content hit on an object's repr still has
397
+ `fields` beside it, and those are counted too: the repr and a secret
398
+ field are two values withheld, not one. A `map` pair is a two-element
399
+ list and both halves are asked.
400
+ """
401
+ if not isinstance(capture, dict):
402
+ return 0
403
+ red = capture.get("redacted")
404
+ if isinstance(red, dict) and red.get("by") == "name":
405
+ return 1
406
+ n = 1 if "redacted" in capture else 0
407
+ sample = capture.get("sample")
408
+ if isinstance(sample, list):
409
+ n += sum(count_capture(x) for entry in sample
410
+ for x in (entry if isinstance(entry, list) else (entry,)))
411
+ fields = capture.get("fields")
412
+ if isinstance(fields, dict):
413
+ n += sum(count_capture(c) for c in fields.values())
414
+ return n
415
+
416
+
417
+ def count(payload) -> int:
418
+ """How many values a finished payload withholds -- the number the writer
419
+ adds to `stats` as it stores that payload.
420
+
421
+ Reads the payload's own vocabulary (`args`, `deltas`, `value`, `exc`,
422
+ `thrown`) rather than walking it blind: a payload key that is not a
423
+ capture (`unbound`, `unread`, `caller`, `chain`) must never be counted,
424
+ and a key that becomes one has to be added HERE, deliberately.
425
+ """
426
+ if not isinstance(payload, dict):
427
+ return 0
428
+ total = sum(count_capture(payload.get(k)) for k in _PAYLOAD_CAPTURES)
429
+ for name in _PAYLOAD_MAPS:
430
+ group = payload.get(name)
431
+ if isinstance(group, dict):
432
+ total += sum(count_capture(c) for c in group.values())
433
+ return total
File without changes