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/c/format.py ADDED
@@ -0,0 +1,271 @@
1
+ """On-wire spool for the C recorder. Version 1. Little-endian.
2
+
3
+ The runtime (``c/rt/sensorium_c_rt.c``) and this module are the two
4
+ writers of one layout. Change either only together with the other.
5
+
6
+ Directory ``$SENSORIUM_C_ROOT/<pid>/`` per instrumented process:
7
+
8
+ threads/t<N>.bin per-thread record stream (main is tid 1)
9
+ argv.json this process's argv, a JSON list of strings
10
+ boot.json {"start_ts": <time.time()>}
11
+ exit.json {"status": int} or {"signal": int}
12
+ threads.json {"started": <extra threads created>, "live": [tid, ...]}
13
+ written at exit and from the fatal-signal handler
14
+ warn.txt one warning per line (``cet: ...``)
15
+ objs.txt ``<bias hex> <path>`` from dl_iterate_phdr; the main
16
+ executable's path is the literal ``<exe>``
17
+ forks.json [child pid, ...] if this process called fork
18
+
19
+ The driver owns ``$SENSORIUM_C_ROOT/side.json`` (invocation, the command
20
+ the user typed, the pid it waited on, harness_exit, compiler,
21
+ build_warnings, cwd) plus ``stdout.bin`` and ``stderr.bin`` for that pid.
22
+
23
+ A capture plan sits beside each linked image: ``<image>.scplan``.
24
+ Addresses in the plan are unrelocated ELF ``low_pc`` values.
25
+
26
+ Plan file
27
+ ---------
28
+ ``SCPL`` magic, ``u32`` version ``1``, ``u32`` count, then count
29
+ functions sorted by address:
30
+
31
+ addr u64, ret_class u8, ret_nreg u8, ret_size u16, nparams u16
32
+ then nparams times: off i32, size u16, flags u16
33
+
34
+ ``ret_class`` is ``RET_VOID`` (0), ``RET_INT`` (1, rax and maybe rdx),
35
+ ``RET_SSE`` (2, xmm0 and maybe xmm1), or ``RET_MEM`` (3, rax points at
36
+ the struct, ``ret_size`` bytes). ``off == NO_SLOT`` means the parameter
37
+ has no frame slot (optimized out, or a location list). ``FLAG_CSTR``
38
+ asks the runtime to copy a NUL-terminated byte string through
39
+ ``process_vm_readv``.
40
+
41
+ Thread file
42
+ -----------
43
+ ``SCR1`` magic, ``u32`` tid, then records. Each record header is 56
44
+ bytes (``<BxxxQQQQQQI``: kind, 3 zero pad bytes, seq, ts, a, b, c, d,
45
+ extra_len) plus ``extra``:
46
+
47
+ kind u8, pad 3 zero bytes, seq u64, ts u64, a u64, b u64, c u64, d u64,
48
+ extra_len u32, extra bytes
49
+
50
+ Kinds:
51
+
52
+ E enter. a=fn, b=call site, c=cfa (rbp+16), d=0.
53
+ extra is an argument blob (below).
54
+ X cyg exit hook, before the ret. a=fn, b=call site.
55
+ V return trampoline. a=rax, b=rdx, c=xmm0 bits, d=xmm1 bits.
56
+ extra is the memory return bytes when the plan says ``RET_MEM``.
57
+ S fatal signal. a=signo, b=si_addr, c=rip, d=si_code.
58
+ extra is up to 512 bytes at rsp.
59
+ A assert, before abort. a=line. extra is
60
+ ``assertion\\0file\\0function`` in utf-8, each part clipped.
61
+ J longjmp. a=target rbp, b=target rsp, c=target pc,
62
+ d=number of shadow frames abandoned.
63
+ F fork, in the parent. a=child pid.
64
+
65
+ Argument blob
66
+ -------------
67
+ ``nparams u16``, ``pad u16``, then each parameter in plan order:
68
+
69
+ off i32, size u16, flags u16, raw[size] if size else nothing,
70
+ and if ``FLAG_CSTR``: slen i32, then ``slen`` bytes when ``slen > 0``.
71
+
72
+ ``slen`` is ``-1`` if the read faulted, ``-2`` if the pointer was NULL,
73
+ ``0`` for an empty string, or the byte count before the NUL. A count of
74
+ ``STR_CAP`` with no NUL in those bytes is a truncated string.
75
+ """
76
+ from __future__ import annotations
77
+
78
+ import struct
79
+ from dataclasses import dataclass
80
+
81
+ MAGIC_PLAN = b"SCPL"
82
+ MAGIC_THREAD = b"SCR1"
83
+ VERSION = 1
84
+
85
+ RET_VOID = 0
86
+ RET_INT = 1
87
+ RET_SSE = 2
88
+ RET_MEM = 3
89
+
90
+ NO_SLOT = -0x80000000
91
+ FLAG_CSTR = 1
92
+ FLAG_TRUNC = 2
93
+
94
+ STR_CAP = 64
95
+ STACK_BYTES = 512
96
+
97
+ KIND_ENTER = ord("E")
98
+ KIND_EXIT = ord("X")
99
+ KIND_RET = ord("V")
100
+ KIND_SIGNAL = ord("S")
101
+ KIND_ASSERT = ord("A")
102
+ KIND_LONGJMP = ord("J")
103
+ KIND_FORK = ord("F")
104
+
105
+ _PLAN_HEAD = struct.Struct("<4sII")
106
+ _FUNC = struct.Struct("<QBBHH")
107
+ _PARAM = struct.Struct("<iHH")
108
+ _THREAD_HEAD = struct.Struct("<4sI")
109
+ _REC = struct.Struct("<BxxxQQQQQQI")
110
+ _ARG_HEAD = struct.Struct("<HH")
111
+ _SLEN = struct.Struct("<i")
112
+
113
+
114
+ @dataclass(frozen=True)
115
+ class ParamPlan:
116
+ off: int
117
+ size: int
118
+ flags: int
119
+
120
+
121
+ @dataclass(frozen=True)
122
+ class FuncPlan:
123
+ addr: int
124
+ ret_class: int
125
+ ret_nreg: int
126
+ ret_size: int
127
+ params: tuple[ParamPlan, ...]
128
+
129
+
130
+ def write_plan(path, funcs: list[FuncPlan]) -> None:
131
+ """Write ``path`` as a version-1 plan, functions sorted by address."""
132
+ ordered = sorted(funcs, key=lambda f: f.addr)
133
+ out = bytearray(_PLAN_HEAD.pack(MAGIC_PLAN, VERSION, len(ordered)))
134
+ for fn in ordered:
135
+ out += _FUNC.pack(fn.addr, fn.ret_class, fn.ret_nreg, fn.ret_size,
136
+ len(fn.params))
137
+ for p in fn.params:
138
+ out += _PARAM.pack(p.off, p.size, p.flags)
139
+ with open(path, "wb") as fh:
140
+ fh.write(out)
141
+
142
+
143
+ def read_plan(path) -> list[FuncPlan]:
144
+ """Read a plan file. Raises ``ValueError`` on a bad header."""
145
+ data = open(path, "rb").read()
146
+ if len(data) < _PLAN_HEAD.size:
147
+ raise ValueError(f"{path}: plan shorter than a header")
148
+ magic, version, count = _PLAN_HEAD.unpack_from(data, 0)
149
+ if magic != MAGIC_PLAN or version != VERSION:
150
+ raise ValueError(f"{path}: not a version-{VERSION} plan")
151
+ out = []
152
+ i = _PLAN_HEAD.size
153
+ for _ in range(count):
154
+ if i + _FUNC.size > len(data):
155
+ raise ValueError(f"{path}: truncated function")
156
+ addr, cls, nreg, size, nparams = _FUNC.unpack_from(data, i)
157
+ i += _FUNC.size
158
+ params = []
159
+ for _p in range(nparams):
160
+ if i + _PARAM.size > len(data):
161
+ raise ValueError(f"{path}: truncated parameter")
162
+ off, psz, flags = _PARAM.unpack_from(data, i)
163
+ i += _PARAM.size
164
+ params.append(ParamPlan(off, psz, flags))
165
+ out.append(FuncPlan(addr, cls, nreg, size, tuple(params)))
166
+ return out
167
+
168
+
169
+ @dataclass(frozen=True)
170
+ class ArgRaw:
171
+ off: int
172
+ size: int
173
+ flags: int
174
+ raw: bytes
175
+ slen: int | None
176
+ sbytes: bytes | None
177
+
178
+
179
+ def pack_args(args: list[ArgRaw]) -> bytes:
180
+ out = bytearray(_ARG_HEAD.pack(len(args), 0))
181
+ for a in args:
182
+ out += _PARAM.pack(a.off, a.size, a.flags)
183
+ if a.size:
184
+ if len(a.raw) != a.size:
185
+ raise ValueError("raw length does not match size")
186
+ out += a.raw
187
+ if a.flags & FLAG_CSTR:
188
+ slen = -1 if a.slen is None else a.slen
189
+ out += _SLEN.pack(slen)
190
+ if slen > 0:
191
+ blob = a.sbytes or b""
192
+ if len(blob) != slen:
193
+ raise ValueError("string length does not match slen")
194
+ out += blob
195
+ return bytes(out)
196
+
197
+
198
+ def unpack_args(blob: bytes) -> list[ArgRaw]:
199
+ if len(blob) < _ARG_HEAD.size:
200
+ raise ValueError("argument blob shorter than a header")
201
+ n, _pad = _ARG_HEAD.unpack_from(blob, 0)
202
+ i = _ARG_HEAD.size
203
+ out = []
204
+ for _ in range(n):
205
+ if i + _PARAM.size > len(blob):
206
+ raise ValueError("truncated argument")
207
+ off, size, flags = _PARAM.unpack_from(blob, i)
208
+ i += _PARAM.size
209
+ raw = b""
210
+ if size:
211
+ if i + size > len(blob):
212
+ raise ValueError("truncated argument bytes")
213
+ raw = blob[i:i + size]
214
+ i += size
215
+ slen = None
216
+ sbytes = None
217
+ if flags & FLAG_CSTR:
218
+ if i + _SLEN.size > len(blob):
219
+ raise ValueError("truncated string length")
220
+ slen = _SLEN.unpack_from(blob, i)[0]
221
+ i += _SLEN.size
222
+ if slen > 0:
223
+ if i + slen > len(blob):
224
+ raise ValueError("truncated string bytes")
225
+ sbytes = blob[i:i + slen]
226
+ i += slen
227
+ out.append(ArgRaw(off, size, flags, raw, slen, sbytes))
228
+ return out
229
+
230
+
231
+ @dataclass(frozen=True)
232
+ class Rec:
233
+ kind: int
234
+ seq: int
235
+ ts: int
236
+ a: int
237
+ b: int
238
+ c: int
239
+ d: int
240
+ extra: bytes
241
+
242
+
243
+ def write_thread(path, tid: int, recs: list[Rec]) -> None:
244
+ out = bytearray(_THREAD_HEAD.pack(MAGIC_THREAD, tid))
245
+ for r in recs:
246
+ out += _REC.pack(r.kind, r.seq, r.ts, r.a, r.b, r.c, r.d,
247
+ len(r.extra))
248
+ out += r.extra
249
+ with open(path, "wb") as fh:
250
+ fh.write(out)
251
+
252
+
253
+ def read_thread(path) -> tuple[int, list[Rec]]:
254
+ data = open(path, "rb").read()
255
+ if len(data) < _THREAD_HEAD.size:
256
+ raise ValueError(f"{path}: thread file shorter than a header")
257
+ magic, tid = _THREAD_HEAD.unpack_from(data, 0)
258
+ if magic != MAGIC_THREAD:
259
+ raise ValueError(f"{path}: not a thread spool")
260
+ out = []
261
+ i = _THREAD_HEAD.size
262
+ while i < len(data):
263
+ if i + _REC.size > len(data):
264
+ raise ValueError(f"{path}: truncated record header")
265
+ kind, seq, ts, a, b, c, d, n = _REC.unpack_from(data, i)
266
+ i += _REC.size
267
+ if i + n > len(data):
268
+ raise ValueError(f"{path}: truncated record extra")
269
+ out.append(Rec(kind, seq, ts, a, b, c, d, data[i:i + n]))
270
+ i += n
271
+ return tid, out
sensorium/c/pkg.py ADDED
@@ -0,0 +1,187 @@
1
+ """Where the C runtime lives, and the object file a link needs.
2
+
3
+ `locate` finds the directory that contains ``rt/sensorium_c_rt.c``.
4
+ `runtime_object` compiles it, once, with the flags the runtime was
5
+ measured with. The compiler wrapper is often the ``gcc`` on ``PATH``
6
+ while this runs, so the build below skips that shim and calls a real
7
+ ``gcc``. A second copy of the object in one link is a duplicate symbol;
8
+ callers check for the path before adding it.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ import subprocess
14
+ from pathlib import Path
15
+
16
+ from sensorium import paths
17
+
18
+ _RUNTIME_C = Path("rt") / "sensorium_c_rt.c"
19
+ _RUNTIME_O = Path("rt") / "sensorium_c_rt.o"
20
+ _COMPILE = (
21
+ "-O2", "-g", "-fno-omit-frame-pointer", "-fPIC",
22
+ "-fno-instrument-functions",
23
+ "-Wall", "-Wextra", "-Wno-frame-address", "-c",
24
+ )
25
+
26
+
27
+ class PackageError(Exception):
28
+ """The runtime source is missing, or ``gcc`` could not compile it."""
29
+
30
+
31
+ def locate() -> Path:
32
+ """Directory that contains ``rt/sensorium_c_rt.c``.
33
+
34
+ An editable install lives in the repo, so walking from this file up
35
+ to a directory that contains ``c/rt/sensorium_c_rt.c`` finds it. A
36
+ wheel that cannot see the checkout is checked second, at
37
+ ``sensorium/_c`` beside the installed package (the same shape as
38
+ ``sensorium/_typescript``).
39
+ """
40
+ looked: list[str] = []
41
+ here = Path(__file__).resolve().parent
42
+ for directory in (here, *here.parents):
43
+ candidate = directory / "c" / _RUNTIME_C
44
+ looked.append(str(candidate))
45
+ if candidate.is_file():
46
+ return candidate.parent.parent
47
+ wheel = _wheel_source()
48
+ if wheel is not None:
49
+ looked.append(str(wheel))
50
+ if wheel.is_file():
51
+ return wheel.parent.parent
52
+ raise PackageError(
53
+ "cannot find the C runtime rt/sensorium_c_rt.c. Looked for: "
54
+ + "; ".join(looked))
55
+
56
+
57
+ def _wheel_source() -> Path | None:
58
+ """``sensorium/_c/rt/sensorium_c_rt.c`` inside an installed package.
59
+
60
+ ``None`` when this process has no importable ``sensorium`` package
61
+ file to start from (the walk above is then the only place we looked).
62
+ """
63
+ try:
64
+ import sensorium
65
+ except ImportError:
66
+ return None
67
+ origin = getattr(sensorium, "__file__", None)
68
+ if not origin:
69
+ return None
70
+ return Path(origin).resolve().parent / "_c" / _RUNTIME_C
71
+
72
+
73
+ def runtime_object() -> Path:
74
+ """Compiled ``sensorium_c_rt.o``, rebuilding when it is older than the .c.
75
+
76
+ The object is cached next to the source when that directory is
77
+ writable, and otherwise under ``<trace root>/c-rt/``.
78
+ """
79
+ root = locate()
80
+ src = root / _RUNTIME_C
81
+ beside = root / _RUNTIME_O
82
+ if _fresh(beside, src):
83
+ return beside
84
+ if _writable(beside.parent):
85
+ try:
86
+ _compile(src, beside)
87
+ return beside
88
+ except OSError:
89
+ pass
90
+ cache_dir = _cache_dir()
91
+ cached = cache_dir / "sensorium_c_rt.o"
92
+ if _fresh(cached, src):
93
+ return cached
94
+ _compile(src, cached)
95
+ return cached
96
+
97
+
98
+ def _cache_dir() -> Path:
99
+ """``<trace root>/c-rt``, created 0700 one level at a time.
100
+
101
+ ``Path.mkdir(parents=True, mode=...)`` applies the mode only to the
102
+ leaf, so a single call would leave the store root (where
103
+ ``redaction.key`` lives) at the default. An existing directory is
104
+ not chmod'ed.
105
+ """
106
+ root = paths.trace_root()
107
+ root.mkdir(parents=True, exist_ok=True, mode=0o700)
108
+ cache = root / "c-rt"
109
+ cache.mkdir(exist_ok=True, mode=0o700)
110
+ return cache
111
+
112
+
113
+ def _fresh(obj: Path, src: Path) -> bool:
114
+ if not obj.is_file():
115
+ return False
116
+ try:
117
+ return obj.stat().st_mtime >= src.stat().st_mtime
118
+ except OSError:
119
+ return False
120
+
121
+
122
+ def _writable(directory: Path) -> bool:
123
+ return os.access(directory, os.W_OK | os.X_OK)
124
+
125
+
126
+ def _compile(src: Path, dest: Path) -> None:
127
+ dest.parent.mkdir(parents=True, exist_ok=True)
128
+ tmp = dest.with_name(f".{dest.name}.{os.getpid()}.tmp")
129
+ cmd = [_real_gcc(), *_COMPILE, str(src), "-o", str(tmp)]
130
+ try:
131
+ completed = subprocess.run(cmd, capture_output=True, text=True)
132
+ except OSError as e:
133
+ tmp.unlink(missing_ok=True)
134
+ raise PackageError(
135
+ f"cannot run {cmd[0]} to compile {src}: {e.strerror}") from e
136
+ if completed.returncode != 0:
137
+ tmp.unlink(missing_ok=True)
138
+ detail = (completed.stderr or completed.stdout or "").strip()
139
+ raise PackageError(
140
+ f"gcc failed to compile {src} (exit {completed.returncode})"
141
+ + (f": {detail}" if detail else ""))
142
+ try:
143
+ os.replace(tmp, dest)
144
+ except OSError:
145
+ tmp.unlink(missing_ok=True)
146
+ raise
147
+
148
+
149
+ def _real_gcc() -> str:
150
+ """A ``gcc`` that is not this recorder's shim.
151
+
152
+ During ``sensorium c run`` the shim directory is first on ``PATH``.
153
+ Compiling the runtime with that ``gcc`` would re-enter the wrapper.
154
+ """
155
+ skipped = set()
156
+ root = os.environ.get("SENSORIUM_C_ROOT")
157
+ if root:
158
+ skipped.add(os.path.abspath(os.path.join(root, "bin")))
159
+ for directory in os.environ.get("PATH", "").split(os.pathsep):
160
+ if not directory:
161
+ directory = os.curdir
162
+ if os.path.abspath(directory) in skipped:
163
+ continue
164
+ candidate = os.path.join(directory, "gcc")
165
+ if _usable_gcc(candidate):
166
+ return os.path.abspath(candidate)
167
+ fallback = "/usr/bin/gcc"
168
+ if _usable_gcc(fallback):
169
+ return fallback
170
+ raise PackageError(
171
+ "gcc was not found on PATH; the C runtime cannot be built")
172
+
173
+
174
+ def _usable_gcc(path: str) -> bool:
175
+ if not (os.path.isfile(path) and os.access(path, os.X_OK)):
176
+ return False
177
+ return not _looks_like_wrapper(path)
178
+
179
+
180
+ def _looks_like_wrapper(path: str) -> bool:
181
+ """True for the Python shims this driver writes, not for a real gcc."""
182
+ try:
183
+ with open(path, "rb") as fh:
184
+ head = fh.read(400)
185
+ except OSError:
186
+ return False
187
+ return b"sensorium.c.cc" in head or b"sensorium-cc" in head