rolloutdiff 0.1.0__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 (62) hide show
  1. rolloutdiff/__init__.py +130 -0
  2. rolloutdiff/_aria_replay.py +346 -0
  3. rolloutdiff/_benchmarks/m0-2026-11-06.json +318 -0
  4. rolloutdiff/_dependence.py +195 -0
  5. rolloutdiff/_feature_values.py +79 -0
  6. rolloutdiff/_replay_container.py +568 -0
  7. rolloutdiff/_report_validation.py +758 -0
  8. rolloutdiff/_retrospective_policy.py +33 -0
  9. rolloutdiff/_sampling.py +127 -0
  10. rolloutdiff/_series_validation.py +67 -0
  11. rolloutdiff/_watch_report.py +436 -0
  12. rolloutdiff/_watch_storage.py +800 -0
  13. rolloutdiff/_web/assets/index-D8uGEQ9w.js +12 -0
  14. rolloutdiff/_web/assets/index-Dvo9nx9b.css +1 -0
  15. rolloutdiff/_web/assets/mona-sans-OFL.txt +93 -0
  16. rolloutdiff/_web/assets/mona-sans-latin-ext-wght-normal-BqSk0Z3x.woff2 +0 -0
  17. rolloutdiff/_web/assets/mona-sans-latin-wght-normal-Pz49MTQZ.woff2 +0 -0
  18. rolloutdiff/_web/assets/mona-sans-vietnamese-wght-normal-DsUdksa4.woff2 +0 -0
  19. rolloutdiff/_web/assets/third-party-notices.txt +112 -0
  20. rolloutdiff/_web/index.html +14 -0
  21. rolloutdiff/adapters.py +264 -0
  22. rolloutdiff/app.py +956 -0
  23. rolloutdiff/app_evidence.py +678 -0
  24. rolloutdiff/benchmark_reference.py +458 -0
  25. rolloutdiff/cli.py +1292 -0
  26. rolloutdiff/comparison.py +572 -0
  27. rolloutdiff/comparison_report.py +982 -0
  28. rolloutdiff/corroboration.py +287 -0
  29. rolloutdiff/detect.py +307 -0
  30. rolloutdiff/events.py +173 -0
  31. rolloutdiff/evidence.py +285 -0
  32. rolloutdiff/exemplars.py +240 -0
  33. rolloutdiff/features.py +823 -0
  34. rolloutdiff/html_report.py +726 -0
  35. rolloutdiff/inspect_logs.py +383 -0
  36. rolloutdiff/inspection.py +207 -0
  37. rolloutdiff/integrations.py +552 -0
  38. rolloutdiff/investigation.py +1146 -0
  39. rolloutdiff/notifications.py +406 -0
  40. rolloutdiff/pipeline.py +809 -0
  41. rolloutdiff/producer.py +663 -0
  42. rolloutdiff/prompt_mix.py +258 -0
  43. rolloutdiff/ranking.py +388 -0
  44. rolloutdiff/replay.py +589 -0
  45. rolloutdiff/replication.py +572 -0
  46. rolloutdiff/report.py +838 -0
  47. rolloutdiff/retrospective.py +386 -0
  48. rolloutdiff/schema.py +109 -0
  49. rolloutdiff/sensitivity.py +202 -0
  50. rolloutdiff/series.py +430 -0
  51. rolloutdiff/tool_features.py +422 -0
  52. rolloutdiff/trajectories.py +236 -0
  53. rolloutdiff/watch-compatibility.json +13 -0
  54. rolloutdiff/watch.py +742 -0
  55. rolloutdiff-0.1.0.dist-info/METADATA +158 -0
  56. rolloutdiff-0.1.0.dist-info/RECORD +62 -0
  57. rolloutdiff-0.1.0.dist-info/WHEEL +5 -0
  58. rolloutdiff-0.1.0.dist-info/entry_points.txt +2 -0
  59. rolloutdiff-0.1.0.dist-info/licenses/LICENSE +202 -0
  60. rolloutdiff-0.1.0.dist-info/licenses/frontend/public/assets/mona-sans-OFL.txt +93 -0
  61. rolloutdiff-0.1.0.dist-info/licenses/frontend/public/assets/third-party-notices.txt +112 -0
  62. rolloutdiff-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,406 @@
