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
sensorium/ts/pkg.py ADDED
@@ -0,0 +1,167 @@
1
+ """Where the Node library is, and whether this box can run it.
2
+
3
+ Two questions the driver has to settle BEFORE it mints an invocation or
4
+ spawns anything, because both of them have answers a recording cannot
5
+ recover from: a Node older than the one the recorder was measured on, and a
6
+ package that has never been installed. Each is a refusal with a sentence
7
+ naming the fix, and neither leaves a spool directory behind.
8
+
9
+ The package's location is one rule in one place (`locate`). `SENSORIUM_TS_PKG`
10
+ names it when the library lives somewhere else -- a test pointing at an empty
11
+ directory, a checkout beside a wheel -- and otherwise it is the `typescript/`
12
+ directory beside `src/` when this module was imported from a checkout, or the
13
+ `sensorium/_typescript` tree a wheel ships next to the package. The same
14
+ variable is exported to the harness, so what the driver checked and what the
15
+ loader hook resolves are the same directory by construction.
16
+ """
17
+ import os
18
+ import re
19
+ import subprocess
20
+ from pathlib import Path
21
+
22
+ import sensorium
23
+
24
+ #: The variable that names the package, and the only one. Read here and
25
+ #: exported to the harness by the driver.
26
+ ENV_VAR = "SENSORIUM_TS_PKG"
27
+
28
+ #: The Node the recorder was measured on (D2). Below it nothing was
29
+ #: measured, so nothing is claimed: the driver refuses rather than record a
30
+ #: run whose async semantics it has never seen.
31
+ NODE_FLOOR = 24
32
+
33
+ #: The one file whose presence says the package has been installed. The
34
+ #: transform bare-imports `magic-string`, so its absence is not a missing
35
+ #: nicety -- it is an `ERR_MODULE_NOT_FOUND` thrown deep inside a Vite
36
+ #: transform, minutes later, about a module the consumer never mentioned.
37
+ INSTALLED = Path("node_modules") / "magic-string"
38
+
39
+ #: The one module resolved from the CONSUMER's tree rather than this
40
+ #: package's. The transform positions itself against the AST the consumer's
41
+ #: own build produces, so it parses with the compiler that build trusts.
42
+ CONSUMER_DEP = "typescript"
43
+
44
+
45
+ class PackageError(Exception):
46
+ """The Node side cannot be used, and the sentence says what to do."""
47
+
48
+
49
+ def locate() -> Path:
50
+ """The `sensorium-ts` package directory.
51
+
52
+ An EMPTY variable is not a location -- `or` and not a presence test, so
53
+ `SENSORIUM_TS_PKG=` falls through rather than resolving to the process's
54
+ working directory.
55
+
56
+ A checkout (and an editable install of one) keeps the Node package at
57
+ `typescript/` beside `src/`. A non-editable install has no such
58
+ directory: `parents[2]` of an installed `sensorium/__init__.py` is the
59
+ virtualenv, not the repository. The wheel carries the Node sources at
60
+ `sensorium/_typescript`, which is the location a `git+https` install
61
+ can actually see. `node_modules` is not part of that tree; `check`
62
+ still refuses until `npm ci --prefix` that directory.
63
+ """
64
+ env = os.environ.get(ENV_VAR)
65
+ if env:
66
+ return Path(env)
67
+ here = Path(sensorium.__file__).resolve()
68
+ checkout = here.parents[2] / "typescript"
69
+ if (checkout / "package.json").is_file():
70
+ return checkout
71
+ installed = here.parent / "_typescript"
72
+ if (installed / "package.json").is_file():
73
+ return installed
74
+ raise PackageError(
75
+ "cannot find the recorder's Node package. A checkout keeps it at "
76
+ "typescript/ beside src/. A wheel install ships it inside the "
77
+ "sensorium package, at sensorium/_typescript. Set "
78
+ f"{ENV_VAR} to the directory that contains package.json.")
79
+
80
+
81
+ def check(pkg: Path) -> None:
82
+ """Refuse a package whose dependencies were never installed."""
83
+ if not (pkg / INSTALLED).is_dir():
84
+ raise PackageError(
85
+ f"the recorder's Node package at {pkg} has no {INSTALLED}: "
86
+ f"install it with `npm ci --prefix {pkg}`")
87
+
88
+
89
+ def check_root(root: Path) -> None:
90
+ """Refuse a project whose own TypeScript the transform cannot resolve.
91
+
92
+ The transform parses with the CONSUMER's compiler and never with this
93
+ package's: the loader hook and the Vite plugin both `require` it from
94
+ the ROOT, because the AST a recorder positions itself against has to be
95
+ the one the consumer's own build produces. Absent, that surfaced as an
96
+ `ERR_MODULE_NOT_FOUND` thrown inside a transform, minutes into a run,
97
+ about a module the consumer never mentioned -- the same failure shape
98
+ `check` above exists to stop for `magic-string`.
99
+
100
+ Resolved the way NODE resolves it from `<root>/package.json`:
101
+ `<root>/node_modules`, then each parent's. A workspace package whose
102
+ dependency is hoisted to the repository root has no `node_modules` of
103
+ its own and runs fine, and refusing it for a directory Node was never
104
+ going to look in would be a refusal about this check, not about the run.
105
+ """
106
+ root = Path(root)
107
+ for directory in (root, *root.parents):
108
+ if (directory / "node_modules" / CONSUMER_DEP
109
+ / "package.json").is_file():
110
+ return
111
+ raise PackageError(
112
+ f"{root} has no {CONSUMER_DEP} in node_modules: the transform "
113
+ f"parses with the consumer's own compiler, and there is none here "
114
+ f"to parse with -- install it with `npm install --save-dev "
115
+ f"{CONSUMER_DEP}`")
116
+
117
+
118
+ def version(pkg: Path) -> str:
119
+ """The package's own version, for the `recorder` a spool without one
120
+ falls back to (R5).
121
+
122
+ Read as text rather than as JSON, and never an error: this is a
123
+ FALLBACK, used only for a spool whose BOOT record did not name its own
124
+ writer, and a manifest this cannot read is not a reason to refuse a
125
+ recording that would otherwise happen.
126
+ """
127
+ try:
128
+ text = (pkg / "package.json").read_text(encoding="utf-8")
129
+ except OSError:
130
+ return "unknown"
131
+ m = re.search(r'"version"\s*:\s*"([^"]*)"', text)
132
+ return m.group(1) if m else "unknown"
133
+
134
+
135
+ def node_version(node: str = "node") -> tuple[str, tuple[int, ...]]:
136
+ """What `node --version` says, as it said it and as numbers.
137
+
138
+ The reported string is carried into the trace verbatim (`meta.node` is
139
+ what the container itself reports; this is what the DRIVER saw), so it
140
+ is returned beside the parse rather than replaced by it.
141
+ """
142
+ try:
143
+ out = subprocess.run([node, "--version"], capture_output=True,
144
+ text=True)
145
+ except OSError:
146
+ raise PackageError(
147
+ f"cannot run `{node} --version`: this recorder drives node, and "
148
+ f"Node {NODE_FLOOR} or newer is the version it was measured on"
149
+ ) from None
150
+ reported = out.stdout.strip()
151
+ parts = tuple(int(n) for n in re.findall(r"\d+", reported)[:3])
152
+ if out.returncode != 0 or not parts:
153
+ raise PackageError(
154
+ f"`{node} --version` answered nothing this recorder can read "
155
+ f"({reported!r}): it needs Node {NODE_FLOOR} or newer")
156
+ return reported, parts
157
+
158
+
159
+ def check_node(node: str = "node") -> str:
160
+ """The Node version string, or a refusal naming the floor."""
161
+ reported, parts = node_version(node)
162
+ if parts[0] < NODE_FLOOR:
163
+ raise PackageError(
164
+ f"node {reported} is below this recorder's floor of "
165
+ f"{NODE_FLOOR}: Node {NODE_FLOOR} is the version its async "
166
+ "model was measured on, and nothing older was")
167
+ return reported
@@ -0,0 +1,64 @@
1
+ """Which hand applied rule v1 to a TypeScript spool, and whether it runs.
2
+
3
+ Two decisions, both read off the BOOT record and both taken ONCE per spool,
4
+ because every value site in `build.py` needs the same answer:
5
+
6
+ * **`rule_runs`** -- whether rule v1 applies to this spool's captures at all
7
+ (B26). A recording made with the rule off is converted as it was written.
8
+ * **`ran_the_value_rule`** -- whether the RECORDER already applied the NAME
9
+ half, which decides both what `build.py` has left to do and the `by` word
10
+ the trace carries (B2).
11
+
12
+ Its own module for the reason `cargo-sensorium`'s `convert/redaction.rs` is
13
+ one: the converter's mapping is long enough already, and this is the part of
14
+ it that has to be read against the design's §5.4 rather than against the
15
+ wire.
16
+ """
17
+ import re
18
+
19
+ #: The `sensorium-ts` the value half of rule v1 shipped in (B2). A BOOT
20
+ #: below it says `mode: "on"` about its ENVIRONMENT and nothing else, so the
21
+ #: converter runs the name rule over its captures itself.
22
+ VALUES_FROM = (0, 6, 0)
23
+
24
+
25
+ def ran_the_value_rule(boot: dict) -> bool:
26
+ """Whether the RECORDER applied rule v1 to its own captures (B2).
27
+
28
+ Two facts together: the BOOT says `mode: "on"`, and it was written by a
29
+ recorder that HAD the value rules. 0.5.0 says `mode: "on"` about its
30
+ environment while its captures are plaintext, and a converter that
31
+ trusted the word alone would pass those through as recorded.
32
+ """
33
+ recorded = boot.get("redaction")
34
+ return (isinstance(recorded, dict) and recorded.get("mode") == "on"
35
+ and version_tuple(boot.get("version")) >= VALUES_FROM)
36
+
37
+
38
+ def rule_runs(boot: dict) -> bool:
39
+ """Whether rule v1 runs over this spool's captures at all (B26).
40
+
41
+ True for a spool written before the rule existed -- it is exactly the
42
+ spool whose captures nobody has judged -- and for one whose BOOT says
43
+ `mode: "on"`. False for `mode: "off"`, for a mode this converter does
44
+ not know, and for a `redaction` that is not an object: the same set
45
+ `_redaction` passes through untouched, because a converter that added a
46
+ judgement to a header it could not read would be reporting one nobody
47
+ made.
48
+ """
49
+ recorded = boot.get("redaction")
50
+ if not recorded:
51
+ return True
52
+ return isinstance(recorded, dict) and recorded.get("mode") == "on"
53
+
54
+
55
+ def version_tuple(reported) -> tuple[int, ...]:
56
+ """`"0.6.0"` -> `(0, 6, 0)`, and `()` for anything unreadable.
57
+
58
+ The empty tuple sorts BELOW every real version, so a spool that names no
59
+ writer is treated as older than the rule -- the safe direction, where
60
+ the converter applies it rather than assuming somebody else did.
61
+ """
62
+ if not isinstance(reported, str):
63
+ return ()
64
+ return tuple(int(n) for n in re.findall(r"\d+", reported)[:3])
sensorium/ts/spool.py ADDED
@@ -0,0 +1,168 @@
1
+ """The wire: one JSONL spool, streamed back into records.
2
+
3
+ One file per container -- `<pid>-<threadId>.jsonl` -- one JSON object per
4
+ line, in the order the runtime observed the events. This module does the
5
+ reading and the two refusals that belong to it, and nothing else: what a
6
+ record MEANS is `ingest`'s.
7
+
8
+ The file is WALKED, never materialised (A3). BOOT is read eagerly, from
9
+ line 1, because nothing downstream can start without it; every later record
10
+ is yielded as the file is read, so the converter holds one record at a time
11
+ and not a list of two million. `exit` and `torn_tail` are therefore facts
12
+ only once the walk is DONE -- which is where the builder reads them, after
13
+ its loop.
14
+
15
+ Three properties of the file this module turns into facts:
16
+
17
+ * **The first record is BOOT**, because a spool that does not say what
18
+ wrote it, under what environment, at what wall clock, is not a recording
19
+ anybody can date or place. A spool with no BOOT is refused by name, and
20
+ so is one whose BOOT is not on line 1: a reader that streams has already
21
+ handed records to its caller by the time a later BOOT turns up.
22
+ * **There is exactly one BOOT** (R16). Two runtime instances writing one
23
+ spool means two module graphs resolved the runtime by two specifiers,
24
+ and every frame id, task id and file id in the file is then two
25
+ independent counters interleaved. Nothing downstream can untangle that,
26
+ so the spool is refused rather than converted into a plausible lie. The
27
+ second BOOT is met mid-walk, which aborts a build already under way --
28
+ `ingest.convert` unlinks the temporary file it had reserved, and the
29
+ refusal comes back from the worker as a value, exactly as before.
30
+ * **The last line may be torn.** A container killed by SIGKILL loses
31
+ whatever `appendFileSync` had not finished writing. A final line with no
32
+ newline after it is that tail, and it is dropped -- the trace is then
33
+ `incomplete`, which is the honest artifact. A malformed line ANYWHERE
34
+ ELSE is a refusal: that is a corrupt file, not a killed process.
35
+ """
36
+ import json
37
+ from collections.abc import Iterator
38
+ from dataclasses import dataclass, field
39
+ from pathlib import Path
40
+
41
+
42
+ class SpoolError(Exception):
43
+ """A spool cannot be read as one container's recording. Always names
44
+ the file: `ingest` prints it beside the spool it refused, and the other
45
+ spools of the same invocation are converted anyway."""
46
+
47
+
48
+ @dataclass
49
+ class Spool:
50
+ """One container's records, in the order they were written."""
51
+
52
+ path: Path
53
+ boot: dict
54
+ #: Every record after BOOT, in wire order, YIELDED as the file is
55
+ #: walked. BOOT is not among them: it is the header, and every caller
56
+ #: wants it by name. Consumable once, like any iterator -- a second
57
+ #: reader of one spool calls `read` again.
58
+ records: Iterator[dict] = field(default_factory=lambda: iter(()))
59
+ #: The EXIT record, or None. Its presence is what `incomplete` is read
60
+ #: from (R13) -- an EXIT with a `signal` still finalizes the trace,
61
+ #: because the container lived long enough to say how it ended. Known
62
+ #: once `records` is exhausted, which is where the builder reads it.
63
+ exit: dict | None = None
64
+ #: Whether the file's last line was cut mid-write. Known once
65
+ #: `records` is exhausted.
66
+ torn_tail: bool = False
67
+
68
+
69
+ def read(path) -> Spool:
70
+ """`path` opened and its BOOT read, or `SpoolError` naming it.
71
+
72
+ What comes back is a `Spool` whose `records` walks the rest of the file
73
+ as it is iterated; the handle it holds is closed when the walk ends, by
74
+ exhaustion or by refusal.
75
+ """
76
+ path = Path(path)
77
+ try:
78
+ fh = open(path, "rb")
79
+ except OSError as e:
80
+ raise SpoolError(f"{path} cannot be read as a spool: {e}") from None
81
+ try:
82
+ boot = _boot(path, fh)
83
+ except BaseException:
84
+ # Every refusal above the walk closes the handle here: the generator
85
+ # that would otherwise have closed it is never created.
86
+ fh.close()
87
+ raise
88
+ sp = Spool(path=path, boot=boot)
89
+ sp.records = _stream(sp, fh)
90
+ return sp
91
+
92
+
93
+ def _boot(path: Path, fh) -> dict:
94
+ """Line 1, which is BOOT or the end of this spool's reading."""
95
+ first = fh.readline()
96
+ if not first.endswith(b"\n") or not first.strip():
97
+ # No first line at all, nothing but a torn one, or a blank one: in
98
+ # none of those cases does the file open with a BOOT record.
99
+ raise SpoolError(f"no BOOT record in {path}: the spool does not say "
100
+ "what wrote it")
101
+ boot = _parse(path, 1, _decode(path, 1, first))
102
+ if boot.get("e") != "BOOT":
103
+ raise SpoolError(f"no BOOT record in {path}: line 1 is a "
104
+ f"{boot['e']} record, and the spool does not say "
105
+ "what wrote it")
106
+ caps = boot.get("capabilities")
107
+ if caps is not None and not isinstance(caps, dict):
108
+ # Present but not a map is not a declaration `build._meta` can merge
109
+ # over the constant -- refused here, where BOOT is read, rather than
110
+ # a worker crashing deep inside the merge.
111
+ raise SpoolError(f"{path}: BOOT carries a capabilities value that "
112
+ "is not a map")
113
+ return boot
114
+
115
+
116
+ def _stream(sp: Spool, fh) -> Iterator[dict]:
117
+ """Every record after BOOT, yielded as `fh` is walked.
118
+
119
+ `sp` is filled in as the walk goes: `torn_tail` when the last line has
120
+ no newline after it, `exit` when the EXIT record goes past. Both are
121
+ read by the builder AFTER its loop, which is the first point at which
122
+ either is known. The handle is closed on every way out of here --
123
+ exhaustion, torn tail, refusal, or a caller that stops early.
124
+ """
125
+ lineno = 1
126
+ with fh:
127
+ for raw in fh:
128
+ lineno += 1
129
+ if not raw.endswith(b"\n"):
130
+ sp.torn_tail = True # the tail a SIGKILL cut; dropped
131
+ return
132
+ line = _decode(sp.path, lineno, raw)
133
+ if not line.strip():
134
+ continue
135
+ rec = _parse(sp.path, lineno, line)
136
+ if rec.get("e") == "BOOT":
137
+ raise SpoolError(f"two BOOT records in {sp.path}: two runtime "
138
+ "instances wrote one spool")
139
+ if rec.get("e") == "EXIT":
140
+ sp.exit = rec
141
+ yield rec
142
+
143
+
144
+ def _decode(path: Path, lineno: int, raw: bytes) -> str:
145
+ """One line's bytes as text, or a refusal naming the line.
146
+
147
+ The file is read as bytes so the walk never holds more than a line of
148
+ it; a line that is not UTF-8 is then named where it is, which is more
149
+ than the whole-file decode this replaced could say.
150
+ """
151
+ try:
152
+ return raw.decode("utf-8")
153
+ except UnicodeDecodeError as e:
154
+ raise SpoolError(f"{path} line {lineno} is not UTF-8: {e} -- a spool "
155
+ "this recorder wrote is UTF-8 throughout") from None
156
+
157
+
158
+ def _parse(path: Path, lineno: int, line: str) -> dict:
159
+ try:
160
+ rec = json.loads(line)
161
+ except json.JSONDecodeError as e:
162
+ raise SpoolError(f"{path} line {lineno} is not readable JSON: {e} -- "
163
+ "a spool this recorder wrote is one object per "
164
+ "line") from None
165
+ if not isinstance(rec, dict) or not isinstance(rec.get("e"), str):
166
+ raise SpoolError(f"{path} line {lineno} is not a record: every line "
167
+ "carries an `e` naming its kind")
168
+ return rec
@@ -0,0 +1,81 @@
1
+ """Trace-cap meta from one ELISION spool record.
2
+
3
+ Written only when calls were dropped. No record, or a record whose elided
4
+ count is zero, leaves the trace without truncation meta, so a spool from
5
+ before caps still converts. The wire stays v1: `file` and `c` are the same
6
+ ids a CALL carries, and this module resolves them through the FILE header
7
+ the same way a CALL becomes a code object.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ from sensorium.ts.spool import SpoolError
12
+
13
+
14
+ def truncation_meta(rec: dict | None, files: dict, spool_path: str) -> dict:
15
+ """Optional meta. ``{}`` when nothing was dropped.
16
+
17
+ ``files`` maps a wire file id to its FILE record. A name this record
18
+ cannot resolve is a spool this converter cannot read.
19
+ """
20
+ if not rec:
21
+ return {}
22
+ try:
23
+ dropped = rec["callsElided"]
24
+ except KeyError as e:
25
+ raise _bad(spool_path, e) from None
26
+ if not isinstance(dropped, int) or isinstance(dropped, bool) or dropped <= 0:
27
+ return {}
28
+ rows = []
29
+ for row in rec.get("elisions") or []:
30
+ rows.append(_row(row, files, spool_path))
31
+ try:
32
+ limits = {
33
+ "max_events": rec["maxEvents"],
34
+ "max_bytes": rec["maxBytes"],
35
+ "max_calls": rec["maxCalls"],
36
+ "hit": list(rec["hit"]),
37
+ "events_recorded": rec["eventsRecorded"],
38
+ "calls_elided": dropped,
39
+ }
40
+ except (KeyError, TypeError) as e:
41
+ raise _bad(spool_path, e) from None
42
+ failures = rec.get("failuresKept") or 0
43
+ if failures:
44
+ limits["failures_kept"] = failures
45
+ return {
46
+ "trace_truncated": True,
47
+ "trace_limits": limits,
48
+ "elisions": rows,
49
+ }
50
+
51
+
52
+ def _row(row: dict, files: dict, spool_path: str) -> dict:
53
+ try:
54
+ file_id = row["file"]
55
+ index = row["c"]
56
+ except KeyError as e:
57
+ raise _bad(spool_path, e) from None
58
+ header = files.get(file_id)
59
+ if header is None:
60
+ raise SpoolError(
61
+ f"{spool_path}: an ELISION names file {file_id}, which no "
62
+ "FILE record declared")
63
+ codes = header["codes"]
64
+ if not isinstance(index, int) or isinstance(index, bool) or not 0 <= index < len(codes):
65
+ raise SpoolError(
66
+ f"{spool_path}: an ELISION names site {index} of "
67
+ f"{header['rel']}, which declared {len(codes)}")
68
+ qualname, line, _kind = codes[index]
69
+ return {
70
+ "file": header["abs"],
71
+ "qualname": qualname,
72
+ "firstlineno": line,
73
+ "elided": row["elided"],
74
+ "kept": row["kept"],
75
+ }
76
+
77
+
78
+ def _bad(spool_path: str, err: BaseException) -> SpoolError:
79
+ return SpoolError(
80
+ f"{spool_path}: an ELISION record is not the shape wire 1 "
81
+ f"declares ({type(err).__name__}: {err})")