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,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
|