1
+ """Explicit, bounded delivery of public summaries from durable watch snapshots."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import http.client
6
+ import ipaddress
7
+ import math
8
+ import os
9
+ import re
10
+ import socket
11
+ import ssl
12
+ import time
13
+ from concurrent.futures import Future
14
+ from contextlib import suppress
15
+ from pathlib import Path
16
+ from threading import Thread, Timer
17
+ from urllib.parse import urlsplit
18
+
19
+ from ._watch_report import validate_watch_report
20
+ from ._watch_storage import _decode, _json, _open, _publish, _read, _sha, _stat
21
+ from .producer import _lock, _mkdir
22
+
23
+ _MAX_ARTIFACT_BYTES = 16 * 1024 * 1024
24
+ _MAX_PAYLOAD_BYTES = 256 * 1024
25
+ _MAX_RESPONSE_BYTES = 8 * 1024
26
+
27
+
28
+ def _read_bounded(path, limit):
29
+ with _open(path) as descriptor:
30
+ before = _stat(os.fstat(descriptor))
31
+ if before["size_bytes"] > limit:
32
+ raise ValueError("notification snapshot artifact exceeds its byte limit")
33
+ chunks = []
34
+ remaining = limit + 1
35
+ while remaining and (part := os.read(descriptor, min(remaining, 64 * 1024))):
36
+ chunks.append(part)
37
+ remaining -= len(part)
38
+ data = b"".join(chunks)
39
+ if (
40
+ len(data) > limit
41
+ or len(data) != before["size_bytes"]
42
+ or _stat(os.fstat(descriptor)) != before
43
+ ):
44
+ raise ValueError("notification snapshot artifact changed while reading")
45
+ return data
46
+
47
+
48
+ def _endpoint(url):
49
+ if not isinstance(url, str) or any(ord(character) < 33 for character in url):
50
+ raise ValueError("invalid notification endpoint")
51
+ try:
52
+ parsed = urlsplit(url)
53
+ host = parsed.hostname
54
+ port = parsed.port or (443 if parsed.scheme == "https" else 80)
55
+ if (
56
+ not host
57
+ or len(host) > 253
58
+ or parsed.username is not None
59
+ or parsed.password is not None
60
+ or parsed.fragment
61
+ ):
62
+ raise ValueError
63
+ if parsed.scheme == "http":
64
+ if not ipaddress.ip_address(host).is_loopback:
65
+ raise ValueError
66
+ elif parsed.scheme != "https":
67
+ raise ValueError
68
+ except ValueError:
69
+ raise ValueError(
70
+ "notification endpoint requires HTTPS or literal loopback HTTP without credentials"
71
+ ) from None
72
+ return (
73
+ parsed.scheme,
74
+ host,
75
+ port,
76
+ (parsed.path or "/") + ("?" + parsed.query if parsed.query else ""),
77
+ )
78
+
79
+
80
+ def _snapshot(path):
81
+ if (
82
+ path.name != "report.json"
83
+ or path.parent.parent.name != "commits"
84
+ or re.fullmatch(r"\d{12,}", path.parent.name) is None
85
+ ):
86
+ raise ValueError("notification requires a committed watch snapshot report")
87
+ report_bytes = _read_bounded(path, _MAX_ARTIFACT_BYTES)
88
+ manifest_bytes = _read_bounded(path.parent / "manifest.json", _MAX_ARTIFACT_BYTES)
89
+ journal_bytes = _read_bounded(path.parent / "journal.json", _MAX_ARTIFACT_BYTES)
90
+ report = validate_watch_report(_decode(report_bytes))
91
+ manifest, journal = _decode(manifest_bytes), _decode(journal_bytes)
92
+ try:
93
+ if (
94
+ type(manifest["schema_version"]) is not int
95
+ or manifest["schema_version"] != 1
96
+ or manifest["sequence"] != report["sequence"]
97
+ or manifest["step"] != report["as_of_step"]
98
+ or int(path.parent.name) != report["sequence"]
99
+ or manifest["configuration_sha256"]
100
+ != report["policy"]["configuration_sha256"]
101
+ or _sha(_json(manifest["configuration"]).encode())
102
+ != manifest["configuration_sha256"]
103
+ ):
104
+ raise ValueError("notification snapshot manifest is inconsistent")
105
+ for name, data in (
106
+ ("report.json", report_bytes),
107
+ ("journal.json", journal_bytes),
108
+ ):
109
+ if manifest["artifacts"][name] != {
110
+ "sha256": _sha(data),
111
+ "size_bytes": len(data),
112
+ }:
113
+ raise ValueError(
114
+ "notification snapshot artifact hash differs from its durable manifest"
115
+ )
116
+ if (
117
+ set(journal)
118
+ != {"schema_version", "configuration_sha256", "sequence", "step", "records"}
119
+ or type(journal["schema_version"]) is not int
120
+ or journal["schema_version"] != 1
121
+ or journal["configuration_sha256"] != manifest["configuration_sha256"]
122
+ or journal["sequence"] != report["sequence"]
123
+ or journal["step"] != report["as_of_step"]
124
+ or not isinstance(journal["records"], list)
125
+ ):
126
+ raise ValueError("notification snapshot journal is inconsistent")
127
+ snapshots = [row for row in journal["records"] if row["type"] == "snapshot"]
128
+ if (
129
+ len(snapshots) != 1
130
+ or snapshots[0]["id"] != f"{report['sequence']}:snapshot"
131
+ or snapshots[0]["report_sha256"] != _sha(_json(report).encode())
132
+ ):
133
+ raise ValueError(
134
+ "notification snapshot journal does not identify this report"
135
+ )
136
+ new_emissions = [
137
+ row
138
+ for row in report["emissions"]
139
+ if row["first_emission_sequence"] == report["sequence"]
140
+ ]
141
+ alerts = [
142
+ {"id": "alert:" + _sha(row["feature"].encode()), "type": "alert", **row}
143
+ for row in new_emissions
144
+ ]
145
+ if [row for row in journal["records"] if row["type"] == "alert"] != alerts:
146
+ raise ValueError("notification snapshot emissions differ from its journal")
147
+ except (KeyError, TypeError):
148
+ raise ValueError("invalid notification snapshot manifest or journal") from None
149
+ identity = _sha(
150
+ _json(
151
+ {
152
+ "configuration_sha256": manifest["configuration_sha256"],
153
+ "manifest_sha256": _sha(manifest_bytes),
154
+ "report_sha256": _sha(report_bytes),
155
+ }
156
+ ).encode()
157
+ )
158
+ payload = _json(
159
+ {
160
+ "schema_version": 1,
161
+ "type": "rolloutdiff.watch.notification",
162
+ "notification_id": identity,
163
+ "run_sha256": _sha(report["source"]["run"].encode()),
164
+ "sequence": report["sequence"],
165
+ "as_of_step": report["as_of_step"],
166
+ "new_feature_emissions": [
167
+ {
168
+ "journal_id": item["id"],
169
+ "feature_sha256": _sha(item["feature"].encode()),
170
+ **{
171
+ key: item[key]
172
+ for key in (
173
+ "first_emission_sequence",
174
+ "first_emitted_step",
175
+ "onset_step",
176
+ "alert_step",
177
+ )
178
+ },
179
+ }
180
+ for item in alerts
181
+ ],
182
+ "n_new_feature_emissions": len(alerts),
183
+ "n_current_events": len(report["analysis"]["runs"][0]["events"]),
184
+ "events": [
185
+ {
186
+ "event_id": f"{report['sequence']}:{_sha(event['event_id'].encode())}",
187
+ "rank": event["rank"],
188
+ "representative_feature_sha256": _sha(
189
+ event["representative_feature"].encode()
190
+ ),
191
+ }
192
+ for event in report["analysis"]["runs"][0]["events"]
193
+ ],
194
+ }
195
+ ).encode()
196
+ if len(payload) > _MAX_PAYLOAD_BYTES:
197
+ raise ValueError("notification summary exceeds the 256 KiB payload limit")
198
+ return identity, payload
199
+
200
+
201
+ class _LimitedReader:
202
+ def __init__(self, stream, limit):
203
+ self.stream = stream
204
+ self.remaining = limit
205
+
206
+ def _size(self, requested):
207
+ return (
208
+ min(requested, self.remaining + 1) if requested >= 0 else self.remaining + 1
209
+ )
210
+
211
+ def _count(self, data):
212
+ self.remaining -= len(data)
213
+ if self.remaining < 0:
214
+ raise ValueError("notification response exceeds its byte limit")
215
+ return data
216
+
217
+ def readline(self, size=-1):
218
+ return self._count(self.stream.readline(self._size(size)))
219
+
220
+ def read(self, size=-1):
221
+ return self._count(self.stream.read(self._size(size)))
222
+
223
+ def close(self):
224
+ self.stream.close()
225
+
226
+ def flush(self):
227
+ self.stream.flush()
228
+
229
+
230
+ class _LimitedResponse(http.client.HTTPResponse):
231
+ def __init__(self, *args, **kwargs):
232
+ super().__init__(*args, **kwargs)
233
+ self.fp = _LimitedReader(self.fp, _MAX_RESPONSE_BYTES)
234
+
235
+
236
+ def _addresses(host, port, timeout):
237
+ try:
238
+ address = ipaddress.ip_address(host)
239
+ except ValueError:
240
+ resolved = Future()
241
+
242
+ def lookup():
243
+ try:
244
+ resolved.set_result(
245
+ socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
246
+ )
247
+ except OSError as exc:
248
+ resolved.set_exception(exc)
249
+
250
+ Thread(target=lookup, name="notification-resolver", daemon=True).start()
251
+ return resolved.result(timeout)
252
+ family = socket.AF_INET6 if address.version == 6 else socket.AF_INET
253
+ return [(family, socket.SOCK_STREAM, 0, "", (host, port))]
254
+
255
+
256
+ def _post(endpoint, payload, identity, timeout):
257
+ scheme, host, port, target = endpoint
258
+ deadline = time.monotonic() + timeout
259
+ addresses = _addresses(host, port, timeout)
260
+ connection = http.client.HTTPConnection(host, port, timeout=timeout)
261
+ connection.response_class = _LimitedResponse
262
+ timer = None
263
+ try:
264
+ for family, kind, protocol, _, address in addresses:
265
+ remaining = deadline - time.monotonic()
266
+ if remaining <= 0:
267
+ raise TimeoutError("notification deadline exceeded")
268
+ stream = socket.socket(family, kind, protocol)
269
+ stream.settimeout(remaining)
270
+ try:
271
+ stream.connect(address)
272
+ if scheme == "https":
273
+ stream.settimeout(max(deadline - time.monotonic(), 0.001))
274
+ stream = ssl.create_default_context().wrap_socket(
275
+ stream, server_hostname=host
276
+ )
277
+ connection.sock = stream
278
+ break
279
+ except OSError:
280
+ stream.close()
281
+ if connection.sock is None:
282
+ raise OSError("notification endpoint connection failed")
283
+ remaining = deadline - time.monotonic()
284
+ if remaining <= 0:
285
+ raise TimeoutError("notification deadline exceeded")
286
+
287
+ transport = connection.sock
288
+
289
+ def abort():
290
+ with suppress(OSError):
291
+ transport.shutdown(socket.SHUT_RDWR)
292
+ connection.close()
293
+
294
+ timer = Timer(remaining, abort)
295
+ timer.daemon = True
296
+ timer.start()
297
+ connection.sock.settimeout(remaining)
298
+ connection.request(
299
+ "POST",
300
+ target,
301
+ body=payload,
302
+ headers={
303
+ "Content-Type": "application/json",
304
+ "Idempotency-Key": identity,
305
+ "User-Agent": "rolloutdiff-watch-notification/1",
306
+ "Connection": "close",
307
+ },
308
+ )
309
+ response = connection.getresponse()
310
+ response.read(_MAX_RESPONSE_BYTES + 1)
311
+ if not 100 <= response.status <= 599:
312
+ raise ValueError("invalid notification response status")
313
+ if time.monotonic() > deadline:
314
+ raise TimeoutError("notification deadline exceeded")
315
+ return response.status
316
+ finally:
317
+ if timer is not None:
318
+ timer.cancel()
319
+ connection.close()
320
+
321
+
322
+ def deliver_watch_notification(report_path, *, url, state, timeout=5.0):
323
+ """Attempt one explicit notification; completed or uncertain attempts never retry.
324
+
325
+ Only HTTPS and literal loopback HTTP are accepted. No proxy, ambient credentials,
326
+ redirects, raw rollout files, or response bodies are used. Summaries are capped
327
+ at 256 KiB, HTTP headers plus body at 8 KiB, and transport duration at timeout
328
+ (maximum 30 seconds). DNS may finish in a daemon thread after timeout; that
329
+ thread performs no connection or delivery. This is at-most-once local attempt
330
+ accounting, not exactly-once delivery by the receiver.
331
+ """
332
+ endpoint = _endpoint(url)
333
+ if (
334
+ isinstance(timeout, bool)
335
+ or not isinstance(timeout, (int, float))
336
+ or not math.isfinite(timeout)
337
+ or not 0 < timeout <= 30
338
+ ):
339
+ raise ValueError("notification timeout must be positive and at most 30 seconds")
340
+ report = Path(os.path.abspath(report_path))
341
+ state = Path(os.path.abspath(state))
342
+ watch_state = report.parent.parent.parent
343
+ if (
344
+ state == watch_state
345
+ or state in watch_state.parents
346
+ or watch_state in state.parents
347
+ ):
348
+ raise ValueError("notification and watch state directories must be disjoint")
349
+ identity, payload = _snapshot(report)
350
+ _mkdir(state, private=True)
351
+ descriptor = _lock(state / "lock")
352
+ try:
353
+ binding = {"schema_version": 1, "endpoint_sha256": _sha(url.encode())}
354
+ binding_path = state / "endpoint.json"
355
+ if binding_path.exists() or binding_path.is_symlink():
356
+ if _decode(_read(binding_path)) != binding:
357
+ raise ValueError("notification state is bound to a different endpoint")
358
+ else:
359
+ _publish(binding_path, _json(binding).encode())
360
+ started = state / f"{identity}.started.json"
361
+ completed = state / f"{identity}.complete.json"
362
+ attempt = {
363
+ **binding,
364
+ "notification_id": identity,
365
+ "payload_sha256": _sha(payload),
366
+ }
367
+ if started.exists() or started.is_symlink():
368
+ if _decode(_read(started)) != attempt:
369
+ raise ValueError("notification attempt receipt changed")
370
+ if not completed.exists() and not completed.is_symlink():
371
+ raise ValueError(
372
+ "notification attempt is uncertain; automatic retry is forbidden"
373
+ )
374
+ previous = _decode(_read(completed))
375
+ http_status = previous.get("http_status")
376
+ if (
377
+ set(previous) != set(attempt) | {"status", "http_status"}
378
+ or any(previous[key] != value for key, value in attempt.items())
379
+ or previous["status"] not in {"delivered", "failed"}
380
+ or (
381
+ http_status is not None
382
+ and (type(http_status) is not int or not 100 <= http_status <= 599)
383
+ )
384
+ or (previous["status"] == "delivered")
385
+ != (type(http_status) is int and 200 <= http_status < 300)
386
+ ):
387
+ raise ValueError("notification completion receipt changed")
388
+ return previous
389
+ if completed.exists() or completed.is_symlink():
390
+ raise ValueError("notification completion receipt has no durable attempt")
391
+ _publish(started, _json(attempt).encode())
392
+ try:
393
+ status = _post(endpoint, payload, identity, timeout)
394
+ except (OSError, ValueError, http.client.HTTPException):
395
+ status = None
396
+ result = {
397
+ **attempt,
398
+ "status": "delivered"
399
+ if status is not None and 200 <= status < 300
400
+ else "failed",
401
+ "http_status": status,
402
+ }
403
+ _publish(completed, _json(result).encode())
404
+ return result
405
+ finally:
406
+ os.close(descriptor)