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,136 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Read-only views over a loaded ledger: filtered log, one entry with context, and the summary."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from typing import Any
7
+
8
+ from .errors import InputError
9
+ from .ledger import ENTRY_TYPES, RESULT_STATUSES, Entry
10
+ from .rules import Verdict, Verifier
11
+
12
+
13
+ def _protocol_sha(verifier: Verifier, entry: Entry) -> str | None:
14
+ """The protocol hash an entry refers to (an issue entry refers to the protocol of its record)."""
15
+ body = entry["body"]
16
+ if entry["type"] == "issue":
17
+ target = verifier.entries.get(body["record_seq"])
18
+ return None if target is None else _protocol_sha(verifier, target)
19
+ return str(body["protocol_sha256"])
20
+
21
+
22
+ def protocol_of(verifier: Verifier, entry: Entry) -> str | None:
23
+ """The ``protocol_id`` an entry belongs to, or None when its protocol was never frozen."""
24
+ if entry["type"] == "freeze":
25
+ return str(entry["body"]["protocol_id"])
26
+ frozen = verifier.protocols.get(_protocol_sha(verifier, entry) or "")
27
+ return None if frozen is None else str(frozen["protocol_id"])
28
+
29
+
30
+ def _ordered(verifier: Verifier) -> list[Entry]:
31
+ return [verifier.entries[i] for i in sorted(verifier.entries)]
32
+
33
+
34
+ def _require_protocol(verifier: Verifier, protocol: str | None) -> None:
35
+ if protocol is not None and all(p["protocol_id"] != protocol for p in verifier.protocols.values()):
36
+ raise InputError("UNKNOWN_PROTOCOL", f"no protocol {protocol!r} is frozen in this ledger")
37
+
38
+
39
+ def select(
40
+ verifier: Verifier,
41
+ *,
42
+ protocol: str | None = None,
43
+ entry_type: str | None = None,
44
+ status: str | None = None,
45
+ tail: int | None = None,
46
+ ) -> list[Entry]:
47
+ """Entries matching every given filter, in ledger order; ``tail`` keeps the last N matches."""
48
+ if entry_type is not None and entry_type not in ENTRY_TYPES:
49
+ raise InputError("BAD_ENTRY", f"type must be one of: {', '.join(ENTRY_TYPES)}")
50
+ if status is not None and status not in RESULT_STATUSES:
51
+ raise InputError("BAD_STATUS", f"status must be one of: {', '.join(sorted(RESULT_STATUSES))}")
52
+ if tail is not None and not (type(tail) is int and tail >= 1):
53
+ raise InputError("BAD_ENTRY", "tail must be an integer of at least 1")
54
+ _require_protocol(verifier, protocol)
55
+ found = [
56
+ entry
57
+ for entry in _ordered(verifier)
58
+ if (entry_type is None or entry["type"] == entry_type)
59
+ and (status is None or entry["body"].get("status") == status)
60
+ and (protocol is None or protocol_of(verifier, entry) == protocol)
61
+ ]
62
+ return found if tail is None else found[-tail:]
63
+
64
+
65
+ def show(verifier: Verifier, seq: int) -> dict[str, Any]:
66
+ """One entry, the protocol it belongs to, the entries it points at and the entries that point at it."""
67
+ if type(seq) is not int or seq not in verifier.entries:
68
+ raise InputError("DANGLING_REF", f"there is no valid entry at seq {seq!r}")
69
+ entry = verifier.entries[seq]
70
+ body = entry["body"]
71
+ sha = _protocol_sha(verifier, entry) or ""
72
+ frozen = verifier.protocols.get(sha)
73
+ context = None
74
+ if frozen is not None:
75
+ context = {
76
+ "freeze_seq": frozen["seq"],
77
+ "protocol_id": frozen["protocol_id"],
78
+ "protocol_sha256": sha,
79
+ "version": frozen["version"],
80
+ }
81
+ points_at = list(body["deviations"]) if entry["type"] == "record" else []
82
+ if entry["type"] == "issue":
83
+ points_at = [body["record_seq"]]
84
+ pointed_by = [
85
+ other["seq"]
86
+ for other in _ordered(verifier)
87
+ if (other["type"] == "issue" and other["body"]["record_seq"] == seq)
88
+ or (other["type"] == "record" and seq in other["body"]["deviations"])
89
+ ]
90
+ return {"entry": entry, "points_at": points_at, "pointed_by": pointed_by, "protocol": context}
91
+
92
+
93
+ def summarize(verdict: Verdict, verifier: Verifier, protocol: str | None = None) -> dict[str, Any]:
94
+ """Verdict, head, counts and a per-protocol table. Computed from the entries that parsed and passed their shape checks."""
95
+ _require_protocol(verifier, protocol)
96
+ by_type = dict.fromkeys(ENTRY_TYPES, 0)
97
+ by_status: dict[str, int] = {}
98
+ table: dict[str, dict[str, Any]] = {}
99
+ for entry in _ordered(verifier):
100
+ pid = protocol_of(verifier, entry)
101
+ if pid is None or (protocol is not None and pid != protocol):
102
+ continue
103
+ body = entry["body"]
104
+ by_type[entry["type"]] += 1
105
+ row = table.setdefault(
106
+ pid,
107
+ {
108
+ "cards": 0,
109
+ "deviations": 0,
110
+ "latest_status": None,
111
+ "latest_version": None,
112
+ "protocol_id": pid,
113
+ "records": 0,
114
+ "versions": [],
115
+ },
116
+ )
117
+ if entry["type"] == "freeze":
118
+ row["versions"].append(body["version"])
119
+ row["latest_version"] = body["version"]
120
+ elif entry["type"] == "record":
121
+ row["records"] += 1
122
+ row["latest_status"] = body["status"]
123
+ by_status[body["status"]] = by_status.get(body["status"], 0) + 1
124
+ elif entry["type"] == "deviation":
125
+ row["deviations"] += 1
126
+ else:
127
+ row["cards"] += 1
128
+ problems = [{"code": v.code, "message": v.message, "seq": v.seq} for v in verdict.violations]
129
+ return {
130
+ "entries_by_type": by_type,
131
+ "head": {"count": verdict.count, "hash": verdict.head_hash, "seq": verdict.head_seq},
132
+ "ok": verdict.ok,
133
+ "problems": problems,
134
+ "protocols": [table[pid] for pid in sorted(table)],
135
+ "records_by_status": dict(sorted(by_status.items())),
136
+ }
protocolith/doctor.py ADDED
@@ -0,0 +1,135 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Cross-platform environment checks for Protocolith operators."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import platform
7
+ import shutil
8
+ import sys
9
+ from dataclasses import dataclass
10
+ from datetime import date
11
+ from pathlib import Path
12
+
13
+
14
+ MIN_PYTHON = (3, 11)
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class DoctorCheck:
19
+ name: str
20
+ ok: bool
21
+ detail: str
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class DoctorReport:
26
+ checks: tuple[DoctorCheck, ...]
27
+ platform_system: str
28
+ platform_release: str
29
+ python_version: str
30
+ repo_root: Path
31
+ runs_root: Path
32
+ today_iso: str
33
+ mode: str = "checkout"
34
+
35
+ @property
36
+ def ok(self) -> bool:
37
+ return all(check.ok for check in self.checks)
38
+
39
+
40
+ def run_doctor(repo_root: Path) -> DoctorReport:
41
+ checks: list[DoctorCheck] = []
42
+
43
+ py_ok = sys.version_info[:2] >= MIN_PYTHON
44
+ checks.append(
45
+ DoctorCheck(
46
+ name="python",
47
+ ok=py_ok,
48
+ detail=(
49
+ f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
50
+ if py_ok
51
+ else (
52
+ f"{sys.version_info.major}.{sys.version_info.minor} "
53
+ f"(need >={MIN_PYTHON[0]}.{MIN_PYTHON[1]})"
54
+ )
55
+ ),
56
+ )
57
+ )
58
+
59
+ git_path = shutil.which("git")
60
+ checks.append(
61
+ DoctorCheck(
62
+ name="git",
63
+ ok=git_path is not None,
64
+ detail=git_path or "not found in PATH (required for clone and grok demo)",
65
+ )
66
+ )
67
+
68
+ uv_path = shutil.which("uv")
69
+ checks.append(
70
+ DoctorCheck(
71
+ name="uv",
72
+ ok=True,
73
+ detail=(
74
+ uv_path
75
+ if uv_path
76
+ else "not found (optional; pip install -e . also works)"
77
+ ),
78
+ )
79
+ )
80
+
81
+ cards_dir = repo_root / "docs" / "evidence_cards"
82
+ registry = repo_root / "docs" / "registry" / "evidence_index.json"
83
+ repo_ok = cards_dir.is_dir() and registry.is_file()
84
+ installed = not repo_ok and not (repo_root / "pyproject.toml").is_file()
85
+ if installed:
86
+ checks.append(
87
+ DoctorCheck(
88
+ name="repo_layout",
89
+ ok=True,
90
+ detail=(
91
+ "installed package, no repository clone: validate-card, inspect, hash and "
92
+ "run-root work; validate-all, demo, rerun, drift and verify need "
93
+ "git clone https://github.com/protocolith/protocolith.git"
94
+ ),
95
+ )
96
+ )
97
+ else:
98
+ checks.append(
99
+ DoctorCheck(
100
+ name="repo_layout",
101
+ ok=repo_ok,
102
+ detail=(
103
+ "evidence cards and registry present"
104
+ if repo_ok
105
+ else "missing docs/evidence_cards or docs/registry/evidence_index.json"
106
+ ),
107
+ )
108
+ )
109
+
110
+ return DoctorReport(
111
+ checks=tuple(checks),
112
+ platform_system=platform.system(),
113
+ platform_release=platform.release(),
114
+ python_version=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
115
+ repo_root=repo_root.resolve(),
116
+ runs_root=Path.home() / "protocolith_runs",
117
+ today_iso=date.today().isoformat(),
118
+ mode="installed-package" if installed else "checkout",
119
+ )
120
+
121
+
122
+ def format_doctor_report(report: DoctorReport) -> str:
123
+ lines = [
124
+ f"platform={report.platform_system} {report.platform_release}",
125
+ f"python={report.python_version}",
126
+ f"mode={report.mode}",
127
+ *([] if report.mode == "installed-package" else [f"repo_root={report.repo_root.as_posix()}"]),
128
+ f"runs_root={report.runs_root.as_posix()}",
129
+ f"today={report.today_iso}",
130
+ ]
131
+ for check in report.checks:
132
+ status = "ok" if check.ok else "FAIL"
133
+ lines.append(f"{check.name}={status} ({check.detail})")
134
+ lines.append(f"ready={'yes' if report.ok else 'no'}")
135
+ return "\n".join(lines)
@@ -0,0 +1,354 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Validation helpers for Protocolith evidence cards."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ import re
8
+ from datetime import date
9
+ from pathlib import Path
10
+ from typing import Any
11
+ from urllib.parse import urlparse
12
+
13
+ ALLOWED_EXECUTION_MODES = {
14
+ "MANUAL_NO_AI",
15
+ "AUTOMATED_AI_ASSISTED",
16
+ }
17
+
18
+ ALLOWED_RESULT_STATUSES = {
19
+ "PASSED_UNDER_PROTOCOL",
20
+ "NEGATIVE_RESULT_UNDER_PROTOCOL",
21
+ "BLOCKED_SOURCE",
22
+ "INSUFFICIENT_COVERAGE",
23
+ "SOURCE_DRIFT",
24
+ "REPRODUCED_OUTCOME",
25
+ }
26
+
27
+ ALLOWED_REPRODUCTION_LEVELS = {
28
+ "not independently reproduced",
29
+ "REPRODUCED_OUTCOME",
30
+ "REPRODUCED_OUTCOME_WITH_SOURCE_BYTE_DRIFT",
31
+ }
32
+
33
+ ALLOWED_RECORD_TYPES = {
34
+ "evidence_result",
35
+ "source_audit",
36
+ "protocol_registration",
37
+ "reproduction_attempt",
38
+ }
39
+
40
+ ALLOWED_VERIFICATION_LEVELS = {
41
+ "SINGLE_OPERATOR",
42
+ "SINGLE_OPERATOR_RERUN",
43
+ "INDEPENDENT_RERUN",
44
+ "MULTI_OPERATOR",
45
+ "NOT_EXECUTED",
46
+ }
47
+
48
+ REQUIRED_FIELDS = {
49
+ "evidence_id",
50
+ "registry_sequence",
51
+ "record_type",
52
+ "protocol_id",
53
+ "protocol_version",
54
+ "domain",
55
+ "claim_type",
56
+ "execution_mode",
57
+ "result_status",
58
+ "claim_boundary",
59
+ "official_source_name",
60
+ "official_source_url",
61
+ "access_date",
62
+ "source_rights_note",
63
+ "raw_payload_committed",
64
+ "raw_payload_manifest",
65
+ "sanitized_report_path",
66
+ "sanitized_report_sha256",
67
+ "git_commit",
68
+ "runner_command",
69
+ "operator",
70
+ "created_at",
71
+ "last_verified_date",
72
+ "verification_count",
73
+ "verification_level",
74
+ "reproduction_level",
75
+ "ai_assistance",
76
+ "manual_review",
77
+ "known_limitations",
78
+ }
79
+
80
+ FORECAST_REQUIRED_FIELDS = {
81
+ "forecast_question",
82
+ "answer_timestamp",
83
+ "forecast_deadline",
84
+ "resolution_deadline",
85
+ "model_or_method",
86
+ "resolution_rule",
87
+ "allowed_resolution_sources",
88
+ "scoring_rule",
89
+ }
90
+
91
+ FORBIDDEN_CLAIM_FRAGMENTS = {
92
+ "best model",
93
+ "model is best",
94
+ "broad model superiority",
95
+ "deployment ready",
96
+ "deployment-ready",
97
+ "production ready",
98
+ "universal forecasting edge",
99
+ "universal effect",
100
+ "proves correctness outside",
101
+ }
102
+
103
+ # Cards created before this policy remain readable as historical records. Every
104
+ # card created on or after the cutoff must bind the result to a concrete public
105
+ # statement. This is deliberately date based so a producer cannot opt out by
106
+ # choosing an older schema version or record type.
107
+ PUBLIC_CLAIM_POLICY_START = date(2026, 7, 26)
108
+ PUBLIC_CLAIM_REQUIRED_FIELDS = {
109
+ "public_claim_text",
110
+ "public_claim_verbatim_quote",
111
+ "public_claim_source_url",
112
+ "public_claim_locator",
113
+ "public_claim_captured_at",
114
+ "public_claim_source_sha256",
115
+ }
116
+ _SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
117
+ _CANDIDATE_QUESTION_FRAGMENTS = {
118
+ "the public claim about",
119
+ "the published number for",
120
+ "can be traced to one exact public source",
121
+ "does not silently exclude",
122
+ }
123
+
124
+
125
+ def load_evidence_card(path: Path) -> dict[str, Any]:
126
+ data = json.loads(path.read_text(encoding="utf-8"))
127
+ if not isinstance(data, dict):
128
+ raise ValueError("evidence card must be a JSON object")
129
+ return data
130
+
131
+
132
+ def validate_evidence_card(card: dict[str, Any]) -> list[str]:
133
+ violations: list[str] = []
134
+
135
+ missing = sorted(field for field in REQUIRED_FIELDS if _is_missing(card.get(field)))
136
+ violations.extend(f"missing required field: {field}" for field in missing)
137
+
138
+ execution_mode = card.get("execution_mode")
139
+ if execution_mode not in ALLOWED_EXECUTION_MODES:
140
+ violations.append(
141
+ "execution_mode must be one of: "
142
+ + ", ".join(sorted(ALLOWED_EXECUTION_MODES))
143
+ )
144
+
145
+ result_status = card.get("result_status")
146
+ if result_status == "REPRODUCED_OUTCOME_WITH_SOURCE_BYTE_DRIFT":
147
+ violations.append(
148
+ "result_status must not be REPRODUCED_OUTCOME_WITH_SOURCE_BYTE_DRIFT; "
149
+ "set reproduction_level instead and keep result_status as the gate outcome"
150
+ )
151
+ elif result_status not in ALLOWED_RESULT_STATUSES:
152
+ violations.append(
153
+ "result_status must be one of: "
154
+ + ", ".join(sorted(ALLOWED_RESULT_STATUSES))
155
+ )
156
+
157
+ reproduction_level = card.get("reproduction_level")
158
+ if reproduction_level not in ALLOWED_REPRODUCTION_LEVELS:
159
+ violations.append(
160
+ "reproduction_level must be one of: "
161
+ + ", ".join(sorted(ALLOWED_REPRODUCTION_LEVELS))
162
+ )
163
+
164
+ record_type = card.get("record_type")
165
+ if record_type not in ALLOWED_RECORD_TYPES:
166
+ violations.append(
167
+ "record_type must be one of: "
168
+ + ", ".join(sorted(ALLOWED_RECORD_TYPES))
169
+ )
170
+
171
+ if card.get("raw_payload_committed") is not False:
172
+ violations.append("raw_payload_committed must be false")
173
+
174
+ registry_sequence = card.get("registry_sequence")
175
+ if not isinstance(registry_sequence, int) or registry_sequence < 1:
176
+ violations.append("registry_sequence must be a positive integer")
177
+
178
+ verification_count = card.get("verification_count")
179
+ if not isinstance(verification_count, int) or verification_count < 0:
180
+ violations.append("verification_count must be a non-negative integer")
181
+
182
+ verification_level = card.get("verification_level")
183
+ if verification_level not in ALLOWED_VERIFICATION_LEVELS:
184
+ violations.append(
185
+ "verification_level must be one of: "
186
+ + ", ".join(sorted(ALLOWED_VERIFICATION_LEVELS))
187
+ )
188
+
189
+ claim_type = str(card.get("claim_type", "")).lower()
190
+ if claim_type == "forecast":
191
+ missing_forecast = sorted(
192
+ field for field in FORECAST_REQUIRED_FIELDS if _is_missing(card.get(field))
193
+ )
194
+ violations.extend(
195
+ f"missing forecast field: {field}" for field in missing_forecast
196
+ )
197
+
198
+ if result_status == "PASSED_UNDER_PROTOCOL" and _is_missing(
199
+ card.get("baseline_control_summary")
200
+ ):
201
+ violations.append("positive records must include baseline_control_summary")
202
+
203
+ if result_status == "BLOCKED_SOURCE" and _is_missing(card.get("block_reason")):
204
+ violations.append("blocked records must include block_reason")
205
+
206
+ if result_status == "SOURCE_DRIFT" and _is_missing(card.get("drift_reason")):
207
+ violations.append("source drift records must include drift_reason")
208
+
209
+ text = json.dumps(card, sort_keys=True).lower()
210
+ for fragment in sorted(FORBIDDEN_CLAIM_FRAGMENTS):
211
+ if fragment in text:
212
+ violations.append(f"forbidden broad claim fragment: {fragment!r}")
213
+
214
+ mode_text = str(card.get("execution_mode", ""))
215
+ ai_assistance = str(card.get("ai_assistance", "")).lower()
216
+ if "AI_ASSISTED" in mode_text and ai_assistance in {"", "none", "not used"}:
217
+ violations.append("AI-assisted execution modes must describe ai_assistance")
218
+
219
+ if mode_text.endswith("_NO_AI") and "used" in ai_assistance and "not used" not in ai_assistance:
220
+ violations.append("NO_AI execution modes must not describe AI use")
221
+
222
+ violations.extend(_validate_public_claim_binding(card))
223
+
224
+ return violations
225
+
226
+
227
+ _ISO_DATE_PREFIX_RE = re.compile(r"^\d{4}-\d{2}-\d{2}")
228
+ _DATE_FIELDS = ("access_date", "created_at", "last_verified_date")
229
+ _MIN_CLAIM_BOUNDARY_CHARS = 20
230
+
231
+
232
+ def warn_evidence_card(card: dict[str, Any]) -> list[str]:
233
+ """Return non-fatal hardening warnings for a card.
234
+
235
+ These checks are intentionally separate from :func:`validate_evidence_card`:
236
+ they must never turn an already published historical card into a failure.
237
+ Callers report counts so new violations are visible without reclassifying
238
+ or editing any card.
239
+ """
240
+ warnings: list[str] = []
241
+
242
+ sha = card.get("sanitized_report_sha256")
243
+ if not _is_missing(sha) and not (isinstance(sha, str) and _SHA256_RE.fullmatch(sha)):
244
+ warnings.append("sanitized_report_sha256 should be a lowercase 64-hex SHA-256 digest")
245
+
246
+ for field in _DATE_FIELDS:
247
+ value = card.get(field)
248
+ if _is_missing(value):
249
+ continue
250
+ if not _is_iso_date_prefix(value):
251
+ warnings.append(f"{field} should start with an ISO-8601 date (YYYY-MM-DD)")
252
+
253
+ boundary = card.get("claim_boundary")
254
+ if not _is_missing(boundary) and (
255
+ not isinstance(boundary, str) or len(boundary.strip()) < _MIN_CLAIM_BOUNDARY_CHARS
256
+ ):
257
+ warnings.append(
258
+ f"claim_boundary should be a string of at least {_MIN_CLAIM_BOUNDARY_CHARS} characters"
259
+ )
260
+
261
+ limitations = card.get("known_limitations")
262
+ if not _is_missing(limitations) and not (
263
+ isinstance(limitations, list)
264
+ and all(isinstance(item, str) and item.strip() for item in limitations)
265
+ ):
266
+ warnings.append("known_limitations should be a list of non-empty strings")
267
+
268
+ url = card.get("official_source_url")
269
+ if not _is_missing(url):
270
+ parsed = urlparse(str(url))
271
+ if parsed.scheme not in {"https", "http"} or not parsed.netloc:
272
+ warnings.append("official_source_url should be an absolute http(s) URL")
273
+
274
+ evidence_id = card.get("evidence_id")
275
+ if isinstance(evidence_id, str) and evidence_id != evidence_id.strip():
276
+ warnings.append("evidence_id should not have surrounding whitespace")
277
+
278
+ if (
279
+ isinstance(card.get("verification_count"), int)
280
+ and card.get("verification_count") == 0
281
+ and card.get("verification_level") not in {None, "NOT_EXECUTED"}
282
+ and card.get("result_status") in {"PASSED_UNDER_PROTOCOL", "NEGATIVE_RESULT_UNDER_PROTOCOL"}
283
+ ):
284
+ warnings.append("verification_count is 0 although an executed result_status is recorded")
285
+
286
+ return warnings
287
+
288
+
289
+ def _is_iso_date_prefix(value: object) -> bool:
290
+ text = str(value)
291
+ if not _ISO_DATE_PREFIX_RE.match(text):
292
+ return False
293
+ try:
294
+ date.fromisoformat(text[:10])
295
+ except ValueError:
296
+ return False
297
+ return True
298
+
299
+
300
+ def _validate_public_claim_binding(card: dict[str, Any]) -> list[str]:
301
+ """Require a source-bound public statement for every newly created card."""
302
+ created = str(card.get("created_at", ""))[:10]
303
+ try:
304
+ policy_applies = date.fromisoformat(created) >= PUBLIC_CLAIM_POLICY_START
305
+ except ValueError:
306
+ return [] # The ordinary required-field validation handles bad/missing values.
307
+ if not policy_applies:
308
+ return []
309
+
310
+ violations: list[str] = []
311
+ missing = sorted(
312
+ field for field in PUBLIC_CLAIM_REQUIRED_FIELDS if _is_missing(card.get(field))
313
+ )
314
+ violations.extend(f"missing public claim field: {field}" for field in missing)
315
+ if missing:
316
+ return violations
317
+
318
+ claim = str(card["public_claim_text"]).strip()
319
+ quote = str(card["public_claim_verbatim_quote"]).strip()
320
+ locator = str(card["public_claim_locator"]).strip()
321
+ source_url = str(card["public_claim_source_url"]).strip()
322
+ source_sha256 = str(card["public_claim_source_sha256"]).strip()
323
+
324
+ if len(claim) < 20 or claim.endswith("?"):
325
+ violations.append("public_claim_text must be a concrete declarative statement")
326
+ lowered_claim = claim.lower()
327
+ if any(fragment in lowered_claim for fragment in _CANDIDATE_QUESTION_FRAGMENTS):
328
+ violations.append("public_claim_text must not be a generated gate template")
329
+ if len(quote) < 20:
330
+ violations.append("public_claim_verbatim_quote must contain a substantive source excerpt")
331
+ if len(locator) < 8:
332
+ violations.append("public_claim_locator must identify the quote within the source")
333
+ parsed = urlparse(source_url)
334
+ if parsed.scheme != "https" or not parsed.netloc:
335
+ violations.append("public_claim_source_url must be an absolute HTTPS URL")
336
+ if not _SHA256_RE.fullmatch(source_sha256):
337
+ violations.append("public_claim_source_sha256 must be a lowercase SHA-256 digest")
338
+ try:
339
+ captured = date.fromisoformat(str(card["public_claim_captured_at"])[:10])
340
+ if captured > date.fromisoformat(created):
341
+ violations.append("public_claim_captured_at must not be later than created_at")
342
+ except ValueError:
343
+ violations.append("public_claim_captured_at must start with an ISO date")
344
+ return violations
345
+
346
+
347
+ def _is_missing(value: object) -> bool:
348
+ if value is None:
349
+ return True
350
+ if isinstance(value, str) and value.strip() == "":
351
+ return True
352
+ if isinstance(value, (list, tuple, dict, set)) and len(value) == 0:
353
+ return True
354
+ return False