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,227 @@
1
+ // Per-run caps. 0 is unlimited. The driver resolves the command, the
2
+ // environment and the store config and exports integers; this module only
3
+ // reads those numbers. An unset variable is the built-in default.
4
+ //
5
+ // The first `maxCalls` activations of each function are stored. Further
6
+ // activations of that function, and every activation once the event or byte
7
+ // estimate is hit, are counted and not stored. A frame that is not stored is
8
+ // still pushed, so a child sees `parent.elided` and the whole subtree is
9
+ // counted rather than written under a parent id the spool never recorded.
10
+ // A throw materializes the raising frame and each elided ancestor,
11
+ // outermost first, as a skeleton CALL (no arguments). Each one spends an
12
+ // elided count, which is why a failure still answers.
13
+
14
+ /** @typedef {{elided: number, file: number, c: number, kept: number, reason: string}} Slot */
15
+ /** @typedef {{elided?: boolean, file?: number, c?: number, id?: number}} CapFrame */
16
+
17
+ export const DEFAULT_MAX_EVENTS = 100000;
18
+ export const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
19
+ export const DEFAULT_MAX_CALLS = 1024;
20
+
21
+ /** Kinds the converter turns into event rows. The cap counts those. */
22
+ const EVENT_KINDS = new Set(['CALL', 'RETURN', 'LINE', 'YIELD', 'RESUME', 'RAISE', 'HANDLED']);
23
+
24
+ /**
25
+ * @param {string|undefined} text
26
+ * @param {number} fallback
27
+ * @returns {number}
28
+ */
29
+ function readCap(text, fallback) {
30
+ if (text === undefined || text === null || String(text).trim() === '') return fallback;
31
+ const n = Number(String(text).trim());
32
+ if (!Number.isFinite(n) || n < 0) return fallback;
33
+ return Math.trunc(n);
34
+ }
35
+
36
+ /**
37
+ * @param {NodeJS.ProcessEnv} [env]
38
+ * @returns {{maxEvents: number, maxBytes: number, maxCalls: number}}
39
+ */
40
+ export function limitsFromEnv(env = process.env) {
41
+ return {
42
+ maxEvents: readCap(env.SENSORIUM_MAX_EVENTS, DEFAULT_MAX_EVENTS),
43
+ maxBytes: readCap(env.SENSORIUM_MAX_BYTES, DEFAULT_MAX_BYTES),
44
+ maxCalls: readCap(env.SENSORIUM_MAX_CALLS, DEFAULT_MAX_CALLS),
45
+ };
46
+ }
47
+
48
+ /**
49
+ * @param {{maxEvents: number, maxBytes: number, maxCalls: number}} limits
50
+ */
51
+ export function createBudget(limits) {
52
+ /** @type {Map<string, Slot>} */
53
+ const hot = new Map();
54
+ /** @type {Map<string, number>} */
55
+ const keptN = new Map();
56
+ /** @type {string[]} */
57
+ const hits = [];
58
+ const hitset = new Set();
59
+ let failuresKept = 0;
60
+ let events = 0;
61
+ let bytes = 0;
62
+
63
+ /** @param {number} file @param {number} c */
64
+ const keyOf = (file, c) => `${file}:${c}`;
65
+
66
+ /** @param {string} name */
67
+ function mark(name) {
68
+ if (!hitset.has(name)) {
69
+ hitset.add(name);
70
+ hits.push(name);
71
+ }
72
+ }
73
+
74
+ /**
75
+ * @param {number} file
76
+ * @param {number} c
77
+ * @param {string} reason
78
+ * @returns {Slot}
79
+ */
80
+ function slotFor(file, c, reason) {
81
+ const key = keyOf(file, c);
82
+ let slot = hot.get(key);
83
+ if (!slot) {
84
+ slot = { elided: 0, file, c, kept: keptN.get(key) ?? 0, reason };
85
+ hot.set(key, slot);
86
+ }
87
+ return slot;
88
+ }
89
+
90
+ /** @param {Slot} slot */
91
+ function drop(slot) {
92
+ slot.elided += 1;
93
+ if (slot.elided === 1) mark(slot.reason);
94
+ }
95
+
96
+ return {
97
+ limits,
98
+ /**
99
+ * @param {string} kind
100
+ * @param {number} nbytes
101
+ */
102
+ note(kind, nbytes) {
103
+ bytes += nbytes;
104
+ if (EVENT_KINDS.has(kind)) events += 1;
105
+ },
106
+ /**
107
+ * A reason string when this activation must not be stored, else null.
108
+ * A hot function takes the fast path: the slot already says why.
109
+ * @param {{elided?: boolean, reason?: string|null}|null} parent
110
+ * @param {number} file
111
+ * @param {number} c
112
+ * @returns {string|null}
113
+ */
114
+ hiding(parent, file, c) {
115
+ // A child of an elided frame is counted, not stored. That does not
116
+ // use up the child's own quota: a later call with a recorded parent
117
+ // is judged on its own caps.
118
+ if (parent && parent.elided) {
119
+ const reason = parent.reason || 'max_calls';
120
+ drop(slotFor(file, c, reason));
121
+ return reason;
122
+ }
123
+ const key = keyOf(file, c);
124
+ const n = keptN.get(key) ?? 0;
125
+ /** @type {string[]} */
126
+ const reasons = [];
127
+ if (limits.maxCalls && n >= limits.maxCalls) reasons.push('max_calls');
128
+ if (limits.maxEvents && events >= limits.maxEvents) reasons.push('max_events');
129
+ if (limits.maxBytes && bytes >= limits.maxBytes) reasons.push('max_bytes');
130
+ if (!reasons.length) return null;
131
+ for (const reason of reasons) mark(reason);
132
+ const existing = hot.get(key);
133
+ if (existing) {
134
+ drop(existing);
135
+ return existing.reason;
136
+ }
137
+ hot.set(key, { elided: 1, file, c, kept: n, reason: reasons[0] });
138
+ return reasons[0];
139
+ },
140
+ /**
141
+ * A call that was stored. Arms the per-function quota once it is full.
142
+ * A slot opened earlier, because this function was under an elided
143
+ * parent, keeps its elided count and gains this stored call.
144
+ * @param {number} file
145
+ * @param {number} c
146
+ */
147
+ kept(file, c) {
148
+ const key = keyOf(file, c);
149
+ const n = (keptN.get(key) ?? 0) + 1;
150
+ keptN.set(key, n);
151
+ const slot = hot.get(key);
152
+ if (slot) slot.kept += 1;
153
+ else if (limits.maxCalls && n >= limits.maxCalls) {
154
+ hot.set(key, { elided: 0, file, c, kept: n, reason: 'max_calls' });
155
+ }
156
+ },
157
+ /**
158
+ * Spend one elided count so the skeleton CALL is written once.
159
+ * @param {number} file
160
+ * @param {number} c
161
+ * @returns {boolean}
162
+ */
163
+ noteFailure(file, c) {
164
+ const slot = hot.get(keyOf(file, c));
165
+ if (!slot || slot.elided <= 0) return false;
166
+ slot.elided -= 1;
167
+ slot.kept += 1;
168
+ failuresKept += 1;
169
+ return true;
170
+ },
171
+ /**
172
+ * Outermost elided ancestor first, then the throwing frame.
173
+ * @param {CapFrame} frame
174
+ * @param {CapFrame[]} stack
175
+ * @param {(frame: CapFrame, parent: CapFrame|null) => void} emitCall
176
+ */
177
+ materialize(frame, stack, emitCall) {
178
+ if (!frame) return;
179
+ /** @type {CapFrame[]} */
180
+ const chain = [];
181
+ const idx = stack.lastIndexOf(frame);
182
+ if (idx < 0) {
183
+ if (frame.elided) chain.push(frame);
184
+ } else {
185
+ for (let i = idx; i >= 0 && stack[i].elided; i--) chain.push(stack[i]);
186
+ }
187
+ for (let i = chain.length - 1; i >= 0; i--) {
188
+ const cur = chain[i];
189
+ if (!cur.elided || cur.file === undefined || cur.c === undefined) continue;
190
+ if (!this.noteFailure(cur.file, cur.c)) continue;
191
+ const at = stack.lastIndexOf(cur);
192
+ const below = at > 0 ? stack[at - 1] : null;
193
+ const parent = below && !below.elided ? below : null;
194
+ cur.elided = false;
195
+ emitCall(cur, parent);
196
+ }
197
+ },
198
+ /** @returns {Record<string, unknown>|null} */
199
+ report() {
200
+ let callsElided = 0;
201
+ /** @type {{file: number, c: number, elided: number, kept: number}[]} */
202
+ const elisions = [];
203
+ for (const slot of hot.values()) {
204
+ callsElided += slot.elided;
205
+ if (slot.elided > 0) {
206
+ elisions.push({ file: slot.file, c: slot.c, elided: slot.elided, kept: slot.kept });
207
+ }
208
+ }
209
+ if (callsElided <= 0) return null;
210
+ /** @type {Record<string, unknown>} */
211
+ const rec = {
212
+ e: 'ELISION',
213
+ hit: hits.slice(),
214
+ maxEvents: limits.maxEvents,
215
+ maxBytes: limits.maxBytes,
216
+ maxCalls: limits.maxCalls,
217
+ eventsRecorded: events,
218
+ callsElided,
219
+ elisions,
220
+ };
221
+ if (failuresKept) rec.failuresKept = failuresKept;
222
+ return rec;
223
+ },
224
+ };
225
+ }
226
+
227
+ export const budget = createBudget(limitsFromEnv());
@@ -0,0 +1,40 @@
1
+ // What this recorder declares it produces, and nothing else.
2
+ //
3
+ // Its own module because `rt.mjs` is at the repo's 800-line ceiling and this
4
+ // is the one block in it that answers a question of its own: what a READER
5
+ // may ask of a trace this runtime wrote. The declaration is the runtime's
6
+ // word — a spool whose BOOT lacks a key reads `false` for every one of them,
7
+ // so what is missing is a record and not a permission — and it belongs to
8
+ // the recorder rather than to the converter for that reason (§2.4).
9
+
10
+ /**
11
+ * What this recorder DECLARES it produces, written into every BOOT record and
12
+ * passed through by the converter (§2.4). A spool whose BOOT lacks a key reads
13
+ * `false`, so a trace this recorder did not write is still refused — what it
14
+ * lacks is a record, not a permission.
15
+ *
16
+ * `err_flow` says the throw-flow rows are complete enough to be judged: every
17
+ * `throw` statement, every `catch` clause with the transform's verdict about
18
+ * its binding, every rejection handler and every `finally` that discards a
19
+ * throw in flight.
20
+ *
21
+ * `object_identity` says every captured object carries an `oid` that is the
22
+ * same number wherever that object is seen again and is never given to a
23
+ * second one. It does not depend on a focus: a RETURN's value is captured at
24
+ * every tier this recorder records at, so the identity is there to follow
25
+ * whether or not any statement was.
26
+ *
27
+ * `line` and `locals` say the LINE rows exist — one per completed statement of
28
+ * a focused function, carrying the names it wrote and the names out of scope
29
+ * at it. Both are declared exactly when `SENSORIUM_FOCUS` is non-empty: with
30
+ * no focus nothing was instrumented for statements and there are no such rows,
31
+ * and a reader told otherwise would report "no hits" for a search that never
32
+ * had anything to search.
33
+ * @param {string} focus the run's `SENSORIUM_FOCUS`, empty when there was none
34
+ * @returns {Record<string, boolean>}
35
+ */
36
+ export function capabilities(focus) {
37
+ return focus === ''
38
+ ? { err_flow: true, object_identity: true }
39
+ : { err_flow: true, object_identity: true, line: true, locals: true };
40
+ }
@@ -0,0 +1,348 @@
1
+ // Reading values out of the program under test, without trusting them. Both
2
+ // exports take a value the consumer produced — a return value, a thrown thing —
3
+ // and hand back a small JSON object the wire can carry. `dbg` and `exc` do not throw:
4
+ // a recorder that dies on a hostile object has changed the program it was
5
+ // supposed to observe. What cannot be read is SAID to be unread; nothing here
6
+ // invents a value it did not obtain.
7
+ //
8
+ // Rule v1 (§2.3) reaches these texts from two directions. A capture `dbg`
9
+ // makes is ruled by NAME where it has one — `redact.mjs`'s `redactCaptures`
10
+ // and `redactReturn`, which `rt.mjs` puts between every capture here and the
11
+ // wire — and by the content rule where the name fires on nothing. A thrown
12
+ // MESSAGE has no name to be asked about, so `exc` applies the content rule
13
+ // itself, here, before the text is written.
14
+ import util from 'node:util';
15
+
16
+ import { content, current, redactCaptures } from './redact.mjs';
17
+
18
+ /** The byte budget one captured value gets on the wire (design §4). */
19
+ const CAP = 200;
20
+
21
+ /** The one inspection this recorder does, pinned by `rt.test.mjs` (`dbg caps`). */
22
+ const INSPECT = {
23
+ depth: 2,
24
+ maxArrayLength: 8,
25
+ maxStringLength: 100,
26
+ breakLength: Infinity,
27
+ compact: true,
28
+ };
29
+
30
+ // State only. At depth 0 a fulfilled string and a rejection's stack are still
31
+ // inlined, so the capture keeps the state word and drops the rest.
32
+ // `maxStringLength: 0` stops a long fulfilled string from being copied into
33
+ // that check. No `then`: a reaction would observe a pending promise and would
34
+ // handle a rejection the program left unhandled.
35
+ const PROMISE_INSPECT = {
36
+ depth: 0,
37
+ maxStringLength: 0,
38
+ customInspect: false,
39
+ showHidden: false,
40
+ compact: true,
41
+ breakLength: Infinity,
42
+ colors: false,
43
+ };
44
+
45
+ /**
46
+ * What the rule withheld, on the capture it took it from (§4.2): `by` is
47
+ * `name` for a value taken whole and `content` for a span replaced inside
48
+ * one, and `digest` is the HMAC of what was taken — `null` for a span,
49
+ * because a partial cannot honestly commit to the whole.
50
+ * @typedef {{by: string, digest: string|null}} Redacted
51
+ */
52
+
53
+ /**
54
+ * A value this recorder read, as the wire carries it. `oid` and `type` are on
55
+ * the capture of an OBJECT or a function and on nothing else: a primitive has
56
+ * no identity to carry and this recorder does not invent one for it.
57
+ * @typedef {{k: 'dbg', v: string, trunc: boolean, oid?: number, type?: string,
58
+ * redacted?: Redacted}} Dbg
59
+ */
60
+
61
+ /**
62
+ * What one captured value is on the wire. A value it could not read is
63
+ * `unread` whole — an oid there would say it knows WHICH object it failed to
64
+ * read.
65
+ * @typedef {Dbg|{k: 'unread'}} Captured
66
+ */
67
+
68
+ /** Serials are per value, not per record: a rethrown OBJECT keeps its own. */
69
+ let nextSerial = 1;
70
+ /** @type {WeakMap<object, number>} */
71
+ const serials = new WeakMap();
72
+
73
+ /**
74
+ * The identity a captured object carries, and the counter that mints it.
75
+ *
76
+ * Deliberately NOT the exception map above (P12). The two number different
77
+ * populations — every object a capture reads, against every value a throw
78
+ * carried — and one shared counter would put `oid` and `serial` in the same
79
+ * sequence, which reads as a relation between two records that have none. Held
80
+ * weakly, so remembering an identity never keeps an object alive; minted once
81
+ * per object and never reused, so one number means one object for the life of
82
+ * the container and the same object wherever it is seen again.
83
+ */
84
+ let nextOid = 1;
85
+ /** @type {WeakMap<object, number>} */
86
+ const oids = new WeakMap();
87
+
88
+ /**
89
+ * @param {object} o
90
+ * @returns {number} minted once per object, never reused
91
+ */
92
+ function oidOf(o) {
93
+ let id = oids.get(o);
94
+ if (id === undefined) {
95
+ id = nextOid++;
96
+ oids.set(o, id);
97
+ }
98
+ return id;
99
+ }
100
+
101
+ /**
102
+ * @param {unknown} v
103
+ * @returns {v is object}
104
+ */
105
+ function isObject(v) {
106
+ return v !== null && (typeof v === 'object' || typeof v === 'function');
107
+ }
108
+
109
+ /**
110
+ * @param {object} v
111
+ * @returns {string}
112
+ */
113
+ function ctorName(v) {
114
+ // A throwing getter is not a timer. Falling through lets `inspect` read the
115
+ // value and `typeOf` report `unread`.
116
+ try {
117
+ const ctor = /** @type {{constructor?: unknown}} */ (v).constructor;
118
+ return typeof ctor === 'function' && typeof ctor.name === 'string' ? ctor.name : '';
119
+ } catch {
120
+ return '';
121
+ }
122
+ }
123
+
124
+ /**
125
+ * @param {object} v
126
+ * @param {string} name
127
+ * @returns {boolean}
128
+ */
129
+ function hasMethod(v, name) {
130
+ try {
131
+ return typeof /** @type {Record<string, unknown>} */ (v)[name] === 'function';
132
+ } catch {
133
+ return false;
134
+ }
135
+ }
136
+
137
+ /**
138
+ * Node's `Timeout` (`setTimeout` / `setInterval`). It is not a thenable.
139
+ * @param {unknown} v
140
+ * @returns {boolean}
141
+ */
142
+ function isTimeout(v) {
143
+ return isObject(v) && ctorName(v) === 'Timeout' && hasMethod(v, 'ref') && hasMethod(v, 'refresh');
144
+ }
145
+
146
+ /**
147
+ * Node's `Immediate` (`setImmediate`).
148
+ * @param {unknown} v
149
+ * @returns {boolean}
150
+ */
151
+ function isImmediate(v) {
152
+ return isObject(v) && ctorName(v) === 'Immediate' && hasMethod(v, 'ref') && hasMethod(v, 'hasRef');
153
+ }
154
+
155
+ /**
156
+ * A real promise: `then` is a function, and the value is one this process
157
+ * treats as a Promise. An arbitrary thenable is left to `inspect`.
158
+ * @param {unknown} v
159
+ * @returns {v is Promise<unknown>}
160
+ */
161
+ function isPromise(v) {
162
+ if (!isObject(v) || !util.types.isPromise(v)) return false;
163
+ return typeof /** @type {{then?: unknown}} */ (v).then === 'function';
164
+ }
165
+
166
+ /**
167
+ * `Promise { <pending> }`, `Promise { <fulfilled> }`, or `Promise { <rejected> }`.
168
+ * The state word is the prefix of `inspect`, never a fulfilled value that
169
+ * happens to mention the same word.
170
+ * @param {string} text
171
+ * @returns {string}
172
+ */
173
+ function promiseSummary(text) {
174
+ const mark = /^[^{]*\{\s*<(pending|rejected)>/.exec(text);
175
+ if (mark !== null && (mark[1] === 'pending' || mark[1] === 'rejected')) {
176
+ return `Promise { <${mark[1]}> }`;
177
+ }
178
+ // Fulfilled inspect names Promise and no state word. If it names neither,
179
+ // the state could not be read, so the capture is the one word `Promise`.
180
+ return text.includes('Promise') ? 'Promise { <fulfilled> }' : 'Promise';
181
+ }
182
+
183
+ /**
184
+ * A short stand-in for a Promise, Timeout, or Immediate, or null when `v`
185
+ * is an ordinary value. Timers are recognized first so their inspect, which
186
+ * prints `_idleNext` and symbols, is never the capture. A promise's
187
+ * fulfillment is not walked, so a promise of a timer stays a promise summary.
188
+ * @param {unknown} v
189
+ * @returns {string|null}
190
+ */
191
+ function summaryOf(v) {
192
+ if (isTimeout(v)) return 'Timeout';
193
+ if (isImmediate(v)) return 'Immediate';
194
+ if (!isPromise(v)) return null;
195
+ return promiseSummary(util.inspect(v, PROMISE_INSPECT));
196
+ }
197
+
198
+ /**
199
+ * Capture a value — a RETURN's, a focused CALL's argument, a statement's delta.
200
+ * @param {unknown} v
201
+ * @returns {Captured}
202
+ */
203
+ export function dbg(v) {
204
+ // The common case — an instrumented function that returns nothing — never
205
+ // reaches the inspector.
206
+ if (v === undefined) return { k: 'dbg', v: 'undefined', trunc: false };
207
+ let text;
208
+ try {
209
+ // Summarize before the byte cap, so a timer or a promise is the short
210
+ // text and `trunc` stays false.
211
+ text = summaryOf(v) ?? util.inspect(v, INSPECT);
212
+ } catch {
213
+ return { k: 'unread' };
214
+ }
215
+ const { v: text_, trunc } = cap(text);
216
+ /** @type {Dbg} */
217
+ const out = { k: 'dbg', v: text_, trunc };
218
+ const t = typeof v;
219
+ // `null` is `typeof "object"` and is a primitive all the same.
220
+ if (v !== null && (t === 'object' || t === 'function')) {
221
+ out.oid = oidOf(/** @type {object} */ (v));
222
+ out.type = typeOf(v);
223
+ }
224
+ return out;
225
+ }
226
+
227
+ /**
228
+ * The byte budget, applied to any string this recorder puts on the wire that
229
+ * the CONSUMER supplied — an inspected value, a test name the harness handed
230
+ * us (R14). The cut falls between characters and never through one, so a
231
+ * truncated capture is still text; what was cut is always declared.
232
+ * @param {string} text
233
+ * @returns {{v: string, trunc: boolean}}
234
+ */
235
+ export function cap(text) {
236
+ if (Buffer.byteLength(text) <= CAP) return { v: text, trunc: false };
237
+ let bytes = 0;
238
+ let end = 0;
239
+ for (const ch of text) {
240
+ const width = Buffer.byteLength(ch);
241
+ if (bytes + width > CAP) break;
242
+ bytes += width;
243
+ end += ch.length;
244
+ }
245
+ return { v: text.slice(0, end), trunc: true };
246
+ }
247
+
248
+ /**
249
+ * Describe a thrown or rejected value. Both strings it reads came from the
250
+ * consumer, so both are capped (R14a) and a cut is DECLARED in the contract's
251
+ * own spelling (TRACE-FORMAT §5): `trunc` for a cut message, `type_trunc` for a
252
+ * cut type name, each absent when nothing was cut — which is what tells a
253
+ * reader that a text is a whole identity and may be compared as one.
254
+ * @param {*} e the value the program threw
255
+ * @param {'throw'|'rejection'} kind how it arrived
256
+ * @returns {Record<string, unknown>} `{kind, type, msg, serial}` and the flags
257
+ */
258
+ export function exc(e, kind) {
259
+ const type = cap(typeOf(e));
260
+ const msg = cap(msgOf(e));
261
+ // A message is a sentence the program wrote, not a value with an identity,
262
+ // so the CONTENT rule is the only one it meets (§2.3) — the span goes and
263
+ // the sentence around it stays. `trunc` is untouched by that: the text WAS
264
+ // clipped, and a span inside it was replaced.
265
+ const found = current().knobs.off ? { text: msg.v, hit: false } : content(msg.v);
266
+ /** @type {Record<string, unknown>} */
267
+ const out = { kind, type: type.v, msg: found.text, serial: serialOf(e) };
268
+ if (msg.trunc) out.trunc = true;
269
+ if (type.trunc) out.type_trunc = true;
270
+ if (found.hit) out.redacted = { by: 'content', digest: null };
271
+ return out;
272
+ }
273
+
274
+ /**
275
+ * The constructor's name for an object or a function, `typeof` for a primitive
276
+ * (`null` included, which is `object`), and `unread` when the object lies about
277
+ * its own constructor.
278
+ * @param {*} e
279
+ * @returns {string}
280
+ */
281
+ function typeOf(e) {
282
+ const t = typeof e;
283
+ if (e === null || (t !== 'object' && t !== 'function')) return t;
284
+ try {
285
+ const name = e.constructor?.name;
286
+ return typeof name === 'string' ? name : 'unread';
287
+ } catch {
288
+ return 'unread';
289
+ }
290
+ }
291
+
292
+ /**
293
+ * `e.message` where there is one, the value's own string form otherwise, and
294
+ * `<unread>` when either read throws — a getter that raises, an object with no
295
+ * prototype, a Symbol.
296
+ * @param {*} e
297
+ * @returns {string}
298
+ */
299
+ function msgOf(e) {
300
+ try {
301
+ const t = typeof e;
302
+ if (e !== null && (t === 'object' || t === 'function') && 'message' in e) {
303
+ return String(e.message);
304
+ }
305
+ return String(e);
306
+ } catch {
307
+ return '<unread>';
308
+ }
309
+ }
310
+
311
+ /**
312
+ * One serial per thrown OBJECT, minted once and remembered weakly, so a rethrow
313
+ * is followable; a fresh one for every primitive, because two equal strings are
314
+ * not the same throw and this recorder will not claim they are.
315
+ * @param {*} e
316
+ * @returns {number}
317
+ */
318
+ function serialOf(e) {
319
+ const t = typeof e;
320
+ if (e === null || (t !== 'object' && t !== 'function')) return nextSerial++;
321
+ let serial = serials.get(e);
322
+ if (serial === undefined) {
323
+ serial = nextSerial++;
324
+ serials.set(e, serial);
325
+ }
326
+ return serial;
327
+ }
328
+
329
+ /**
330
+ * A `[name, value, name, value, ...]` list, as the map the wire carries.
331
+ * Names are the transform's; values are the program's, so every value goes
332
+ * through `dbg` and no name does. An odd list throws: the transform emits
333
+ * both halves, and dropping the trailing name would hide a splice defect.
334
+ * The runtime calls this only for a call it is going to store.
335
+ * @param {unknown[]} pairs
336
+ * @returns {Record<string, Captured>}
337
+ */
338
+ export function captures(pairs) {
339
+ if (pairs.length % 2 !== 0) throw new TypeError('captures: an odd pairs list — ' + pairs.length + ' entries');
340
+ /** @type {Record<string, Captured>} */
341
+ const out = {};
342
+ for (let i = 0; i + 1 < pairs.length; i += 2) {
343
+ out[/** @type {string} */ (pairs[i])] = dbg(pairs[i + 1]);
344
+ }
345
+ // Rule v1's NAME half, before the record exists, so the plaintext of a
346
+ // secret-shaped name never reaches the disk.
347
+ return redactCaptures(out);
348
+ }