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,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
@@ -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")