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/store/db.py ADDED
@@ -0,0 +1,284 @@
1
+ """Trace file creation, opening, and run-metadata access."""
2
+ import importlib.metadata
3
+ import json
4
+ import os
5
+ import sqlite3
6
+ from pathlib import Path
7
+
8
+ from sensorium import paths
9
+
10
+ TRACE_FORMAT = 4
11
+
12
+ # The languages this sensorium has a vocabulary column for
13
+ # (`query/vocab._TABLES`). A trace naming any other is refused at open,
14
+ # ONCE, rather than narrated in another language's words by every renderer
15
+ # in turn: until S5 an unknown `lang` fell back to the Python column, which
16
+ # told a reader of such a trace about `asyncio tasks` and `python ?`. The
17
+ # order is the order the columns were written, and it is the order the
18
+ # refusal lists them in.
19
+ KNOWN_LANGS = ("python", "rust", "typescript", "c")
20
+
21
+ # Keys a finalized format-4 trace MUST carry (spec §5.1). Every reader
22
+ # defaults these when absent; on a trace that claims `incomplete = False`
23
+ # that default would print as a measured zero, so absence is refused here,
24
+ # once, instead of guarded at every `.get(key, 0)`.
25
+ REQUIRED_META = ("run_id", "argv", "cwd", "env_hash", "start_ts", "end_ts",
26
+ "exit_status", "main_thread_ident", "fingerprint_basis",
27
+ "truncated_count", "source_hashes",
28
+ "recorder", "lang", "capabilities")
29
+ # Witness keys, required only when the recorder declares the capability
30
+ # that produces them. A capability declared False means "not witnessed",
31
+ # which every reader prints as such -- never as zero, never as "predates".
32
+ WITNESS_KEYS = {"threads": ("threads_started", "live_threads"),
33
+ "children": ("children", "spawn_syscalls", "audit_errors"),
34
+ "stdin": ("stdin_consumed",)}
35
+
36
+
37
+ class TraceFormatError(Exception):
38
+ """A trace this sensorium must not read: written by a NEWER sensorium,
39
+ or a format-4 trace that claims to be finalized without the keys the
40
+ format requires.
41
+
42
+ `trace_format` is stamped at creation; a higher value means the file's
43
+ layout may differ from what these queries assume. A trace with no
44
+ `trace_format` at all predates the key and is read as format 1. Format
45
+ 2 (async attribution) added events.task_id, the tasks table and
46
+ CALL-payload keys. Format 3 (inspectable coroutines) added frames.kind,
47
+ the YIELD/RESUME event kinds, and task_fingerprints. Format 4 (the
48
+ trace-format contract, docs/TRACE-FORMAT.md) adds no column: it makes
49
+ `recorder`, `lang` and `capabilities` required meta, and requires the
50
+ finalize keys above on any trace that says `incomplete = False`, so a
51
+ second recorder can never render an absent record as a zero.
52
+ """
53
+
54
+ SCHEMA = """
55
+ CREATE TABLE meta (
56
+ key TEXT PRIMARY KEY,
57
+ value TEXT NOT NULL
58
+ );
59
+ CREATE TABLE code_objects (
60
+ id INTEGER PRIMARY KEY,
61
+ file TEXT NOT NULL,
62
+ qualname TEXT NOT NULL,
63
+ firstlineno INTEGER NOT NULL
64
+ );
65
+ CREATE TABLE frames (
66
+ id INTEGER PRIMARY KEY,
67
+ parent_id INTEGER,
68
+ code_id INTEGER NOT NULL,
69
+ call_event_id INTEGER NOT NULL,
70
+ return_event_id INTEGER,
71
+ depth INTEGER NOT NULL,
72
+ thread_id INTEGER NOT NULL,
73
+ closed_by TEXT,
74
+ unwind_exc TEXT,
75
+ kind TEXT
76
+ );
77
+ CREATE TABLE events (
78
+ id INTEGER PRIMARY KEY,
79
+ ts_ns INTEGER NOT NULL,
80
+ thread_id INTEGER NOT NULL,
81
+ kind TEXT NOT NULL,
82
+ frame_id INTEGER,
83
+ code_id INTEGER,
84
+ line INTEGER,
85
+ payload TEXT,
86
+ task_id INTEGER
87
+ );
88
+ CREATE TABLE output (
89
+ id INTEGER PRIMARY KEY,
90
+ after_event_id INTEGER NOT NULL,
91
+ stream TEXT NOT NULL,
92
+ data TEXT NOT NULL
93
+ );
94
+ CREATE TABLE tasks (
95
+ id INTEGER PRIMARY KEY,
96
+ name TEXT,
97
+ thread_id INTEGER NOT NULL
98
+ );
99
+ CREATE TABLE fingerprints (
100
+ thread_id INTEGER PRIMARY KEY,
101
+ hash TEXT NOT NULL,
102
+ n_events INTEGER NOT NULL
103
+ );
104
+ CREATE TABLE task_fingerprints (
105
+ task_id INTEGER PRIMARY KEY,
106
+ name TEXT,
107
+ hash TEXT NOT NULL,
108
+ n_events INTEGER NOT NULL
109
+ );
110
+ CREATE INDEX idx_events_code ON events(code_id);
111
+ CREATE INDEX idx_events_frame ON events(frame_id);
112
+ CREATE INDEX idx_events_kind ON events(kind);
113
+ CREATE INDEX idx_frames_code ON frames(code_id);
114
+ """
115
+
116
+
117
+ def _create_parent(parent: Path) -> None:
118
+ """The directory a trace is about to be written into, 0700 (R35).
119
+
120
+ This was `parent.mkdir(parents=True, exist_ok=True)` -- the last
121
+ default-mode creator left inside the store after E16 part A. It is
122
+ normally preceded by `paths.traces_dir()`, so the hole was latent (E16
123
+ read `traces/` at 0700), but a caller reaching here first would have
124
+ made the directory holding every trace on the box world-listable.
125
+
126
+ Routed through `paths.traces_dir()` when the parent IS the store's own
127
+ `traces/`, so that directory has ONE owner and one rule. Otherwise the
128
+ same two-level idiom that function documents: `mkdir(parents=True,
129
+ mode=...)` applies the mode to the directory it NAMES and gives every
130
+ parent it creates the default, so the level above is created explicitly
131
+ too. An existing directory is never chmod'ed.
132
+
133
+ The comparison is against `trace_root() / "traces"` and not against
134
+ `traces_dir()`, because the latter CREATES what it names: asking it
135
+ where the store is would mint a `~/.sensorium` for a caller writing a
136
+ trace somewhere else entirely. `RuntimeError` is `Path.home()`'s answer
137
+ when there is no home and `SENSORIUM_DIR` is unset -- then this is not
138
+ the store's `traces/` by definition.
139
+ """
140
+ try:
141
+ is_the_store = parent == paths.trace_root() / "traces"
142
+ except RuntimeError:
143
+ is_the_store = False
144
+ if is_the_store:
145
+ paths.traces_dir()
146
+ return
147
+ parent.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
148
+ parent.mkdir(exist_ok=True, mode=0o700)
149
+
150
+
151
+ def create_trace(path: Path) -> sqlite3.Connection:
152
+ path = Path(path)
153
+ _create_parent(path.parent)
154
+ # The trace exists at 0600 from its first instant. sqlite would create
155
+ # it 0666-under-the-umask -- 0644 on most boxes -- and a trace holds the
156
+ # whole recorded environment, so the window between "file appears" and
157
+ # "we chmod it" is the window the spec closes (design §5.5).
158
+ #
159
+ # No `O_EXCL`: `ts/ingest.py` reserves a run id by creating the file
160
+ # itself, `O_EXCL`, and hands TraceWriter the zero-byte result, which
161
+ # sqlite opens as a new database exactly as it would its own. The guard
162
+ # against an explicit `--run-id` colliding with a real trace stays where
163
+ # it was, in `boot.run_target`'s `trace_path.exists()` refusal.
164
+ #
165
+ # `fchmod` behind the open because `O_CREAT`'s mode applies only when
166
+ # the open CREATES the file: on ingest's reserved file it is ignored,
167
+ # and that file was made 0600 by its own creator -- fchmod is what makes
168
+ # this function's promise hold whichever of the two paths arrived.
169
+ fd = os.open(path, os.O_WRONLY | os.O_CREAT, 0o600)
170
+ try:
171
+ os.fchmod(fd, 0o600)
172
+ finally:
173
+ os.close(fd)
174
+ # The tracer flushes on whichever thread fills the batch, so the write
175
+ # connection outlives its creating thread. TraceWriter serialises every
176
+ # access under its own lock, which is the invariant check_same_thread
177
+ # approximates. (open_trace stays checked: the read path is single-threaded.)
178
+ conn = sqlite3.connect(path, check_same_thread=False)
179
+ conn.execute("PRAGMA journal_mode=WAL")
180
+ conn.executescript(SCHEMA)
181
+ set_meta(conn, "trace_format", TRACE_FORMAT)
182
+ conn.commit()
183
+ return conn
184
+
185
+
186
+ def missing_required(conn: sqlite3.Connection) -> list[str]:
187
+ """Required keys absent from a trace that claims to be finalized, in
188
+ a stable order; [] when nothing is missing or the claim is not made.
189
+
190
+ A `capabilities` that is present but not a dict counts as absent. This
191
+ is a validation boundary for a recorder nobody here wrote: a list, a
192
+ string or a null is not a declaration this reader can act on, and
193
+ reporting it by name is the whole point of the mechanism. Reading it
194
+ anyway would raise AttributeError out of `open_trace`, which the CLI
195
+ does not catch, or -- for null -- pass silently and be rendered
196
+ downstream as the full Python capability set.
197
+ """
198
+ if get_meta(conn, "incomplete") is not False:
199
+ return []
200
+ present = {k for (k,) in conn.execute("SELECT key FROM meta")}
201
+ missing = [k for k in REQUIRED_META if k not in present]
202
+ caps = get_meta(conn, "capabilities")
203
+ if not isinstance(caps, dict):
204
+ if "capabilities" not in missing:
205
+ missing.append("capabilities")
206
+ caps = {}
207
+ for cap, keys in WITNESS_KEYS.items():
208
+ if caps.get(cap):
209
+ missing += [k for k in keys if k not in present]
210
+ return missing
211
+
212
+
213
+ def open_trace(path: Path) -> sqlite3.Connection:
214
+ path = Path(path)
215
+ if not path.exists():
216
+ raise FileNotFoundError(f"no trace at {path}")
217
+ conn = sqlite3.connect(path)
218
+ fmt = get_meta(conn, "trace_format")
219
+ if fmt is not None and fmt > TRACE_FORMAT:
220
+ conn.close()
221
+ raise TraceFormatError(
222
+ f"{path} is trace format {fmt}, newer than this sensorium reads "
223
+ f"(up to {TRACE_FORMAT}); upgrade sensorium to open it")
224
+ if fmt is not None and fmt >= 4:
225
+ missing = missing_required(conn)
226
+ if missing:
227
+ who = _recorder_name(conn)
228
+ conn.close()
229
+ raise TraceFormatError(
230
+ f"{path} claims to be finalized (incomplete = false) but "
231
+ f"lacks required meta {', '.join(missing)} -- written by "
232
+ f"{who}; format 4 refuses rather than read those as zero")
233
+ # A `lang` no reader has words for, refused HERE and nowhere else: one
234
+ # choke point every command goes through, so `info`, `tree`, `grep` and
235
+ # `diff` cannot answer it differently -- and so no renderer has to
236
+ # remember the check. An ABSENT `lang` is not unknown: it predates the
237
+ # key and is the Python recorder's, which is what `Trace.lang` reads it
238
+ # as. `cli.main` turns this into `error: ...` at exit 2.
239
+ lang = get_meta(conn, "lang")
240
+ if lang is not None and lang not in KNOWN_LANGS:
241
+ who = _recorder_name(conn)
242
+ conn.close()
243
+ raise TraceFormatError(
244
+ f"{path} was written by {who} for lang {lang!r}, which this "
245
+ f"sensorium ({_version()}) has no vocabulary for "
246
+ f"({', '.join(KNOWN_LANGS)}); upgrade sensorium to read it")
247
+ return conn
248
+
249
+
250
+ def _recorder_name(conn: sqlite3.Connection) -> str:
251
+ """Who wrote this trace, for a refusal to name. `meta["recorder"]` when
252
+ it is a name, and the words for its absence otherwise -- absent, null
253
+ or not a string are one case to a reader: nobody said."""
254
+ who = get_meta(conn, "recorder")
255
+ if not isinstance(who, str) or not who:
256
+ return "an unnamed recorder"
257
+ return who
258
+
259
+
260
+ def _version() -> str:
261
+ """This sensorium's own version, for the sentence that says an upgrade
262
+ is what would read the file. `?` from a source tree that was never
263
+ installed: a refusal must not fail while explaining itself."""
264
+ try:
265
+ return importlib.metadata.version("sensorium-trace")
266
+ except importlib.metadata.PackageNotFoundError:
267
+ return "?"
268
+
269
+
270
+ def set_meta(conn: sqlite3.Connection, key: str, value) -> None:
271
+ conn.execute(
272
+ "INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)",
273
+ (key, json.dumps(value, separators=(",", ":"))),
274
+ )
275
+
276
+
277
+ def get_meta(conn: sqlite3.Connection, key: str, default=None):
278
+ row = conn.execute("SELECT value FROM meta WHERE key = ?", (key,)).fetchone()
279
+ return default if row is None else json.loads(row[0])
280
+
281
+
282
+ def all_meta(conn: sqlite3.Connection) -> dict:
283
+ return {k: json.loads(v)
284
+ for k, v in conn.execute("SELECT key, value FROM meta")}
sensorium/store/gc.py ADDED
@@ -0,0 +1,360 @@
1
+ """Delete traces the store no longer needs to keep.
2
+
3
+ ``gc`` removes a trace when it is older than the age limit, past the keep
4
+ count, or what has to go to bring the store under its size budget. A pinned
5
+ run and the most recent run are never deleted, even when that leaves the
6
+ store over the count or the budget. ``--dry-run`` prints the same set and
7
+ deletes nothing.
8
+
9
+ Pins live in ``$SENSORIUM_DIR/pins.json`` (``{"runs": [...]}``, mode 0600),
10
+ outside any trace file. Automatic cleanup after a recording calls
11
+ ``maybe_auto``, which is a no-op unless a retention rule is set in the
12
+ environment or the config file, and which never changes the recorded
13
+ program's exit status.
14
+ """
15
+ from __future__ import annotations
16
+
17
+ import json
18
+ import os
19
+ import sqlite3
20
+ import time
21
+ from dataclasses import dataclass
22
+ from pathlib import Path
23
+
24
+ from sensorium.limits import LimitsError, store_policy
25
+
26
+
27
+ class GcError(ValueError):
28
+ """A retention rule or a pins file that cannot be acted on."""
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class Item:
33
+ path: Path
34
+ run_id: str
35
+ mtime: float
36
+ size: int
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class Plan:
41
+ victims: tuple[Item, ...]
42
+ kept: tuple[Item, ...]
43
+ protected: frozenset[str]
44
+ total_before: int
45
+
46
+
47
+ def format_bytes(n: int) -> str:
48
+ n = int(n)
49
+ for unit, step in (("GiB", 1024 ** 3), ("MiB", 1024 ** 2), ("KiB", 1024)):
50
+ if abs(n) >= step:
51
+ return f"{n / step:.1f} {unit}"
52
+ return f"{n} B"
53
+
54
+
55
+ def _root(environ: dict | None = None) -> Path:
56
+ env = os.environ if environ is None else environ
57
+ raw = env.get("SENSORIUM_DIR")
58
+ return Path(raw) if raw else Path.home() / ".sensorium"
59
+
60
+
61
+ def _pins_path(root: Path) -> Path:
62
+ return root / "pins.json"
63
+
64
+
65
+ def load_pins(root: Path | None = None) -> list[str]:
66
+ """Run ids ``gc`` must not delete. A missing file is an empty list.
67
+
68
+ A file that exists and is not ``{"runs": [...]}`` is an error: treating
69
+ it as empty would delete a run the user had pinned.
70
+ """
71
+ path = _pins_path(root or _root())
72
+ if not path.is_file():
73
+ return []
74
+ try:
75
+ data = json.loads(path.read_text(encoding="utf-8"))
76
+ except (OSError, json.JSONDecodeError) as e:
77
+ raise GcError(f"cannot read {path}: {e}") from e
78
+ if not isinstance(data, dict) or not isinstance(data.get("runs"), list):
79
+ raise GcError(f"{path} must be a JSON object with a runs list")
80
+ runs = []
81
+ for item in data["runs"]:
82
+ if not isinstance(item, str) or not item or item != Path(item).name:
83
+ raise GcError(f"{path} has a run id that is not a single name")
84
+ runs.append(item)
85
+ return runs
86
+
87
+
88
+ def save_pins(runs: list[str], root: Path | None = None) -> Path:
89
+ root = root or _root()
90
+ root.mkdir(parents=True, exist_ok=True, mode=0o700)
91
+ path = _pins_path(root)
92
+ payload = json.dumps({"runs": runs}, indent=2) + "\n"
93
+ tmp = path.with_suffix(".json.tmp")
94
+ fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
95
+ try:
96
+ os.write(fd, payload.encode("utf-8"))
97
+ os.fsync(fd)
98
+ finally:
99
+ os.close(fd)
100
+ os.replace(tmp, path)
101
+ os.chmod(path, 0o600)
102
+ return path
103
+
104
+
105
+ def _trace_size(path: Path) -> int:
106
+ total = path.stat().st_size
107
+ for ext in ("-wal", "-shm"):
108
+ side = Path(str(path) + ext)
109
+ if side.is_file():
110
+ total += side.stat().st_size
111
+ return total
112
+
113
+
114
+ def list_traces(root: Path | None = None) -> list[Item]:
115
+ """``*.db`` files already in the store. Does not create the directory."""
116
+ directory = (root or _root()) / "traces"
117
+ if not directory.is_dir():
118
+ return []
119
+ base = directory.resolve()
120
+ found = []
121
+ for path in directory.glob("*.db"):
122
+ try:
123
+ resolved = path.resolve()
124
+ except OSError:
125
+ continue
126
+ if resolved.parent != base:
127
+ continue
128
+ try:
129
+ stat = path.stat()
130
+ except OSError:
131
+ continue
132
+ found.append(Item(path, path.stem, stat.st_mtime, _trace_size(path)))
133
+ return found
134
+
135
+
136
+ def plan(policy, *, root: Path | None = None,
137
+ now: float | None = None) -> Plan:
138
+ """Which traces ``policy`` would delete. Reads pins; deletes nothing."""
139
+ root = root or _root()
140
+ items = list_traces(root)
141
+ pins = set(load_pins(root))
142
+ if not items:
143
+ return Plan((), (), frozenset(pins), 0)
144
+ newest_first = sorted(items, key=lambda item: (item.mtime, item.run_id),
145
+ reverse=True)
146
+ protected = set(pins)
147
+ protected.add(newest_first[0].run_id)
148
+ victims: dict[str, Item] = {}
149
+ moment = time.time() if now is None else now
150
+ if policy.older_than is not None:
151
+ cutoff = moment - policy.older_than
152
+ for item in newest_first:
153
+ if item.run_id not in protected and item.mtime < cutoff:
154
+ victims[item.run_id] = item
155
+ if policy.keep is not None:
156
+ kept = 0
157
+ for item in newest_first:
158
+ if item.run_id in victims:
159
+ continue
160
+ if kept < policy.keep:
161
+ kept += 1
162
+ continue
163
+ if item.run_id not in protected:
164
+ victims[item.run_id] = item
165
+ remaining = [item for item in newest_first if item.run_id not in victims]
166
+ if policy.max_bytes is not None:
167
+ total = sum(item.size for item in remaining)
168
+ for item in reversed(remaining):
169
+ if total <= policy.max_bytes:
170
+ break
171
+ if item.run_id in protected:
172
+ continue
173
+ victims[item.run_id] = item
174
+ total -= item.size
175
+ victim_list = tuple(item for item in reversed(newest_first)
176
+ if item.run_id in victims)
177
+ kept_list = tuple(item for item in newest_first
178
+ if item.run_id not in victims)
179
+ return Plan(victim_list, kept_list, frozenset(protected),
180
+ sum(item.size for item in items))
181
+
182
+
183
+ def _unlink(path: Path) -> None:
184
+ path.unlink(missing_ok=True)
185
+ for ext in ("-wal", "-shm"):
186
+ Path(str(path) + ext).unlink(missing_ok=True)
187
+
188
+
189
+ def vacuum(path: Path) -> None:
190
+ """Checkpoint and rebuild one remaining trace so deleted pages are gone."""
191
+ conn = sqlite3.connect(path)
192
+ try:
193
+ conn.isolation_level = None
194
+ conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
195
+ conn.execute("VACUUM")
196
+ finally:
197
+ conn.close()
198
+
199
+
200
+ def apply(chosen: Plan, *, dry_run: bool = False) -> tuple[int, int, list[str]]:
201
+ """Delete ``chosen.victims``. Returns ``(count, bytes, vacuum notes)``.
202
+
203
+ Dry-run deletes nothing and does not vacuum. Vacuum runs only after a
204
+ real deletion, and only on the traces that remain.
205
+ """
206
+ if dry_run or not chosen.victims:
207
+ return 0, 0, []
208
+ freed = 0
209
+ for item in chosen.victims:
210
+ freed += item.size
211
+ _unlink(item.path)
212
+ notes = []
213
+ for item in chosen.kept:
214
+ try:
215
+ vacuum(item.path)
216
+ except sqlite3.Error as e:
217
+ notes.append(f"{item.run_id}: {e}")
218
+ return len(chosen.victims), freed, notes
219
+
220
+
221
+ def render(chosen: Plan, *, dry_run: bool, deleted: int, freed: int,
222
+ notes: list[str]) -> str:
223
+ if not chosen.victims:
224
+ return "nothing to delete"
225
+ lines = []
226
+ verb = "would delete" if dry_run else "deleted"
227
+ shown = chosen.victims if dry_run else chosen.victims
228
+ for item in shown:
229
+ lines.append(f"{verb} {item.run_id} ({format_bytes(item.size)})")
230
+ if dry_run:
231
+ total = sum(item.size for item in chosen.victims)
232
+ lines.append(
233
+ f"dry-run: {len(chosen.victims)} traces, {format_bytes(total)}")
234
+ else:
235
+ lines.append(f"deleted {deleted} traces, freed {format_bytes(freed)}")
236
+ return "\n".join(lines)
237
+
238
+
239
+ def maybe_auto(environ: dict | None = None) -> str | None:
240
+ """Apply the configured retention rule. ``None`` when there is no rule
241
+ or nothing to delete. A failure here is the caller's to report."""
242
+ policy = store_policy(environ=environ)
243
+ if policy.is_empty():
244
+ return None
245
+ chosen = plan(policy, root=_root(environ))
246
+ if not chosen.victims:
247
+ return None
248
+ deleted, freed, _notes = apply(chosen)
249
+ if not deleted:
250
+ return None
251
+ return (f"sensorium: gc deleted {deleted} traces, "
252
+ f"freed {format_bytes(freed)}")
253
+
254
+
255
+ def _policy_from_args(args):
256
+ from sensorium.limits import parse_duration
257
+ older = None if args.older_than is None else parse_duration(args.older_than)
258
+ return store_policy(max_bytes=args.max_bytes, keep=args.keep,
259
+ older_than=older)
260
+
261
+
262
+ def gc_main(args) -> int:
263
+ try:
264
+ policy = _policy_from_args(args)
265
+ except (LimitsError, GcError) as e:
266
+ print(f"error: {e}", file=_err())
267
+ return 2
268
+ if policy.is_empty():
269
+ print("error: gc needs --older-than, --keep, or --max-bytes "
270
+ "(or the same rule in the environment or the config file)",
271
+ file=_err())
272
+ return 2
273
+ try:
274
+ chosen = plan(policy)
275
+ except GcError as e:
276
+ print(f"error: {e}", file=_err())
277
+ return 2
278
+ deleted, freed, notes = apply(chosen, dry_run=args.dry_run)
279
+ print(render(chosen, dry_run=args.dry_run, deleted=deleted, freed=freed,
280
+ notes=notes))
281
+ for note in notes:
282
+ print(f"sensorium: vacuum failed: {note}", file=_err())
283
+ return 0
284
+
285
+
286
+ def pin_main(args) -> int:
287
+ from sensorium import paths
288
+ try:
289
+ path = paths.find_trace(args.run)
290
+ runs = load_pins()
291
+ except (paths.TraceLookupError, GcError) as e:
292
+ print(f"error: {e}", file=_err())
293
+ return 2
294
+ run_id = path.stem
295
+ if run_id not in runs:
296
+ runs.append(run_id)
297
+ save_pins(runs)
298
+ print(f"pinned: {run_id}")
299
+ return 0
300
+
301
+
302
+ def unpin_main(args) -> int:
303
+ from sensorium import paths
304
+ try:
305
+ runs = load_pins()
306
+ except GcError as e:
307
+ print(f"error: {e}", file=_err())
308
+ return 2
309
+ target = args.run
310
+ try:
311
+ target = paths.find_trace(args.run).stem
312
+ except paths.TraceLookupError:
313
+ target = args.run
314
+ if target not in runs:
315
+ print(f"error: {args.run!r} is not pinned", file=_err())
316
+ return 2
317
+ save_pins([run for run in runs if run != target])
318
+ print(f"unpinned: {target}")
319
+ return 0
320
+
321
+
322
+ def _err():
323
+ import sys
324
+ return sys.stderr
325
+
326
+
327
+ def add_parsers(sub) -> None:
328
+ gc = sub.add_parser(
329
+ "gc", help="delete traces the store no longer needs",
330
+ description="Removes traces by age, by how many to keep, or by a "
331
+ "total size. A pinned trace and the most recent trace "
332
+ "are kept even when that exceeds the rule. With no rule "
333
+ "on the command, in the environment, or in the config "
334
+ "file, nothing is deleted.",
335
+ epilog="exit: 0 done, 2 fix the call")
336
+ gc.add_argument("--dry-run", action="store_true",
337
+ help="print the traces that would be deleted and delete nothing")
338
+ gc.add_argument("--older-than", default=None,
339
+ help="delete traces older than this duration (30d, 12h, 2w, 45m)")
340
+ gc.add_argument("--keep", default=None,
341
+ help="how many of the newest traces to keep; must be >= 1")
342
+ gc.add_argument("--max-bytes", default=None,
343
+ help="delete the oldest traces until the store is under this size")
344
+ gc.set_defaults(func=gc_main)
345
+
346
+ pin = sub.add_parser(
347
+ "pin", help="keep one trace from gc",
348
+ description="Records the run id in the store's pins file. gc never "
349
+ "deletes a pinned trace.",
350
+ epilog="exit: 0 pinned, 2 fix the call")
351
+ pin.add_argument("run", help="a run id, a unique prefix, or last")
352
+ pin.set_defaults(func=pin_main)
353
+
354
+ unpin = sub.add_parser(
355
+ "unpin", help="drop a trace from the pins file",
356
+ description="Removes the run id from the store's pins file. The "
357
+ "trace itself is left where it is.",
358
+ epilog="exit: 0 unpinned, 2 fix the call")
359
+ unpin.add_argument("run", help="a run id, a unique prefix, or last")
360
+ unpin.set_defaults(func=unpin_main)