protocolith 0.6.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.
- protocolith/__init__.py +38 -0
- protocolith/baseline_groups.py +294 -0
- protocolith/baselines.py +288 -0
- protocolith/card_svg_render.py +281 -0
- protocolith/card_svg_styles.py +178 -0
- protocolith/cli.py +796 -0
- protocolith/core/__init__.py +63 -0
- protocolith/core/_lock_posix.py +29 -0
- protocolith/core/_lock_windows.py +29 -0
- protocolith/core/atlas.py +406 -0
- protocolith/core/atlas_assets/atlas.css +86 -0
- protocolith/core/atlas_assets/atlas.html +84 -0
- protocolith/core/atlas_assets/atlas.js +370 -0
- protocolith/core/atlas_i18n/en.json +61 -0
- protocolith/core/canonical.py +124 -0
- protocolith/core/capture.py +68 -0
- protocolith/core/clock.py +25 -0
- protocolith/core/commands.py +356 -0
- protocolith/core/errors.py +116 -0
- protocolith/core/issue.py +98 -0
- protocolith/core/ledger.py +75 -0
- protocolith/core/mcp.py +371 -0
- protocolith/core/ops.py +183 -0
- protocolith/core/rules.py +352 -0
- protocolith/core/schema.py +137 -0
- protocolith/core/store.py +101 -0
- protocolith/core/views.py +136 -0
- protocolith/doctor.py +135 -0
- protocolith/evidence_card.py +354 -0
- protocolith/family_ledger.py +489 -0
- protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
- protocolith/inspect.py +48 -0
- protocolith/nasa_power.py +266 -0
- protocolith/nasa_power_fetch.py +64 -0
- protocolith/nasa_power_parser.py +133 -0
- protocolith/nasa_power_prereg_runner.py +383 -0
- protocolith/noaa_coops_fetch.py +188 -0
- protocolith/noaa_coops_parser.py +120 -0
- protocolith/noaa_coops_prereg_runner.py +341 -0
- protocolith/public_ai_protocol.py +176 -0
- protocolith/py.typed +0 -0
- protocolith/registry.py +139 -0
- protocolith/registry_view.py +302 -0
- protocolith/rerun_report.py +111 -0
- protocolith/run_root.py +243 -0
- protocolith/scaffold.py +565 -0
- protocolith/source_probe.py +230 -0
- protocolith/svg_a11y.py +100 -0
- protocolith/tree_overlay.py +343 -0
- protocolith/verify_packs.py +251 -0
- protocolith/workflows.py +233 -0
- protocolith-0.6.0.dist-info/METADATA +283 -0
- protocolith-0.6.0.dist-info/RECORD +57 -0
- protocolith-0.6.0.dist-info/WHEEL +4 -0
- protocolith-0.6.0.dist-info/entry_points.txt +3 -0
- protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
- protocolith-0.6.0.dist-info/licenses/NOTICE +13 -0
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""SourceProbe v1: a bounded, metadata-only probe of one public source URL.
|
|
3
|
+
|
|
4
|
+
The probe never writes the response body anywhere. It records only metadata,
|
|
5
|
+
marker checks and link hints. It does not make legal conclusions and never
|
|
6
|
+
emits a PASS status.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import hashlib
|
|
12
|
+
import json
|
|
13
|
+
import re
|
|
14
|
+
import urllib.error
|
|
15
|
+
import urllib.parse
|
|
16
|
+
import urllib.request
|
|
17
|
+
import urllib.robotparser
|
|
18
|
+
from datetime import datetime, UTC
|
|
19
|
+
from html.parser import HTMLParser
|
|
20
|
+
from typing import Any
|
|
21
|
+
|
|
22
|
+
USER_AGENT = "protocolith-source-probe"
|
|
23
|
+
DEFAULT_TIMEOUT = 15.0
|
|
24
|
+
DEFAULT_MAX_BYTES = 1_048_576
|
|
25
|
+
RECOMMENDATIONS = ("safe_to_continue", "needs_human_review", "blocked")
|
|
26
|
+
BLOCKING_STATUSES = frozenset({401, 403, 429})
|
|
27
|
+
CAPTCHA_MARKERS = (
|
|
28
|
+
"captcha",
|
|
29
|
+
"g-recaptcha",
|
|
30
|
+
"hcaptcha",
|
|
31
|
+
"cf-challenge",
|
|
32
|
+
"are you a robot",
|
|
33
|
+
"verify you are human",
|
|
34
|
+
)
|
|
35
|
+
TERMS_HINT = re.compile(
|
|
36
|
+
r"licen[cs]e|terms|copyright|legal|conditions|creativecommons|reuse|policy",
|
|
37
|
+
re.IGNORECASE,
|
|
38
|
+
)
|
|
39
|
+
REQUIRED_FIELDS = (
|
|
40
|
+
"probe_version",
|
|
41
|
+
"url",
|
|
42
|
+
"final_url",
|
|
43
|
+
"http_status",
|
|
44
|
+
"content_type",
|
|
45
|
+
"byte_size",
|
|
46
|
+
"body_fully_read",
|
|
47
|
+
"sha256",
|
|
48
|
+
"expected_marker_checks",
|
|
49
|
+
"license_or_terms_links",
|
|
50
|
+
"robots_disallow_hint",
|
|
51
|
+
"recommendation",
|
|
52
|
+
"reasons",
|
|
53
|
+
"no_legal_conclusion",
|
|
54
|
+
"probed_at_utc",
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class _LinkParser(HTMLParser):
|
|
59
|
+
def __init__(self) -> None:
|
|
60
|
+
super().__init__()
|
|
61
|
+
self.links: list[str] = []
|
|
62
|
+
self._href: str | None = None
|
|
63
|
+
self._text: list[str] = []
|
|
64
|
+
|
|
65
|
+
def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
|
|
66
|
+
if tag == "a":
|
|
67
|
+
self._href = dict(attrs).get("href")
|
|
68
|
+
self._text = []
|
|
69
|
+
|
|
70
|
+
def handle_data(self, data: str) -> None:
|
|
71
|
+
if self._href is not None:
|
|
72
|
+
self._text.append(data)
|
|
73
|
+
|
|
74
|
+
def handle_endtag(self, tag: str) -> None:
|
|
75
|
+
if tag == "a" and self._href is not None:
|
|
76
|
+
label = " ".join(self._text)
|
|
77
|
+
if TERMS_HINT.search(self._href) or TERMS_HINT.search(label):
|
|
78
|
+
self.links.append(self._href)
|
|
79
|
+
self._href = None
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _utc_now() -> str:
|
|
83
|
+
return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _read_capped(resp: Any, max_bytes: int) -> tuple[bytes, bool]:
|
|
87
|
+
body = resp.read(max_bytes + 1)
|
|
88
|
+
if len(body) > max_bytes:
|
|
89
|
+
return body[:max_bytes], False
|
|
90
|
+
return body, True
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _open(url: str, timeout: float) -> tuple[int, str, str, Any]:
|
|
94
|
+
req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
|
|
95
|
+
try:
|
|
96
|
+
resp = urllib.request.urlopen(req, timeout=timeout) # noqa: S310
|
|
97
|
+
except urllib.error.HTTPError as exc:
|
|
98
|
+
return exc.code, exc.geturl() or url, exc.headers.get("Content-Type", "") or "", exc
|
|
99
|
+
return resp.status, resp.geturl() or url, resp.headers.get("Content-Type", "") or "", resp
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def _robots_disallows(final_url: str, timeout: float) -> bool:
|
|
103
|
+
parts = urllib.parse.urlsplit(final_url)
|
|
104
|
+
robots_url = f"{parts.scheme}://{parts.netloc}/robots.txt"
|
|
105
|
+
try:
|
|
106
|
+
status, _, _, resp = _open(robots_url, timeout)
|
|
107
|
+
try:
|
|
108
|
+
if status != 200:
|
|
109
|
+
return False
|
|
110
|
+
body, _ = _read_capped(resp, 65_536)
|
|
111
|
+
finally:
|
|
112
|
+
resp.close()
|
|
113
|
+
except (OSError, ValueError):
|
|
114
|
+
return False
|
|
115
|
+
parser = urllib.robotparser.RobotFileParser()
|
|
116
|
+
parser.parse(body.decode("utf-8", errors="replace").splitlines())
|
|
117
|
+
return not parser.can_fetch(USER_AGENT, final_url)
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def probe_url(
|
|
121
|
+
url: str,
|
|
122
|
+
markers: list[str] | tuple[str, ...] = (),
|
|
123
|
+
*,
|
|
124
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
125
|
+
max_bytes: int = DEFAULT_MAX_BYTES,
|
|
126
|
+
check_robots: bool = True,
|
|
127
|
+
) -> dict[str, Any]:
|
|
128
|
+
"""Probe one URL and return a metadata-only result dictionary."""
|
|
129
|
+
scheme = urllib.parse.urlsplit(url).scheme
|
|
130
|
+
if scheme not in ("http", "https"):
|
|
131
|
+
raise ValueError("SourceProbe supports only http and https URLs")
|
|
132
|
+
reasons: list[str] = []
|
|
133
|
+
result: dict[str, Any] = {
|
|
134
|
+
"probe_version": "1",
|
|
135
|
+
"url": url,
|
|
136
|
+
"final_url": url,
|
|
137
|
+
"http_status": None,
|
|
138
|
+
"content_type": "",
|
|
139
|
+
"byte_size": 0,
|
|
140
|
+
"body_fully_read": False,
|
|
141
|
+
"sha256": None,
|
|
142
|
+
"expected_marker_checks": [],
|
|
143
|
+
"license_or_terms_links": [],
|
|
144
|
+
"robots_disallow_hint": False,
|
|
145
|
+
"recommendation": "needs_human_review",
|
|
146
|
+
"reasons": reasons,
|
|
147
|
+
"no_legal_conclusion": True,
|
|
148
|
+
"probed_at_utc": _utc_now(),
|
|
149
|
+
}
|
|
150
|
+
try:
|
|
151
|
+
status, final_url, ctype, resp = _open(url, timeout)
|
|
152
|
+
try:
|
|
153
|
+
body, complete = _read_capped(resp, max_bytes)
|
|
154
|
+
finally:
|
|
155
|
+
resp.close()
|
|
156
|
+
except (OSError, ValueError) as exc:
|
|
157
|
+
reasons.append(f"request_failed: {type(exc).__name__}")
|
|
158
|
+
result["recommendation"] = "blocked"
|
|
159
|
+
return result
|
|
160
|
+
|
|
161
|
+
result.update(http_status=status, final_url=final_url, content_type=ctype)
|
|
162
|
+
result["byte_size"] = len(body)
|
|
163
|
+
result["body_fully_read"] = complete
|
|
164
|
+
if complete:
|
|
165
|
+
result["sha256"] = hashlib.sha256(body).hexdigest()
|
|
166
|
+
else:
|
|
167
|
+
reasons.append("body_exceeded_max_bytes_not_hashed")
|
|
168
|
+
|
|
169
|
+
text = body.decode("utf-8", errors="replace")
|
|
170
|
+
result["expected_marker_checks"] = [{"marker": m, "found": m in text} for m in markers]
|
|
171
|
+
if "html" in ctype.lower() or not ctype:
|
|
172
|
+
parser = _LinkParser()
|
|
173
|
+
try:
|
|
174
|
+
parser.feed(text)
|
|
175
|
+
except Exception: # noqa: BLE001 - hints only, never fail the probe
|
|
176
|
+
pass
|
|
177
|
+
links = {urllib.parse.urljoin(final_url, h) for h in parser.links if h}
|
|
178
|
+
result["license_or_terms_links"] = sorted(links)[:20]
|
|
179
|
+
|
|
180
|
+
if check_robots:
|
|
181
|
+
result["robots_disallow_hint"] = _robots_disallows(final_url, timeout)
|
|
182
|
+
|
|
183
|
+
lowered = text.lower()
|
|
184
|
+
blocked = False
|
|
185
|
+
if status in BLOCKING_STATUSES or status >= 500:
|
|
186
|
+
blocked = True
|
|
187
|
+
reasons.append(f"http_status_{status}")
|
|
188
|
+
if any(marker in lowered for marker in CAPTCHA_MARKERS):
|
|
189
|
+
blocked = True
|
|
190
|
+
reasons.append("captcha_like_marker")
|
|
191
|
+
if result["robots_disallow_hint"]:
|
|
192
|
+
blocked = True
|
|
193
|
+
reasons.append("robots_disallow_hint")
|
|
194
|
+
|
|
195
|
+
if blocked:
|
|
196
|
+
result["recommendation"] = "blocked"
|
|
197
|
+
else:
|
|
198
|
+
missing = [c["marker"] for c in result["expected_marker_checks"] if not c["found"]]
|
|
199
|
+
if missing:
|
|
200
|
+
reasons.append("expected_marker_missing")
|
|
201
|
+
if status != 200:
|
|
202
|
+
reasons.append(f"http_status_{status}")
|
|
203
|
+
if not complete:
|
|
204
|
+
reasons.append("incomplete_body")
|
|
205
|
+
if missing or status != 200 or not complete:
|
|
206
|
+
result["recommendation"] = "needs_human_review"
|
|
207
|
+
else:
|
|
208
|
+
result["recommendation"] = "safe_to_continue"
|
|
209
|
+
return result
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def validate_probe_artifact(data: Any) -> list[str]:
|
|
213
|
+
"""Return a list of violations for a SourceProbe JSON artifact."""
|
|
214
|
+
if not isinstance(data, dict):
|
|
215
|
+
return ["artifact must be a JSON object"]
|
|
216
|
+
errors = [f"missing field: {f}" for f in REQUIRED_FIELDS if f not in data]
|
|
217
|
+
if data.get("no_legal_conclusion") is not True:
|
|
218
|
+
errors.append("no_legal_conclusion must be true")
|
|
219
|
+
if data.get("recommendation") not in RECOMMENDATIONS:
|
|
220
|
+
errors.append("recommendation must be one of " + "|".join(RECOMMENDATIONS))
|
|
221
|
+
status_text = json.dumps(data)
|
|
222
|
+
if "PASSED_UNDER_PROTOCOL" in status_text or '"PASS"' in status_text:
|
|
223
|
+
errors.append("probe artifact must not carry a PASS status")
|
|
224
|
+
if data.get("sha256") is not None and data.get("body_fully_read") is not True:
|
|
225
|
+
errors.append("sha256 is only allowed when the body was fully read")
|
|
226
|
+
if "body" in data or "raw_body" in data:
|
|
227
|
+
errors.append("raw body must not be stored")
|
|
228
|
+
if not isinstance(data.get("expected_marker_checks", []), list):
|
|
229
|
+
errors.append("expected_marker_checks must be a list")
|
|
230
|
+
return errors
|
protocolith/svg_a11y.py
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Static accessibility lint for Protocolith SVG files.
|
|
3
|
+
|
|
4
|
+
This is a structural and colour-contrast heuristic, not a WCAG conformance
|
|
5
|
+
audit. See ``docs/ACCESSIBILITY.md`` for what is and is not checked.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import re
|
|
11
|
+
import xml.etree.ElementTree as ET
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
|
|
14
|
+
from protocolith.card_svg_styles import (
|
|
15
|
+
MIN_TEXT_CONTRAST,
|
|
16
|
+
PAGE_BACKGROUNDS,
|
|
17
|
+
contrast_ratio,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
_SVG_NS = "{http://www.w3.org/2000/svg}"
|
|
21
|
+
_HEX_RE = re.compile(r"^#[0-9a-fA-F]{6}$")
|
|
22
|
+
_URL_RE = re.compile(r"url\(#([^)]+)\)")
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def lint_svg_text(svg: str) -> list[str]:
|
|
26
|
+
"""Return accessibility findings for one SVG document (empty list = clean).
|
|
27
|
+
|
|
28
|
+
Findings are stable strings without file-specific values so callers can
|
|
29
|
+
count them by kind.
|
|
30
|
+
"""
|
|
31
|
+
try:
|
|
32
|
+
root = ET.fromstring(svg.encode("utf-8"))
|
|
33
|
+
except ET.ParseError:
|
|
34
|
+
return ["svg is not well-formed XML"]
|
|
35
|
+
|
|
36
|
+
if root.tag != f"{_SVG_NS}svg":
|
|
37
|
+
return ["root element is not <svg>"]
|
|
38
|
+
|
|
39
|
+
findings: list[str] = []
|
|
40
|
+
if root.get("role") != "img":
|
|
41
|
+
findings.append('root <svg> lacks role="img"')
|
|
42
|
+
|
|
43
|
+
elements = {el.get("id"): el for el in root.iter() if el.get("id")}
|
|
44
|
+
labelled = (root.get("aria-labelledby") or "").split()
|
|
45
|
+
if not labelled:
|
|
46
|
+
findings.append("root <svg> lacks aria-labelledby")
|
|
47
|
+
kinds: set[str] = set()
|
|
48
|
+
for ident in labelled:
|
|
49
|
+
el = elements.get(ident)
|
|
50
|
+
if el is None:
|
|
51
|
+
findings.append("aria-labelledby references a missing id")
|
|
52
|
+
elif el.tag in (f"{_SVG_NS}title", f"{_SVG_NS}desc") and "".join(el.itertext()).strip():
|
|
53
|
+
kinds.add(el.tag.removeprefix(_SVG_NS))
|
|
54
|
+
for kind in ("title", "desc"):
|
|
55
|
+
if kind not in kinds:
|
|
56
|
+
findings.append(f"no non-empty <{kind}> referenced by aria-labelledby")
|
|
57
|
+
|
|
58
|
+
findings.extend(_contrast_findings(root))
|
|
59
|
+
return findings
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _contrast_findings(root: ET.Element) -> list[str]:
|
|
63
|
+
stops: dict[str, list[str]] = {}
|
|
64
|
+
for grad in root.iter(f"{_SVG_NS}linearGradient"):
|
|
65
|
+
ident = grad.get("id")
|
|
66
|
+
if ident:
|
|
67
|
+
stops[ident] = [
|
|
68
|
+
s.get("stop-color", "")
|
|
69
|
+
for s in grad.iter(f"{_SVG_NS}stop")
|
|
70
|
+
if _HEX_RE.match(s.get("stop-color", ""))
|
|
71
|
+
]
|
|
72
|
+
used: set[str] = set()
|
|
73
|
+
for rect in root.iter(f"{_SVG_NS}rect"):
|
|
74
|
+
match = _URL_RE.fullmatch(rect.get("fill", ""))
|
|
75
|
+
if match and match.group(1) in stops and not match.group(1).startswith("logo"):
|
|
76
|
+
used.add(match.group(1))
|
|
77
|
+
chip_stops = [color for ident in sorted(used) for color in stops[ident]]
|
|
78
|
+
|
|
79
|
+
logo_text = {
|
|
80
|
+
id(text)
|
|
81
|
+
for group in root.iter(f"{_SVG_NS}g")
|
|
82
|
+
if "logo" in group.get("aria-label", "").lower()
|
|
83
|
+
for text in group.iter(f"{_SVG_NS}text")
|
|
84
|
+
} # logotypes are exempt from contrast requirements (WCAG 1.4.3)
|
|
85
|
+
|
|
86
|
+
findings: list[str] = []
|
|
87
|
+
for text in root.iter(f"{_SVG_NS}text"):
|
|
88
|
+
fill = text.get("fill", "")
|
|
89
|
+
if id(text) in logo_text or not _HEX_RE.match(fill):
|
|
90
|
+
continue
|
|
91
|
+
backgrounds = chip_stops if fill.lower() == "#ffffff" else list(PAGE_BACKGROUNDS)
|
|
92
|
+
if any(contrast_ratio(fill, bg) < MIN_TEXT_CONTRAST for bg in backgrounds):
|
|
93
|
+
finding = f"text contrast below {MIN_TEXT_CONTRAST}:1"
|
|
94
|
+
if finding not in findings:
|
|
95
|
+
findings.append(finding)
|
|
96
|
+
return findings
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def lint_svg_file(path: Path) -> list[str]:
|
|
100
|
+
return lint_svg_text(path.read_text(encoding="utf-8"))
|
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Validation helpers for Protocolith v3 tree overlays.
|
|
3
|
+
|
|
4
|
+
The v3 tree overlay is additive planning/preflight metadata. It does not change
|
|
5
|
+
historical evidence cards and it does not create an empirical result by itself.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
PROTOCOL_VERSION_V3 = "protocolith-tree-v3"
|
|
15
|
+
|
|
16
|
+
ALLOWED_TREE_STATUSES = {
|
|
17
|
+
"DRAFT",
|
|
18
|
+
"ACTIVE",
|
|
19
|
+
"CLOSED",
|
|
20
|
+
"SUPERSEDED",
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
ALLOWED_CLAIM_KINDS = {
|
|
24
|
+
"iron_claim",
|
|
25
|
+
"flow_claim",
|
|
26
|
+
"diagnostic_claim",
|
|
27
|
+
"tombstone",
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
ALLOWED_CLAIM_STATUSES = {
|
|
31
|
+
"DRAFT",
|
|
32
|
+
"FROZEN",
|
|
33
|
+
"PASSED",
|
|
34
|
+
"NEGATIVE",
|
|
35
|
+
"BLOCKED",
|
|
36
|
+
"SUPERSEDED",
|
|
37
|
+
"STOPPED",
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
ALLOWED_TRACK_MODES = {
|
|
41
|
+
"source_audit",
|
|
42
|
+
"diagnostic",
|
|
43
|
+
"proof",
|
|
44
|
+
"reproduction",
|
|
45
|
+
"closure",
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
ALLOWED_BRANCH_STATUSES = {
|
|
49
|
+
"runnable",
|
|
50
|
+
"blocked",
|
|
51
|
+
"stopped",
|
|
52
|
+
"closed",
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
REQUIRED_TOP_LEVEL_FIELDS = {
|
|
56
|
+
"tree_id",
|
|
57
|
+
"protocol_version",
|
|
58
|
+
"tree_status",
|
|
59
|
+
"root_family_id",
|
|
60
|
+
"claim_nodes",
|
|
61
|
+
"track_nodes",
|
|
62
|
+
"tombstones",
|
|
63
|
+
"badge_counts",
|
|
64
|
+
"branch_block_rules",
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
REQUIRED_CLAIM_NODE_FIELDS = {
|
|
68
|
+
"claim_id",
|
|
69
|
+
"claim_kind",
|
|
70
|
+
"status",
|
|
71
|
+
"claim_text",
|
|
72
|
+
"evidence_required",
|
|
73
|
+
"acceptance_gate",
|
|
74
|
+
"forbidden_inference",
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
REQUIRED_TRACK_NODE_FIELDS = {
|
|
78
|
+
"track_id",
|
|
79
|
+
"mode",
|
|
80
|
+
"claim_ids",
|
|
81
|
+
"dependencies",
|
|
82
|
+
"branch_status",
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
REQUIRED_TOMBSTONE_FIELDS = {
|
|
86
|
+
"tombstone_id",
|
|
87
|
+
"stopped_family_id",
|
|
88
|
+
"decision",
|
|
89
|
+
"poisoned_proof_surface_hashes",
|
|
90
|
+
"blocked_future_work",
|
|
91
|
+
"non_overlap_requirements",
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
BROAD_CLAIM_FRAGMENTS = {
|
|
95
|
+
"best model",
|
|
96
|
+
"deployment ready",
|
|
97
|
+
"deployment-ready",
|
|
98
|
+
"live operation",
|
|
99
|
+
"production ready",
|
|
100
|
+
"universal edge",
|
|
101
|
+
"universal forecasting edge",
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def load_tree_overlay(path: Path) -> dict[str, Any]:
|
|
106
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
107
|
+
if not isinstance(data, dict):
|
|
108
|
+
raise ValueError("tree overlay must be a JSON object")
|
|
109
|
+
return data
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def validate_tree_overlay(tree: dict[str, Any]) -> list[str]:
|
|
113
|
+
violations: list[str] = []
|
|
114
|
+
|
|
115
|
+
missing = sorted(field for field in REQUIRED_TOP_LEVEL_FIELDS if _is_missing_top_level(tree, field))
|
|
116
|
+
violations.extend(f"missing required field: {field}" for field in missing)
|
|
117
|
+
|
|
118
|
+
if tree.get("protocol_version") != PROTOCOL_VERSION_V3:
|
|
119
|
+
violations.append(f"protocol_version must be {PROTOCOL_VERSION_V3!r}")
|
|
120
|
+
|
|
121
|
+
if tree.get("tree_status") not in ALLOWED_TREE_STATUSES:
|
|
122
|
+
violations.append(
|
|
123
|
+
"tree_status must be one of: " + ", ".join(sorted(ALLOWED_TREE_STATUSES))
|
|
124
|
+
)
|
|
125
|
+
|
|
126
|
+
claim_ids = _validate_claim_nodes(tree.get("claim_nodes"), violations)
|
|
127
|
+
_validate_track_nodes(tree.get("track_nodes"), claim_ids, violations)
|
|
128
|
+
_validate_tombstones(tree.get("tombstones"), violations)
|
|
129
|
+
_validate_badge_counts(
|
|
130
|
+
tree.get("badge_counts"),
|
|
131
|
+
tree.get("claim_nodes"),
|
|
132
|
+
tree.get("tombstones"),
|
|
133
|
+
violations,
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
if not isinstance(tree.get("branch_block_rules"), list) or not tree.get("branch_block_rules"):
|
|
137
|
+
violations.append("branch_block_rules must be a non-empty list")
|
|
138
|
+
|
|
139
|
+
text = json.dumps(tree, sort_keys=True).lower()
|
|
140
|
+
for fragment in sorted(BROAD_CLAIM_FRAGMENTS):
|
|
141
|
+
if fragment in text:
|
|
142
|
+
violations.append(f"forbidden broad claim fragment: {fragment!r}")
|
|
143
|
+
|
|
144
|
+
return violations
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def _validate_claim_nodes(value: object, violations: list[str]) -> set[str]:
|
|
148
|
+
if not isinstance(value, list) or not value:
|
|
149
|
+
violations.append("claim_nodes must be a non-empty list")
|
|
150
|
+
return set()
|
|
151
|
+
|
|
152
|
+
claim_ids: set[str] = set()
|
|
153
|
+
for index, item in enumerate(value):
|
|
154
|
+
prefix = f"claim_nodes[{index}]"
|
|
155
|
+
if not isinstance(item, dict):
|
|
156
|
+
violations.append(f"{prefix} must be an object")
|
|
157
|
+
continue
|
|
158
|
+
|
|
159
|
+
missing = sorted(field for field in REQUIRED_CLAIM_NODE_FIELDS if _is_missing(item.get(field)))
|
|
160
|
+
violations.extend(f"{prefix} missing required field: {field}" for field in missing)
|
|
161
|
+
|
|
162
|
+
claim_id = item.get("claim_id")
|
|
163
|
+
if isinstance(claim_id, str):
|
|
164
|
+
if claim_id in claim_ids:
|
|
165
|
+
violations.append(f"duplicate claim_id: {claim_id}")
|
|
166
|
+
claim_ids.add(claim_id)
|
|
167
|
+
|
|
168
|
+
if item.get("claim_kind") not in ALLOWED_CLAIM_KINDS:
|
|
169
|
+
violations.append(
|
|
170
|
+
f"{prefix}.claim_kind must be one of: "
|
|
171
|
+
+ ", ".join(sorted(ALLOWED_CLAIM_KINDS))
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
if item.get("status") not in ALLOWED_CLAIM_STATUSES:
|
|
175
|
+
violations.append(
|
|
176
|
+
f"{prefix}.status must be one of: "
|
|
177
|
+
+ ", ".join(sorted(ALLOWED_CLAIM_STATUSES))
|
|
178
|
+
)
|
|
179
|
+
|
|
180
|
+
for list_field in ("evidence_required", "forbidden_inference"):
|
|
181
|
+
if not isinstance(item.get(list_field), list) or not item.get(list_field):
|
|
182
|
+
violations.append(f"{prefix}.{list_field} must be a non-empty list")
|
|
183
|
+
|
|
184
|
+
if item.get("claim_kind") == "iron_claim" and not _looks_like_sha256_placeholder_or_hash(
|
|
185
|
+
item.get("proof_surface_hash")
|
|
186
|
+
):
|
|
187
|
+
violations.append(
|
|
188
|
+
f"{prefix}.proof_surface_hash must be SHA-256 hex or NOT_COMPUTED_UNTIL_FREEZE"
|
|
189
|
+
)
|
|
190
|
+
|
|
191
|
+
return claim_ids
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def _validate_track_nodes(value: object, claim_ids: set[str], violations: list[str]) -> None:
|
|
195
|
+
if not isinstance(value, list) or not value:
|
|
196
|
+
violations.append("track_nodes must be a non-empty list")
|
|
197
|
+
return
|
|
198
|
+
|
|
199
|
+
track_ids: set[str] = set()
|
|
200
|
+
for index, item in enumerate(value):
|
|
201
|
+
prefix = f"track_nodes[{index}]"
|
|
202
|
+
if not isinstance(item, dict):
|
|
203
|
+
violations.append(f"{prefix} must be an object")
|
|
204
|
+
continue
|
|
205
|
+
|
|
206
|
+
missing = sorted(
|
|
207
|
+
field for field in REQUIRED_TRACK_NODE_FIELDS if _is_missing_track_field(item, field)
|
|
208
|
+
)
|
|
209
|
+
violations.extend(f"{prefix} missing required field: {field}" for field in missing)
|
|
210
|
+
|
|
211
|
+
track_id = item.get("track_id")
|
|
212
|
+
if isinstance(track_id, str):
|
|
213
|
+
if track_id in track_ids:
|
|
214
|
+
violations.append(f"duplicate track_id: {track_id}")
|
|
215
|
+
track_ids.add(track_id)
|
|
216
|
+
|
|
217
|
+
if item.get("mode") not in ALLOWED_TRACK_MODES:
|
|
218
|
+
violations.append(
|
|
219
|
+
f"{prefix}.mode must be one of: "
|
|
220
|
+
+ ", ".join(sorted(ALLOWED_TRACK_MODES))
|
|
221
|
+
)
|
|
222
|
+
|
|
223
|
+
if item.get("branch_status") not in ALLOWED_BRANCH_STATUSES:
|
|
224
|
+
violations.append(
|
|
225
|
+
f"{prefix}.branch_status must be one of: "
|
|
226
|
+
+ ", ".join(sorted(ALLOWED_BRANCH_STATUSES))
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
refs = item.get("claim_ids")
|
|
230
|
+
if isinstance(refs, list):
|
|
231
|
+
for claim_id in refs:
|
|
232
|
+
if claim_id not in claim_ids:
|
|
233
|
+
violations.append(f"{prefix}.claim_ids references unknown claim_id: {claim_id!r}")
|
|
234
|
+
elif refs is not None:
|
|
235
|
+
violations.append(f"{prefix}.claim_ids must be a list")
|
|
236
|
+
|
|
237
|
+
if not isinstance(item.get("dependencies"), list):
|
|
238
|
+
violations.append(f"{prefix}.dependencies must be a list")
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
def _validate_tombstones(value: object, violations: list[str]) -> None:
|
|
242
|
+
if not isinstance(value, list):
|
|
243
|
+
violations.append("tombstones must be a list")
|
|
244
|
+
return
|
|
245
|
+
|
|
246
|
+
tombstone_ids: set[str] = set()
|
|
247
|
+
for index, item in enumerate(value):
|
|
248
|
+
prefix = f"tombstones[{index}]"
|
|
249
|
+
if not isinstance(item, dict):
|
|
250
|
+
violations.append(f"{prefix} must be an object")
|
|
251
|
+
continue
|
|
252
|
+
|
|
253
|
+
missing = sorted(field for field in REQUIRED_TOMBSTONE_FIELDS if _is_missing(item.get(field)))
|
|
254
|
+
violations.extend(f"{prefix} missing required field: {field}" for field in missing)
|
|
255
|
+
|
|
256
|
+
tombstone_id = item.get("tombstone_id")
|
|
257
|
+
if isinstance(tombstone_id, str):
|
|
258
|
+
if tombstone_id in tombstone_ids:
|
|
259
|
+
violations.append(f"duplicate tombstone_id: {tombstone_id}")
|
|
260
|
+
tombstone_ids.add(tombstone_id)
|
|
261
|
+
|
|
262
|
+
for list_field in (
|
|
263
|
+
"poisoned_proof_surface_hashes",
|
|
264
|
+
"blocked_future_work",
|
|
265
|
+
"non_overlap_requirements",
|
|
266
|
+
):
|
|
267
|
+
if not isinstance(item.get(list_field), list) or not item.get(list_field):
|
|
268
|
+
violations.append(f"{prefix}.{list_field} must be a non-empty list")
|
|
269
|
+
|
|
270
|
+
hashes = item.get("poisoned_proof_surface_hashes")
|
|
271
|
+
if isinstance(hashes, list):
|
|
272
|
+
for proof_hash in hashes:
|
|
273
|
+
if not _looks_like_sha256_placeholder_or_hash(proof_hash):
|
|
274
|
+
violations.append(f"{prefix}.poisoned_proof_surface_hashes has invalid hash")
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def _validate_badge_counts(
|
|
278
|
+
badge_counts: object,
|
|
279
|
+
claim_nodes: object,
|
|
280
|
+
tombstones: object,
|
|
281
|
+
violations: list[str],
|
|
282
|
+
) -> None:
|
|
283
|
+
if not isinstance(badge_counts, dict):
|
|
284
|
+
violations.append("badge_counts must be an object")
|
|
285
|
+
return
|
|
286
|
+
|
|
287
|
+
for field in ("iron_claims", "flow_claims", "tombstones"):
|
|
288
|
+
value = badge_counts.get(field)
|
|
289
|
+
if not isinstance(value, int) or value < 0:
|
|
290
|
+
violations.append(f"badge_counts.{field} must be a non-negative integer")
|
|
291
|
+
|
|
292
|
+
if isinstance(claim_nodes, list):
|
|
293
|
+
iron = sum(1 for item in claim_nodes if isinstance(item, dict) and item.get("claim_kind") == "iron_claim")
|
|
294
|
+
flow = sum(1 for item in claim_nodes if isinstance(item, dict) and item.get("claim_kind") == "flow_claim")
|
|
295
|
+
if badge_counts.get("iron_claims") != iron:
|
|
296
|
+
violations.append("badge_counts.iron_claims must match iron_claim nodes")
|
|
297
|
+
if badge_counts.get("flow_claims") != flow:
|
|
298
|
+
violations.append("badge_counts.flow_claims must match flow_claim nodes")
|
|
299
|
+
|
|
300
|
+
if isinstance(tombstones, list) and badge_counts.get("tombstones") != len(tombstones):
|
|
301
|
+
violations.append("badge_counts.tombstones must match tombstone records")
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
def _is_missing_top_level(tree: dict[str, Any], field: str) -> bool:
|
|
305
|
+
if field not in tree:
|
|
306
|
+
return True
|
|
307
|
+
value = tree.get(field)
|
|
308
|
+
if value is None:
|
|
309
|
+
return True
|
|
310
|
+
if isinstance(value, str) and value.strip() == "":
|
|
311
|
+
return True
|
|
312
|
+
return False
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
def _looks_like_sha256_placeholder_or_hash(value: object) -> bool:
|
|
316
|
+
if value == "NOT_COMPUTED_UNTIL_FREEZE":
|
|
317
|
+
return True
|
|
318
|
+
if not isinstance(value, str):
|
|
319
|
+
return False
|
|
320
|
+
if len(value) != 64:
|
|
321
|
+
return False
|
|
322
|
+
return all(char in "0123456789abcdef" for char in value.lower())
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def _is_missing_track_field(item: dict[str, Any], field: str) -> bool:
|
|
326
|
+
if field not in item:
|
|
327
|
+
return True
|
|
328
|
+
value = item.get(field)
|
|
329
|
+
if value is None:
|
|
330
|
+
return True
|
|
331
|
+
if isinstance(value, str) and value.strip() == "":
|
|
332
|
+
return True
|
|
333
|
+
return False
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
def _is_missing(value: object) -> bool:
|
|
337
|
+
if value is None:
|
|
338
|
+
return True
|
|
339
|
+
if isinstance(value, str) and value.strip() == "":
|
|
340
|
+
return True
|
|
341
|
+
if isinstance(value, (list, tuple, dict, set)) and len(value) == 0:
|
|
342
|
+
return True
|
|
343
|
+
return False
|