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.
Files changed (57) hide show
  1. protocolith/__init__.py +38 -0
  2. protocolith/baseline_groups.py +294 -0
  3. protocolith/baselines.py +288 -0
  4. protocolith/card_svg_render.py +281 -0
  5. protocolith/card_svg_styles.py +178 -0
  6. protocolith/cli.py +796 -0
  7. protocolith/core/__init__.py +63 -0
  8. protocolith/core/_lock_posix.py +29 -0
  9. protocolith/core/_lock_windows.py +29 -0
  10. protocolith/core/atlas.py +406 -0
  11. protocolith/core/atlas_assets/atlas.css +86 -0
  12. protocolith/core/atlas_assets/atlas.html +84 -0
  13. protocolith/core/atlas_assets/atlas.js +370 -0
  14. protocolith/core/atlas_i18n/en.json +61 -0
  15. protocolith/core/canonical.py +124 -0
  16. protocolith/core/capture.py +68 -0
  17. protocolith/core/clock.py +25 -0
  18. protocolith/core/commands.py +356 -0
  19. protocolith/core/errors.py +116 -0
  20. protocolith/core/issue.py +98 -0
  21. protocolith/core/ledger.py +75 -0
  22. protocolith/core/mcp.py +371 -0
  23. protocolith/core/ops.py +183 -0
  24. protocolith/core/rules.py +352 -0
  25. protocolith/core/schema.py +137 -0
  26. protocolith/core/store.py +101 -0
  27. protocolith/core/views.py +136 -0
  28. protocolith/doctor.py +135 -0
  29. protocolith/evidence_card.py +354 -0
  30. protocolith/family_ledger.py +489 -0
  31. protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
  32. protocolith/inspect.py +48 -0
  33. protocolith/nasa_power.py +266 -0
  34. protocolith/nasa_power_fetch.py +64 -0
  35. protocolith/nasa_power_parser.py +133 -0
  36. protocolith/nasa_power_prereg_runner.py +383 -0
  37. protocolith/noaa_coops_fetch.py +188 -0
  38. protocolith/noaa_coops_parser.py +120 -0
  39. protocolith/noaa_coops_prereg_runner.py +341 -0
  40. protocolith/public_ai_protocol.py +176 -0
  41. protocolith/py.typed +0 -0
  42. protocolith/registry.py +139 -0
  43. protocolith/registry_view.py +302 -0
  44. protocolith/rerun_report.py +111 -0
  45. protocolith/run_root.py +243 -0
  46. protocolith/scaffold.py +565 -0
  47. protocolith/source_probe.py +230 -0
  48. protocolith/svg_a11y.py +100 -0
  49. protocolith/tree_overlay.py +343 -0
  50. protocolith/verify_packs.py +251 -0
  51. protocolith/workflows.py +233 -0
  52. protocolith-0.6.0.dist-info/METADATA +283 -0
  53. protocolith-0.6.0.dist-info/RECORD +57 -0
  54. protocolith-0.6.0.dist-info/WHEEL +4 -0
  55. protocolith-0.6.0.dist-info/entry_points.txt +3 -0
  56. protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
  57. 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
@@ -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