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,302 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Deterministic read-only static views of the public evidence registry.
|
|
3
|
+
|
|
4
|
+
Reads ``docs/registry/evidence_index.json`` (validated against every referenced
|
|
5
|
+
card JSON) and renders Markdown pages plus one self-contained HTML page under
|
|
6
|
+
``docs/registry/views/``. Output depends only on the index and the repository
|
|
7
|
+
file tree; it contains no wall-clock timestamps and no raw payloads.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import html
|
|
13
|
+
import re
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Any
|
|
16
|
+
|
|
17
|
+
from protocolith.registry import load_registry, validate_registry
|
|
18
|
+
|
|
19
|
+
INDEX_REL = "docs/registry/evidence_index.json"
|
|
20
|
+
VIEWS_REL = "docs/registry/views"
|
|
21
|
+
# (index field, row key, label)
|
|
22
|
+
FILTERS = (
|
|
23
|
+
("result_status", "status", "Status"),
|
|
24
|
+
("official_source_name", "source", "Source"),
|
|
25
|
+
("domain", "domain", "Domain"),
|
|
26
|
+
("audience", "audience", "Audience"),
|
|
27
|
+
("reproduction_level", "repro", "Reproduction level"),
|
|
28
|
+
)
|
|
29
|
+
REPO_NOTE = (
|
|
30
|
+
"Read-only generated view of `docs/registry/evidence_index.json`. "
|
|
31
|
+
"Do not edit by hand; regenerate with "
|
|
32
|
+
"`uv run python scripts/protocolith_build_registry_view.py`. "
|
|
33
|
+
"No raw payloads are stored here."
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class RegistryViewError(RuntimeError):
|
|
38
|
+
"""Raised when the index does not validate against the card JSON files."""
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def slug(value: str) -> str:
|
|
42
|
+
out = re.sub(r"[^A-Za-z0-9]+", "-", value).strip("-").lower()
|
|
43
|
+
return out or "unknown"
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _md(value: Any) -> str:
|
|
47
|
+
return str(value).replace("|", "\\|").replace("\n", " ")
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def validate_registry_strict(registry: dict[str, Any], repo_root: Path) -> None:
|
|
51
|
+
violations = validate_registry(registry, repo_root)
|
|
52
|
+
if violations:
|
|
53
|
+
shown = "\n".join(violations[:20])
|
|
54
|
+
raise RegistryViewError(
|
|
55
|
+
f"registry does not validate against card JSON ({len(violations)} "
|
|
56
|
+
f"violation(s)); first:\n{shown}"
|
|
57
|
+
)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _row(entry: dict[str, Any], repo_root: Path, up: str) -> dict[str, Any]:
|
|
61
|
+
"""Normalise one entry; ``up`` is the relative prefix from views dir to docs/."""
|
|
62
|
+
card_rel = entry["path"]
|
|
63
|
+
docs_rel = card_rel[len("docs/"):] if card_rel.startswith("docs/") else card_rel
|
|
64
|
+
svg_rel = docs_rel[:-5] + ".svg" if docs_rel.endswith(".json") else ""
|
|
65
|
+
has_svg = bool(svg_rel) and (repo_root / "docs" / svg_rel).is_file()
|
|
66
|
+
return {
|
|
67
|
+
"seq": entry["registry_sequence"],
|
|
68
|
+
"id": entry["evidence_id"],
|
|
69
|
+
"status": entry["result_status"],
|
|
70
|
+
"source": entry["official_source_name"],
|
|
71
|
+
"domain": entry["domain"],
|
|
72
|
+
"audience": str(entry.get("audience", "")),
|
|
73
|
+
"repro": entry["reproduction_level"],
|
|
74
|
+
"record_type": entry["record_type"],
|
|
75
|
+
"json": up + docs_rel,
|
|
76
|
+
"svg": (up + svg_rel) if has_svg else "",
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _md_table(rows: list[dict[str, Any]]) -> list[str]:
|
|
81
|
+
lines = [
|
|
82
|
+
"| # | Evidence | Status | Domain | Source | Reproduction level | Card | SVG |",
|
|
83
|
+
"|---:|---|---|---|---|---|---|---|",
|
|
84
|
+
]
|
|
85
|
+
for r in rows:
|
|
86
|
+
svg = f"[svg]({r['svg']})" if r["svg"] else "n/a"
|
|
87
|
+
lines.append(
|
|
88
|
+
f"| {r['seq']} | `{_md(r['id'])}` | {_md(r['status'])} | {_md(r['domain'])} "
|
|
89
|
+
f"| {_md(r['source'])} | {_md(r['repro'])} | [json]({r['json']}) | {svg} |"
|
|
90
|
+
)
|
|
91
|
+
return lines
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _counts(rows: list[dict[str, Any]], key: str) -> dict[str, int]:
|
|
95
|
+
out: dict[str, int] = {}
|
|
96
|
+
for r in rows:
|
|
97
|
+
out[r[key]] = out.get(r[key], 0) + 1
|
|
98
|
+
return dict(sorted(out.items()))
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _page(title: str, rows: list[dict[str, Any]], version: str) -> str:
|
|
102
|
+
lines = [
|
|
103
|
+
f"# {title}",
|
|
104
|
+
"",
|
|
105
|
+
f"> {REPO_NOTE}",
|
|
106
|
+
"",
|
|
107
|
+
"[Index](index.md) | [HTML view](index.html)",
|
|
108
|
+
"",
|
|
109
|
+
f"Entries: {len(rows)} (index last_updated: {version})",
|
|
110
|
+
"",
|
|
111
|
+
*_md_table(rows),
|
|
112
|
+
"",
|
|
113
|
+
]
|
|
114
|
+
return "\n".join(lines)
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _index_md(registry: dict[str, Any], rows: list[dict[str, Any]]) -> str:
|
|
118
|
+
lines = [
|
|
119
|
+
"# Protocolith Public Evidence Registry - static view",
|
|
120
|
+
"",
|
|
121
|
+
f"> {REPO_NOTE}",
|
|
122
|
+
"",
|
|
123
|
+
f"- Registry: {registry.get('registry_name')} {registry.get('registry_version')}",
|
|
124
|
+
f"- Index last_updated: {registry.get('last_updated', '')}",
|
|
125
|
+
f"- Entries: {len(rows)}",
|
|
126
|
+
"- Single-file filterable view: [index.html](index.html)",
|
|
127
|
+
"",
|
|
128
|
+
"## By result status",
|
|
129
|
+
"",
|
|
130
|
+
"| Status | Entries |",
|
|
131
|
+
"|---|---:|",
|
|
132
|
+
]
|
|
133
|
+
for s, n in _counts(rows, "status").items():
|
|
134
|
+
lines.append(f"| [{_md(s)}](status-{slug(s)}.md) | {n} |")
|
|
135
|
+
lines += ["", "## By domain", "", "| Domain | Entries |", "|---|---:|"]
|
|
136
|
+
for d, n in _counts(rows, "domain").items():
|
|
137
|
+
lines.append(f"| [{_md(d)}](domain-{slug(d)}.md) | {n} |")
|
|
138
|
+
lines.append("")
|
|
139
|
+
return "\n".join(lines)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _index_html(registry: dict[str, Any], rows: list[dict[str, Any]]) -> str:
|
|
143
|
+
esc = html.escape
|
|
144
|
+
version = esc(str(registry.get("last_updated", "")))
|
|
145
|
+
filters = []
|
|
146
|
+
for _field, key, label in FILTERS:
|
|
147
|
+
values = sorted({r[key] for r in rows if r[key]})
|
|
148
|
+
if not values:
|
|
149
|
+
continue # field absent from index data (e.g. audience): no empty filter
|
|
150
|
+
opts = "".join(f'<option value="{esc(v)}">{esc(v)}</option>' for v in values)
|
|
151
|
+
filters.append(
|
|
152
|
+
f'<label>{esc(label)} <select data-filter="{key}">'
|
|
153
|
+
f'<option value="">All</option>{opts}</select></label>'
|
|
154
|
+
)
|
|
155
|
+
body_rows = []
|
|
156
|
+
for r in rows:
|
|
157
|
+
svg = f'<a href="{esc(r["svg"])}">svg</a>' if r["svg"] else "n/a"
|
|
158
|
+
body_rows.append(
|
|
159
|
+
f'<tr data-status="{esc(r["status"])}" data-source="{esc(r["source"])}" '
|
|
160
|
+
f'data-domain="{esc(r["domain"])}" data-audience="{esc(r["audience"])}" '
|
|
161
|
+
f'data-repro="{esc(r["repro"])}">'
|
|
162
|
+
f'<th scope="row">{r["seq"]}</th>'
|
|
163
|
+
f'<td><code>{esc(r["id"])}</code></td><td>{esc(r["status"])}</td>'
|
|
164
|
+
f'<td>{esc(r["domain"])}</td><td>{esc(r["source"])}</td>'
|
|
165
|
+
f'<td>{esc(r["repro"])}</td>'
|
|
166
|
+
f'<td><a href="{esc(r["json"])}">json</a></td><td>{svg}</td></tr>'
|
|
167
|
+
)
|
|
168
|
+
head = "".join(
|
|
169
|
+
f'<th scope="col">{c}</th>'
|
|
170
|
+
for c in ("#", "Evidence", "Status", "Domain", "Source",
|
|
171
|
+
"Reproduction level", "Card", "SVG")
|
|
172
|
+
)
|
|
173
|
+
nl = "\n"
|
|
174
|
+
return f"""<!DOCTYPE html>
|
|
175
|
+
<html lang="en">
|
|
176
|
+
<head>
|
|
177
|
+
<meta charset="utf-8">
|
|
178
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
179
|
+
<title>Protocolith Public Evidence Registry</title>
|
|
180
|
+
<style>
|
|
181
|
+
:root{{color-scheme:light dark;--bg:#fff;--fg:#1a1a1a;--muted:#555;--line:#ccc;--head:#f0f0f0;--link:#0b5cad}}
|
|
182
|
+
@media (prefers-color-scheme:dark){{:root{{--bg:#121212;--fg:#e8e8e8;--muted:#aaa;--line:#444;--head:#222;--link:#7ab8ff}}}}
|
|
183
|
+
body{{margin:0 auto;max-width:90rem;padding:1rem;background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,sans-serif}}
|
|
184
|
+
a{{color:var(--link)}}
|
|
185
|
+
.filters{{display:flex;flex-wrap:wrap;gap:.75rem;margin:1rem 0}}
|
|
186
|
+
.filters[hidden]{{display:none}}
|
|
187
|
+
select{{max-width:22rem;background:var(--bg);color:var(--fg);border:1px solid var(--line);padding:.25rem}}
|
|
188
|
+
.wrap{{overflow-x:auto}}
|
|
189
|
+
table{{border-collapse:collapse;width:100%}}
|
|
190
|
+
caption{{text-align:left;font-weight:600;padding:.5rem 0}}
|
|
191
|
+
th,td{{border:1px solid var(--line);padding:.3rem .5rem;text-align:left;vertical-align:top}}
|
|
192
|
+
thead th{{background:var(--head)}}
|
|
193
|
+
code{{font-size:.85em;word-break:break-all}}
|
|
194
|
+
.muted{{color:var(--muted)}}
|
|
195
|
+
</style>
|
|
196
|
+
</head>
|
|
197
|
+
<body>
|
|
198
|
+
<h1>Protocolith Public Evidence Registry</h1>
|
|
199
|
+
<p class="muted">Read-only generated view of <code>docs/registry/evidence_index.json</code>
|
|
200
|
+
(last_updated {version}). {len(rows)} entries. No raw payloads are stored here.
|
|
201
|
+
Markdown pages: <a href="index.md">index.md</a>.</p>
|
|
202
|
+
<div class="filters" id="filters" role="search" aria-label="Filter registry entries" hidden>
|
|
203
|
+
{nl.join(filters)}
|
|
204
|
+
<span id="count" role="status" aria-live="polite"></span>
|
|
205
|
+
</div>
|
|
206
|
+
<div class="wrap">
|
|
207
|
+
<table id="registry">
|
|
208
|
+
<caption>Evidence registry entries, ordered by registry sequence</caption>
|
|
209
|
+
<thead><tr>{head}</tr></thead>
|
|
210
|
+
<tbody>
|
|
211
|
+
{nl.join(body_rows)}
|
|
212
|
+
</tbody>
|
|
213
|
+
</table>
|
|
214
|
+
</div>
|
|
215
|
+
<script>
|
|
216
|
+
(function(){{
|
|
217
|
+
var box=document.getElementById('filters');
|
|
218
|
+
if(!box)return;
|
|
219
|
+
box.hidden=false;
|
|
220
|
+
var sels=box.querySelectorAll('select[data-filter]');
|
|
221
|
+
var rows=document.querySelectorAll('#registry tbody tr');
|
|
222
|
+
var count=document.getElementById('count');
|
|
223
|
+
function apply(){{
|
|
224
|
+
var n=0;
|
|
225
|
+
for(var i=0;i<rows.length;i++){{
|
|
226
|
+
var ok=true;
|
|
227
|
+
for(var j=0;j<sels.length;j++){{
|
|
228
|
+
var v=sels[j].value;
|
|
229
|
+
if(v&&rows[i].getAttribute('data-'+sels[j].getAttribute('data-filter'))!==v){{ok=false;break;}}
|
|
230
|
+
}}
|
|
231
|
+
rows[i].hidden=!ok;
|
|
232
|
+
if(ok)n++;
|
|
233
|
+
}}
|
|
234
|
+
count.textContent=n+' of '+rows.length+' shown';
|
|
235
|
+
}}
|
|
236
|
+
for(var k=0;k<sels.length;k++)sels[k].addEventListener('change',apply);
|
|
237
|
+
apply();
|
|
238
|
+
}})();
|
|
239
|
+
</script>
|
|
240
|
+
</body>
|
|
241
|
+
</html>
|
|
242
|
+
"""
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def build_views_from_registry(registry: dict[str, Any], repo_root: Path) -> dict[str, str]:
|
|
246
|
+
"""Render views from an already-validated registry dict."""
|
|
247
|
+
rows = [_row(e, repo_root, "../../") for e in registry["cards"]]
|
|
248
|
+
rows.sort(key=lambda r: r["seq"])
|
|
249
|
+
version = str(registry.get("last_updated", ""))
|
|
250
|
+
out: dict[str, str] = {
|
|
251
|
+
"index.md": _index_md(registry, rows),
|
|
252
|
+
"index.html": _index_html(registry, rows),
|
|
253
|
+
}
|
|
254
|
+
for key, prefix, label in (("status", "status", "Status"), ("domain", "domain", "Domain")):
|
|
255
|
+
groups: dict[str, list[dict[str, Any]]] = {}
|
|
256
|
+
for r in rows:
|
|
257
|
+
groups.setdefault(r[key], []).append(r)
|
|
258
|
+
seen: dict[str, str] = {}
|
|
259
|
+
for value in sorted(groups):
|
|
260
|
+
name = f"{prefix}-{slug(value)}.md"
|
|
261
|
+
if name in seen:
|
|
262
|
+
raise RegistryViewError(f"slug collision: {value!r} vs {seen[name]!r}")
|
|
263
|
+
seen[name] = value
|
|
264
|
+
out[name] = _page(f"{label}: {value}", groups[value], version)
|
|
265
|
+
return out
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
def build_views(repo_root: Path) -> dict[str, str]:
|
|
269
|
+
"""Validate the index against card JSON, then render. Raises RegistryViewError."""
|
|
270
|
+
registry = load_registry(repo_root / INDEX_REL)
|
|
271
|
+
validate_registry_strict(registry, repo_root)
|
|
272
|
+
return build_views_from_registry(registry, repo_root)
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
def write_views(repo_root: Path) -> list[str]:
|
|
276
|
+
content = build_views(repo_root)
|
|
277
|
+
vdir = repo_root / VIEWS_REL
|
|
278
|
+
vdir.mkdir(parents=True, exist_ok=True)
|
|
279
|
+
for p in sorted(vdir.iterdir()):
|
|
280
|
+
if p.is_file() and p.name not in content and p.name != "README.md":
|
|
281
|
+
p.unlink()
|
|
282
|
+
for name, text in content.items():
|
|
283
|
+
(vdir / name).write_bytes(text.encode("utf-8"))
|
|
284
|
+
return sorted(content)
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
def check_views(repo_root: Path) -> list[str]:
|
|
288
|
+
"""Return a list of problems (empty when committed views are current)."""
|
|
289
|
+
content = build_views(repo_root)
|
|
290
|
+
vdir = repo_root / VIEWS_REL
|
|
291
|
+
problems: list[str] = []
|
|
292
|
+
for name, text in sorted(content.items()):
|
|
293
|
+
p = vdir / name
|
|
294
|
+
if not p.is_file():
|
|
295
|
+
problems.append(f"missing: {name}")
|
|
296
|
+
elif p.read_bytes().replace(b"\r\n", b"\n") != text.encode("utf-8"):
|
|
297
|
+
problems.append(f"stale: {name}")
|
|
298
|
+
if vdir.is_dir():
|
|
299
|
+
for p in sorted(vdir.iterdir()):
|
|
300
|
+
if p.is_file() and p.name not in content and p.name != "README.md":
|
|
301
|
+
problems.append(f"unexpected: {p.name}")
|
|
302
|
+
return problems
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Independent rerun report: reproduction status and source-byte drift.
|
|
3
|
+
|
|
4
|
+
The helper only compares hashes the operator supplies. It never reads, edits
|
|
5
|
+
or reclassifies an evidence card or its original claim.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
REPRODUCTION_STATUSES = (
|
|
15
|
+
"NOT_RERUN",
|
|
16
|
+
"REPRODUCED",
|
|
17
|
+
"PARTIALLY_REPRODUCED",
|
|
18
|
+
"NOT_REPRODUCED",
|
|
19
|
+
"SOURCE_DRIFT",
|
|
20
|
+
"BLOCKED_SOURCE",
|
|
21
|
+
)
|
|
22
|
+
DRIFT_CLASSES = ("NO_DRIFT", "SOURCE_BYTE_DRIFT", "MISSING_ORIGINAL", "MISSING_RERUN")
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def classify_hashes(original: dict[str, str], rerun: dict[str, str]) -> dict[str, Any]:
|
|
26
|
+
"""Compare name -> sha256 maps and classify per-file and overall drift."""
|
|
27
|
+
|
|
28
|
+
files: dict[str, str] = {}
|
|
29
|
+
for name in sorted(set(original) | set(rerun)):
|
|
30
|
+
if name not in rerun:
|
|
31
|
+
files[name] = "MISSING_RERUN"
|
|
32
|
+
elif name not in original:
|
|
33
|
+
files[name] = "MISSING_ORIGINAL"
|
|
34
|
+
elif original[name] == rerun[name]:
|
|
35
|
+
files[name] = "NO_DRIFT"
|
|
36
|
+
else:
|
|
37
|
+
files[name] = "SOURCE_BYTE_DRIFT"
|
|
38
|
+
drifted = any(v != "NO_DRIFT" for v in files.values())
|
|
39
|
+
return {"drift": "SOURCE_BYTE_DRIFT" if drifted else "NO_DRIFT", "files": files}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def suggest_status(outcome_matches: bool | None, drift: str, blocked: bool = False) -> str:
|
|
43
|
+
"""Suggest a vocabulary status from operator-supplied facts."""
|
|
44
|
+
|
|
45
|
+
if blocked:
|
|
46
|
+
return "BLOCKED_SOURCE"
|
|
47
|
+
if outcome_matches is None:
|
|
48
|
+
return "NOT_RERUN"
|
|
49
|
+
if not outcome_matches:
|
|
50
|
+
return "NOT_REPRODUCED"
|
|
51
|
+
return "SOURCE_DRIFT" if drift != "NO_DRIFT" else "REPRODUCED"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def build_report(
|
|
55
|
+
original: dict[str, str],
|
|
56
|
+
rerun: dict[str, str],
|
|
57
|
+
*,
|
|
58
|
+
outcome_matches: bool | None,
|
|
59
|
+
blocked: bool = False,
|
|
60
|
+
operator_note: str = "",
|
|
61
|
+
) -> dict[str, Any]:
|
|
62
|
+
drift = classify_hashes(original, rerun)
|
|
63
|
+
report: dict[str, Any] = {
|
|
64
|
+
"reproduction_status": suggest_status(outcome_matches, drift["drift"], blocked),
|
|
65
|
+
"source_drift": drift,
|
|
66
|
+
"card_modified": False,
|
|
67
|
+
}
|
|
68
|
+
if operator_note:
|
|
69
|
+
report["operator_note"] = operator_note
|
|
70
|
+
errors = validate_report(report)
|
|
71
|
+
if errors:
|
|
72
|
+
raise ValueError("; ".join(errors))
|
|
73
|
+
return report
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def validate_report(report: dict[str, Any]) -> list[str]:
|
|
77
|
+
"""Validate the optional rerun-report fields; absent fields are fine."""
|
|
78
|
+
|
|
79
|
+
errors: list[str] = []
|
|
80
|
+
status = report.get("reproduction_status")
|
|
81
|
+
if status is not None and status not in REPRODUCTION_STATUSES:
|
|
82
|
+
errors.append(f"reproduction_status must be one of {list(REPRODUCTION_STATUSES)}")
|
|
83
|
+
drift = report.get("source_drift")
|
|
84
|
+
if drift is not None:
|
|
85
|
+
if not isinstance(drift, dict) or drift.get("drift") not in ("NO_DRIFT", "SOURCE_BYTE_DRIFT"):
|
|
86
|
+
errors.append("source_drift.drift must be NO_DRIFT or SOURCE_BYTE_DRIFT")
|
|
87
|
+
else:
|
|
88
|
+
for name, cls in (drift.get("files") or {}).items():
|
|
89
|
+
if cls not in DRIFT_CLASSES:
|
|
90
|
+
errors.append(f"source_drift.files[{name}] invalid: {cls}")
|
|
91
|
+
note = report.get("operator_note")
|
|
92
|
+
if note is not None and not isinstance(note, str):
|
|
93
|
+
errors.append("operator_note must be a string")
|
|
94
|
+
return errors
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def load_hash_map(path: Path) -> dict[str, str]:
|
|
98
|
+
"""Load a JSON {name: sha256} map or a `sha256 name` text file."""
|
|
99
|
+
|
|
100
|
+
text = path.read_text(encoding="utf-8")
|
|
101
|
+
if path.suffix == ".json":
|
|
102
|
+
data = json.loads(text)
|
|
103
|
+
if not isinstance(data, dict) or not all(isinstance(v, str) for v in data.values()):
|
|
104
|
+
raise ValueError(f"{path}: expected a JSON object of name -> sha256")
|
|
105
|
+
return dict(data)
|
|
106
|
+
result: dict[str, str] = {}
|
|
107
|
+
for line in text.splitlines():
|
|
108
|
+
parts = line.split(None, 1)
|
|
109
|
+
if len(parts) == 2:
|
|
110
|
+
result[parts[1].strip().lstrip("*")] = parts[0]
|
|
111
|
+
return result
|
protocolith/run_root.py
ADDED
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Local-only run-root helpers for Protocolith operators."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import json
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from datetime import UTC, datetime
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
RUN_ROOT_SUBDIRS = ("raw", "logs", "hashes", "reports", "transcripts")
|
|
13
|
+
DEVIATION_JSONL = "deviations.jsonl"
|
|
14
|
+
SOURCE_RIGHTS_FILE = "SOURCE_RIGHTS_CHECKLIST.md"
|
|
15
|
+
SOURCE_RIGHTS_ANSWERS = "source_rights_answers.jsonl"
|
|
16
|
+
DEVIATION_FIELDS = ("timestamp", "step", "planned", "happened", "reason", "who")
|
|
17
|
+
|
|
18
|
+
SOURCE_RIGHTS_QUESTIONS: tuple[tuple[str, str], ...] = (
|
|
19
|
+
("terms", "Did you read the source's terms of use or license? What do they say about automated access and reuse?"),
|
|
20
|
+
("robots", "What does the source's robots.txt (or equivalent access policy) say about the paths you fetch?"),
|
|
21
|
+
("attribution", "What attribution does the source require, if any?"),
|
|
22
|
+
("redistribution", "What does the source say about redistributing raw bytes or derived hashes?"),
|
|
23
|
+
("rate_limits", "Are there published rate limits or API key conditions, and did the run respect them?"),
|
|
24
|
+
("personal_data", "Does the payload contain personal or sensitive data that must stay local?"),
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True)
|
|
29
|
+
class RunRootRequest:
|
|
30
|
+
protocol_id: str
|
|
31
|
+
operator: str
|
|
32
|
+
source_url: str
|
|
33
|
+
root: Path
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def prepare_run_root(request: RunRootRequest) -> list[Path]:
|
|
37
|
+
"""Create a local-only Protocolith run root with standard operator files."""
|
|
38
|
+
|
|
39
|
+
protocol_id = _normalize_protocol_id(request.protocol_id)
|
|
40
|
+
created_at = datetime.now(UTC).replace(microsecond=0).isoformat()
|
|
41
|
+
run_dir = request.root / _run_dir_name(protocol_id)
|
|
42
|
+
run_dir.mkdir(parents=True, exist_ok=False)
|
|
43
|
+
|
|
44
|
+
created: list[Path] = [run_dir]
|
|
45
|
+
for subdir in RUN_ROOT_SUBDIRS:
|
|
46
|
+
path = run_dir / subdir
|
|
47
|
+
path.mkdir()
|
|
48
|
+
created.append(path)
|
|
49
|
+
|
|
50
|
+
context_path = run_dir / "RUN_CONTEXT.md"
|
|
51
|
+
context_path.write_text(
|
|
52
|
+
_render_run_context(protocol_id, request.operator, request.source_url, created_at),
|
|
53
|
+
encoding="utf-8",
|
|
54
|
+
)
|
|
55
|
+
created.append(context_path)
|
|
56
|
+
|
|
57
|
+
deviation_path = run_dir / "DEVIATIONS.md"
|
|
58
|
+
deviation_path.write_text(_render_deviation_log(protocol_id), encoding="utf-8")
|
|
59
|
+
created.append(deviation_path)
|
|
60
|
+
|
|
61
|
+
jsonl_path = run_dir / DEVIATION_JSONL
|
|
62
|
+
jsonl_path.touch()
|
|
63
|
+
created.append(jsonl_path)
|
|
64
|
+
|
|
65
|
+
rights_path = run_dir / SOURCE_RIGHTS_FILE
|
|
66
|
+
rights_path.write_text(_render_source_rights(protocol_id), encoding="utf-8")
|
|
67
|
+
created.append(rights_path)
|
|
68
|
+
|
|
69
|
+
manifest_path = run_dir / "LOCAL_MANIFEST.md"
|
|
70
|
+
manifest_path.write_text(_render_local_manifest(protocol_id), encoding="utf-8")
|
|
71
|
+
created.append(manifest_path)
|
|
72
|
+
|
|
73
|
+
return created
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _run_dir_name(protocol_id: str) -> str:
|
|
77
|
+
stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
|
|
78
|
+
return f"{protocol_id.lower()}_{stamp}"
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _normalize_protocol_id(protocol_id: str) -> str:
|
|
82
|
+
normalized = protocol_id.strip().upper().replace("-", "_").replace(" ", "_")
|
|
83
|
+
if not normalized:
|
|
84
|
+
raise ValueError("protocol_id must not be empty")
|
|
85
|
+
return normalized
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _render_run_context(
|
|
89
|
+
protocol_id: str, operator: str, source_url: str, created_at: str
|
|
90
|
+
) -> str:
|
|
91
|
+
return f"""# Protocolith Local Run Context
|
|
92
|
+
|
|
93
|
+
This directory is local-only. Do not commit raw payloads, transcripts, source
|
|
94
|
+
downloads or private logs from this run root.
|
|
95
|
+
|
|
96
|
+
## Run
|
|
97
|
+
|
|
98
|
+
- Protocol ID: {protocol_id}
|
|
99
|
+
- Operator: {operator}
|
|
100
|
+
- Source URL: {source_url}
|
|
101
|
+
- Created at: {created_at}
|
|
102
|
+
|
|
103
|
+
## Freeze Checklist
|
|
104
|
+
|
|
105
|
+
- [ ] I read the protocol before collecting fresh outcomes.
|
|
106
|
+
- [ ] Source, target, selection rule, scoring rule and gate are fixed.
|
|
107
|
+
- [ ] Stop conditions are written down.
|
|
108
|
+
- [ ] Raw payload policy is understood.
|
|
109
|
+
- [ ] Broad forbidden claims are listed.
|
|
110
|
+
|
|
111
|
+
## Output Checklist
|
|
112
|
+
|
|
113
|
+
- [ ] Raw artifacts stayed outside the public repository.
|
|
114
|
+
- [ ] Raw hashes or blocked-hashing reason are recorded.
|
|
115
|
+
- [ ] Commands and logs are recorded.
|
|
116
|
+
- [ ] Sanitized summary can be committed under `artifacts/`.
|
|
117
|
+
- [ ] Evidence card can be validated before registry update.
|
|
118
|
+
"""
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _render_deviation_log(protocol_id: str) -> str:
|
|
122
|
+
return f"""# Deviation Log: {protocol_id}
|
|
123
|
+
|
|
124
|
+
Record every deviation from the frozen protocol. If there were no deviations,
|
|
125
|
+
write `No deviations recorded`.
|
|
126
|
+
|
|
127
|
+
## Deviations
|
|
128
|
+
|
|
129
|
+
| Time | Step | What changed | Why | Effect on status |
|
|
130
|
+
| --- | --- | --- | --- | --- |
|
|
131
|
+
|
|
132
|
+
## Source Drift
|
|
133
|
+
|
|
134
|
+
| Source | Original reference | Fresh reference | Drift observed | Hash or note |
|
|
135
|
+
| --- | --- | --- | --- | --- |
|
|
136
|
+
|
|
137
|
+
## Manual Judgment
|
|
138
|
+
|
|
139
|
+
| Step | Judgment made | Was rule fixed before scoring? | Reviewer note |
|
|
140
|
+
| --- | --- | --- | --- |
|
|
141
|
+
"""
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _render_local_manifest(protocol_id: str) -> str:
|
|
145
|
+
return f"""# Local Manifest: {protocol_id}
|
|
146
|
+
|
|
147
|
+
Use this file to list local-only files and hashes. Do not commit the files
|
|
148
|
+
listed here unless the public data policy explicitly allows it.
|
|
149
|
+
|
|
150
|
+
| Local path | SHA-256 or blocked reason | Public replacement |
|
|
151
|
+
| --- | --- | --- |
|
|
152
|
+
"""
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _render_source_rights(protocol_id: str) -> str:
|
|
156
|
+
lines = [
|
|
157
|
+
f"# Source Rights Checklist: {protocol_id}",
|
|
158
|
+
"",
|
|
159
|
+
"Operator questionnaire. Record what you observed in the source's own",
|
|
160
|
+
"words. This file records operator answers only; it is not a legal",
|
|
161
|
+
"conclusion and does not assert that any use is permitted.",
|
|
162
|
+
"",
|
|
163
|
+
"Record answers with `protocolith run-root rights answer` (append-only",
|
|
164
|
+
f"`{SOURCE_RIGHTS_ANSWERS}`).",
|
|
165
|
+
"",
|
|
166
|
+
]
|
|
167
|
+
for qid, question in SOURCE_RIGHTS_QUESTIONS:
|
|
168
|
+
lines += [f"## {qid}", "", question, "", "- Operator answer: _unanswered_", ""]
|
|
169
|
+
return "\n".join(lines)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def record_rights_answer(run_dir: Path, question_id: str, answer: str, who: str) -> dict[str, str]:
|
|
173
|
+
"""Append an operator answer to the source-rights answers log."""
|
|
174
|
+
|
|
175
|
+
if question_id not in {qid for qid, _ in SOURCE_RIGHTS_QUESTIONS}:
|
|
176
|
+
raise ValueError(f"unknown question id: {question_id}")
|
|
177
|
+
entry = {
|
|
178
|
+
"timestamp": _now(),
|
|
179
|
+
"question_id": question_id,
|
|
180
|
+
"answer": _required(answer, "answer"),
|
|
181
|
+
"who": _required(who, "who"),
|
|
182
|
+
}
|
|
183
|
+
_append_jsonl(_existing_run_dir(run_dir) / SOURCE_RIGHTS_ANSWERS, entry)
|
|
184
|
+
return entry
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def add_deviation(
|
|
188
|
+
run_dir: Path, *, step: str, planned: str, happened: str, reason: str, who: str
|
|
189
|
+
) -> dict[str, str]:
|
|
190
|
+
"""Append one deviation entry to the run root's append-only JSONL log."""
|
|
191
|
+
|
|
192
|
+
entry = {
|
|
193
|
+
"timestamp": _now(),
|
|
194
|
+
"step": _required(step, "step"),
|
|
195
|
+
"planned": _required(planned, "planned"),
|
|
196
|
+
"happened": _required(happened, "happened"),
|
|
197
|
+
"reason": _required(reason, "reason"),
|
|
198
|
+
"who": _required(who, "who"),
|
|
199
|
+
}
|
|
200
|
+
_append_jsonl(_existing_run_dir(run_dir) / DEVIATION_JSONL, entry)
|
|
201
|
+
return entry
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def list_deviations(run_dir: Path) -> list[dict[str, str]]:
|
|
205
|
+
"""Read and validate every deviation entry; raises ValueError on bad lines."""
|
|
206
|
+
|
|
207
|
+
path = _existing_run_dir(run_dir) / DEVIATION_JSONL
|
|
208
|
+
if not path.exists():
|
|
209
|
+
return []
|
|
210
|
+
entries: list[dict[str, str]] = []
|
|
211
|
+
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
|
|
212
|
+
if not line.strip():
|
|
213
|
+
continue
|
|
214
|
+
try:
|
|
215
|
+
entry = json.loads(line)
|
|
216
|
+
except json.JSONDecodeError as exc:
|
|
217
|
+
raise ValueError(f"{DEVIATION_JSONL}:{number}: invalid JSON") from exc
|
|
218
|
+
if not isinstance(entry, dict) or set(entry) != set(DEVIATION_FIELDS):
|
|
219
|
+
raise ValueError(f"{DEVIATION_JSONL}:{number}: fields must be {list(DEVIATION_FIELDS)}")
|
|
220
|
+
entries.append(entry)
|
|
221
|
+
return entries
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
def _now() -> str:
|
|
225
|
+
return datetime.now(UTC).replace(microsecond=0).isoformat()
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def _required(value: str, name: str) -> str:
|
|
229
|
+
value = value.strip()
|
|
230
|
+
if not value:
|
|
231
|
+
raise ValueError(f"{name} must not be empty")
|
|
232
|
+
return value
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _existing_run_dir(run_dir: Path) -> Path:
|
|
236
|
+
if not run_dir.is_dir():
|
|
237
|
+
raise ValueError(f"run root does not exist: {run_dir}")
|
|
238
|
+
return run_dir
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
def _append_jsonl(path: Path, entry: dict[str, str]) -> None:
|
|
242
|
+
with path.open("a", encoding="utf-8") as handle:
|
|
243
|
+
handle.write(json.dumps(entry, ensure_ascii=False, sort_keys=True) + "\n")
|