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,68 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """``capture``: a JSON fragment describing the environment and input files, for a record ``outcome``.
3
+
4
+ It reads only the files it is asked to hash (inside the current directory) and no environment variable values.
5
+ Nothing is executed.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import platform
12
+ import sys
13
+ from collections.abc import Iterable
14
+ from importlib import metadata
15
+ from pathlib import Path
16
+ from typing import Any
17
+
18
+ from .errors import EnvError, InputError, io_guard
19
+
20
+ _CHUNK = 1 << 20
21
+
22
+
23
+ def _version() -> str:
24
+ try:
25
+ return metadata.version("protocolith")
26
+ except metadata.PackageNotFoundError: # running from a source tree that is not installed
27
+ return "unknown"
28
+
29
+
30
+ def environment() -> dict[str, str]:
31
+ return {
32
+ "machine": platform.machine(),
33
+ "platform": sys.platform,
34
+ "protocolith": _version(),
35
+ "python": platform.python_version(),
36
+ }
37
+
38
+
39
+ def describe_file(name: str, base: Path) -> dict[str, Any]:
40
+ """Relative path, size and sha256 of a regular file inside ``base`` (symbolic links are resolved first)."""
41
+ if "\x00" in name:
42
+ raise EnvError("IO_ERROR", "a path must not contain a NUL byte")
43
+ with io_guard():
44
+ root = base.resolve()
45
+ path = (root / name).resolve()
46
+ try:
47
+ relative = path.relative_to(root)
48
+ except ValueError:
49
+ raise InputError("BAD_PATH", f"{name}: the file is outside the current directory") from None
50
+ if not path.is_file():
51
+ raise InputError("BAD_PATH", f"{name}: not an existing regular file")
52
+ digest = hashlib.sha256()
53
+ size = 0
54
+ with open(path, "rb") as handle:
55
+ while chunk := handle.read(_CHUNK):
56
+ digest.update(chunk)
57
+ size += len(chunk)
58
+ return {"path": relative.as_posix(), "sha256": digest.hexdigest(), "size": size}
59
+
60
+
61
+ def capture(files: Iterable[str] = (), *, env: bool = False, base: Path | None = None) -> dict[str, Any]:
62
+ """The fragment ``{"environment": ..., "inputs": [...]}``; the environment is included with ``env`` or when no file is named."""
63
+ names = list(files)
64
+ here = base or Path.cwd()
65
+ fragment: dict[str, Any] = {"inputs": [describe_file(name, here) for name in names]}
66
+ if env or not names:
67
+ fragment["environment"] = environment()
68
+ return fragment
@@ -0,0 +1,25 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Injectable UTC clock with whole-second ISO timestamps."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import os
7
+ from collections.abc import Callable
8
+ from datetime import datetime, UTC
9
+
10
+ from .errors import InputError
11
+ from .ledger import is_ts
12
+
13
+ ENV_NOW = "PROTOCOLITH_NOW"
14
+ Clock = Callable[[], str]
15
+
16
+
17
+ def now_utc(clock: Clock | None = None) -> str:
18
+ """The current timestamp: ``clock`` if given, else ``PROTOCOLITH_NOW``, else the system clock."""
19
+ if clock is not None:
20
+ value = clock()
21
+ else:
22
+ value = os.environ.get(ENV_NOW) or datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
23
+ if not is_ts(value):
24
+ raise InputError("BAD_CLOCK", f"timestamp must look like YYYY-MM-DDTHH:MM:SSZ, got {value!r}")
25
+ return value
@@ -0,0 +1,356 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """CLI glue for the core commands. Exit codes: 0 ok, 1 verification failed, 2 input, 3 environment."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import sys
8
+ from collections.abc import Callable
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+ from typing import Any
12
+
13
+ from . import ops
14
+ from .atlas import DEFAULT_OUT, DEFAULT_TITLE, build_atlas_result, write_atlas
15
+ from .capture import capture
16
+ from .canonical import decode, encode
17
+ from .errors import InputError, ProtocolithError, hint_for, io_guard
18
+ from .ledger import ENTRY_TYPES, RESULT_STATUSES
19
+ from .mcp import serve
20
+ from .schema import NAMES, all_schemas, schema_for
21
+ from .store import Store, resolve_store
22
+
23
+
24
+ @dataclass
25
+ class Outcome:
26
+ data: Any
27
+ text: str
28
+ code: int = 0
29
+ errors: str = ""
30
+
31
+
32
+ def read_input(path: str) -> Any:
33
+ """Read FILE as strict JSON (no duplicate keys, no floats)."""
34
+ with io_guard():
35
+ raw = Path(path).read_bytes()
36
+ try:
37
+ return decode(raw)
38
+ except ProtocolithError as exc:
39
+ raise InputError(exc.code, f"{path}: {exc.message}") from None
40
+
41
+
42
+ def _fail(args: argparse.Namespace, exc: ProtocolithError) -> int:
43
+ print(f"protocolith: {exc.code}: {exc.message}", file=sys.stderr)
44
+ for violation in exc.violations:
45
+ print(f" {violation.code} line {violation.seq}: {violation.message}", file=sys.stderr)
46
+ for code in exc.codes():
47
+ if (hint := hint_for(code)) is not None:
48
+ print(f" hint ({code}): {hint}", file=sys.stderr)
49
+ if args.json:
50
+ print(encode(exc.to_dict()).decode("utf-8"))
51
+ return exc.exit_code
52
+
53
+
54
+ def _run(args: argparse.Namespace, work: Callable[[Store], Outcome]) -> int:
55
+ try:
56
+ outcome = work(resolve_store(args.store))
57
+ except ProtocolithError as exc:
58
+ return _fail(args, exc)
59
+ if outcome.errors:
60
+ print(outcome.errors, file=sys.stderr)
61
+ print(encode(outcome.data).decode("utf-8") if args.json else outcome.text)
62
+ return outcome.code
63
+
64
+
65
+ def _cmd_freeze(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
66
+ def work(store: Store) -> Outcome:
67
+ entry = ops.freeze(store, read_input(args.file), supersedes=args.supersedes)
68
+ body = entry["body"]
69
+ text = f"frozen {body['protocol_id']} {body['version']} seq={entry['seq']} hash={entry['hash']}"
70
+ return Outcome(entry, text + f" protocol_sha256={body['protocol_sha256']}")
71
+
72
+ return _run(args, work)
73
+
74
+
75
+ def _cmd_record(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
76
+ def work(store: Store) -> Outcome:
77
+ entry = ops.record(store, read_input(args.file))
78
+ body = entry["body"]
79
+ return Outcome(entry, f"recorded {body['run_id']} {body['status']} seq={entry['seq']} hash={entry['hash']}")
80
+
81
+ return _run(args, work)
82
+
83
+
84
+ def _cmd_deviation(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
85
+ def work(store: Store) -> Outcome:
86
+ entry = ops.deviation(store, read_input(args.file))
87
+ return Outcome(entry, f"deviation {entry['body']['kind']} seq={entry['seq']} hash={entry['hash']}")
88
+
89
+ return _run(args, work)
90
+
91
+
92
+ def _cmd_verify_ledger(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
93
+ def work(store: Store) -> Outcome:
94
+ verdict = ops.verify(store, args.expect_head)
95
+ if verdict.ok:
96
+ head = f"head seq={verdict.head_seq} hash={verdict.head_hash}" if verdict.count else "empty"
97
+ return Outcome(verdict.to_dict(), f"OK entries={verdict.count} {head}")
98
+ lines = [f"{v.code} line {v.seq}: {v.message}" for v in verdict.violations]
99
+ lines += [f"hint ({code}): {hint}" for code in verdict.codes if (hint := hint_for(code)) is not None]
100
+ return Outcome(verdict.to_dict(), "FAILED: " + ", ".join(verdict.codes), 1, "\n".join(lines))
101
+
102
+ return _run(args, work)
103
+
104
+
105
+ def _cmd_issue(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
106
+ def work(store: Store) -> Outcome:
107
+ result = ops.issue(store, args.seq, out=args.out)
108
+ text = f"issued record seq={args.seq} card_sha256={result['entry']['body']['card_sha256']}"
109
+ return Outcome(result, f"{text}\n{result['json_path']}\n{result['svg_path']}")
110
+
111
+ return _run(args, work)
112
+
113
+
114
+ _SUMMARY: dict[str, Callable[[dict[str, Any]], str]] = {
115
+ "freeze": lambda body: f"{body['protocol_id']} {body['version']}",
116
+ "record": lambda body: f"{body['run_id']} {body['status']}",
117
+ "deviation": lambda body: body["kind"],
118
+ "issue": lambda body: f"record_seq={body['record_seq']}",
119
+ }
120
+
121
+
122
+ def _cmd_log(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
123
+ def work(store: Store) -> Outcome:
124
+ found = ops.log(store, protocol=args.protocol, type=args.type, status=args.status, tail=args.tail)
125
+ lines = [f"{e['seq']} {e['type']} {e['ts']} {e['hash'][:12]} {_SUMMARY[e['type']](e['body'])}" for e in found]
126
+ return Outcome(found, "\n".join(lines))
127
+
128
+ return _run(args, work)
129
+
130
+
131
+ def _cmd_show(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
132
+ def work(store: Store) -> Outcome:
133
+ found = ops.show(store, args.seq)
134
+ entry, context = found["entry"], found["protocol"]
135
+ lines = [f"seq {entry['seq']} {entry['type']} {entry['ts']}", f"hash {entry['hash']}", f"prev {entry['prev']}"]
136
+ lines.append(f"protocol {context['protocol_id']} {context['version']} (frozen at seq {context['freeze_seq']})")
137
+ lines.append("points at: " + (", ".join(map(str, found["points_at"])) or "-"))
138
+ lines.append("pointed at by: " + (", ".join(map(str, found["pointed_by"])) or "-"))
139
+ lines.append("body: " + encode(entry["body"]).decode("utf-8"))
140
+ return Outcome(found, "\n".join(lines))
141
+
142
+ return _run(args, work)
143
+
144
+
145
+ def _table(header: list[str], rows: list[list[str]]) -> list[str]:
146
+ widths = [max(len(row[i]) for row in [header, *rows]) for i in range(len(header))]
147
+ return [
148
+ " ".join(cell.ljust(width) for cell, width in zip(row, widths, strict=True)).rstrip()
149
+ for row in [header, *rows]
150
+ ]
151
+
152
+
153
+ def _counts(counts: dict[str, int]) -> str:
154
+ return ", ".join(f"{name} {count}" for name, count in counts.items()) or "none"
155
+
156
+
157
+ def _summary_text(found: dict[str, Any]) -> str:
158
+ head = found["head"]
159
+ state = "OK" if found["ok"] else "FAILED"
160
+ where = f"head seq={head['seq']} hash={head['hash']}" if head["count"] else "empty"
161
+ lines = [f"ledger {state} entries={head['count']} {where}", f"entries: {_counts(found['entries_by_type'])}"]
162
+ lines.append(f"results: {_counts(found['records_by_status'])}")
163
+ rows = [
164
+ [
165
+ row["protocol_id"],
166
+ ",".join(row["versions"]),
167
+ row["latest_version"],
168
+ str(row["records"]),
169
+ row["latest_status"] or "-",
170
+ str(row["deviations"]),
171
+ str(row["cards"]),
172
+ ]
173
+ for row in found["protocols"]
174
+ ]
175
+ if rows:
176
+ lines += _table(["PROTOCOL", "VERSIONS", "LATEST", "RECORDS", "LATEST_STATUS", "DEVIATIONS", "CARDS"], rows)
177
+ lines.append("problems: " + ("none" if not found["problems"] else str(len(found["problems"]))))
178
+ lines += [f" {p['code']} line {p['seq']}: {p['message']}" for p in found["problems"]]
179
+ return "\n".join(lines)
180
+
181
+
182
+ def _cmd_summary(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
183
+ def work(store: Store) -> Outcome:
184
+ found = ops.summary(store, args.protocol)
185
+ return Outcome(found, _summary_text(found), 0 if found["ok"] else 1)
186
+
187
+ return _run(args, work)
188
+
189
+
190
+ def _cmd_init(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
191
+ def work(store: Store) -> Outcome:
192
+ found = ops.init(store)
193
+ return Outcome(found, f"{'created' if found['created'] else 'exists'} {found['path']}")
194
+
195
+ return _run(args, work)
196
+
197
+
198
+ def _cmd_capture(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
199
+ try:
200
+ fragment = capture(args.file, env=args.env)
201
+ except ProtocolithError as exc:
202
+ return _fail(args, exc)
203
+ print(encode(fragment).decode("utf-8"))
204
+ return 0
205
+
206
+
207
+ def _cmd_schema(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
208
+ print(encode(all_schemas() if args.name == "all" else schema_for(args.name)).decode("utf-8"))
209
+ return 0
210
+
211
+
212
+ def _cmd_head(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
213
+ def work(store: Store) -> Outcome:
214
+ found = ops.head(store)
215
+ text = f"seq={found['seq']} hash={found['hash']}" if found["count"] else "empty"
216
+ return Outcome(found, text)
217
+
218
+ return _run(args, work)
219
+
220
+
221
+ def _cmd_repair(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
222
+ def work(store: Store) -> Outcome:
223
+ removed = ops.repair_truncate_partial_tail(store)
224
+ return Outcome({"ok": True, "removed_bytes": removed}, f"removed {removed} bytes of partial tail")
225
+
226
+ return _run(args, work)
227
+
228
+
229
+ def _cmd_atlas(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
230
+ try:
231
+ result = build_atlas_result(
232
+ store=args.store,
233
+ cards=args.cards,
234
+ title=args.title,
235
+ i18n_dir=args.i18n,
236
+ default_lang=args.default_lang,
237
+ max_rows=args.max_rows,
238
+ )
239
+ path = write_atlas(result.html, args.out)
240
+ except ProtocolithError as exc:
241
+ return _fail(args, exc)
242
+ for warning in result.warnings:
243
+ print(f"warning: {warning}", file=sys.stderr)
244
+ if result.ledger is not None and not result.ledger["ok"]:
245
+ print(f"ledger FAILED verification ({result.ledger['problem_count']} problems); the atlas shows a warning", file=sys.stderr)
246
+ data = {**result.to_dict(), "path": str(path)}
247
+ state = "" if result.ok else " ledger=FAILED"
248
+ text = f"wrote {path} bytes={len(result.html)} records={result.total} shown={result.shown} skipped={result.skipped}{state}"
249
+ print(encode(data).decode("utf-8") if args.json else text)
250
+ return 0 if result.ok else 1
251
+
252
+
253
+ def _cmd_mcp(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
254
+ serve(resolve_store(args.store), sys.stdin.buffer, sys.stdout.buffer)
255
+ return 0
256
+
257
+
258
+ def add_core_commands(subparsers: Any) -> None:
259
+ """Register the ledger commands on the main parser (additive)."""
260
+ common = argparse.ArgumentParser(add_help=False)
261
+ common.add_argument("--store", default=None, help="Store directory (env PROTOCOLITH_STORE, default .protocolith).")
262
+ with_json = argparse.ArgumentParser(add_help=False, parents=[common])
263
+ with_json.add_argument("--json", action="store_true", help="Print the result as canonical JSON.")
264
+
265
+ def add(
266
+ name: str, func: Callable[..., int], help_text: str, parent: argparse.ArgumentParser
267
+ ) -> argparse.ArgumentParser:
268
+ parser: argparse.ArgumentParser = subparsers.add_parser(
269
+ name, parents=[parent], help=help_text, description=help_text
270
+ )
271
+ parser.set_defaults(func=func)
272
+ return parser
273
+
274
+ freeze = add("freeze", _cmd_freeze, "Freeze a protocol from a JSON file.", with_json)
275
+ freeze.add_argument("file", metavar="FILE")
276
+ freeze.add_argument(
277
+ "--supersedes", default=None, metavar="SHA256", help="Hash of the protocol version this replaces."
278
+ )
279
+ add("record", _cmd_record, "Record a run outcome from a JSON file.", with_json).add_argument("file", metavar="FILE")
280
+ add("deviation", _cmd_deviation, "Record a deviation from a JSON file.", with_json).add_argument(
281
+ "file", metavar="FILE"
282
+ )
283
+ verify = add("verify-ledger", _cmd_verify_ledger, "Verify the ledger (rules R1 to R11).", with_json)
284
+ verify.add_argument(
285
+ "--expect-head",
286
+ default=None,
287
+ metavar="SEQ:HASH",
288
+ help="Also require the entry at SEQ to have this hash (detects a removed tail); else HEAD_MISMATCH, exit 1.",
289
+ )
290
+ issue = add("issue", _cmd_issue, "Issue the evidence card of a record.", with_json)
291
+ issue.add_argument("seq", type=int, metavar="SEQ")
292
+ issue.add_argument("--out", default=None, metavar="DIR", help="Card directory (default <store>/cards).")
293
+ log = add("log", _cmd_log, "List ledger entries, optionally filtered.", with_json)
294
+ log.add_argument("--protocol", default=None, metavar="ID", help="Only entries of this protocol_id.")
295
+ log.add_argument("--type", default=None, choices=ENTRY_TYPES, help="Only entries of this type.")
296
+ log.add_argument(
297
+ "--status", default=None, choices=sorted(RESULT_STATUSES), help="Only records with this result status."
298
+ )
299
+ log.add_argument("--tail", default=None, type=int, metavar="N", help="Keep only the last N matching entries.")
300
+ add("show", _cmd_show, "Show one entry with its protocol context.", with_json).add_argument(
301
+ "seq", type=int, metavar="SEQ"
302
+ )
303
+ summary = add("summary", _cmd_summary, "Verdict, head, counts and a per-protocol table in one call.", with_json)
304
+ summary.add_argument("--protocol", default=None, metavar="ID", help="Only this protocol_id.")
305
+ add("init", _cmd_init, "Create the store with an empty ledger (safe to repeat).", with_json)
306
+ capture_parser = subparsers.add_parser(
307
+ "capture",
308
+ help="Print a JSON fragment (environment, input file hashes) for a record outcome.",
309
+ description="Print a JSON fragment for the outcome object of a record: Python, platform, machine and "
310
+ "protocolith version, and the relative path, size and sha256 of each --file (inside the current directory). "
311
+ "Runs nothing and reads no environment values.",
312
+ )
313
+ capture_parser.set_defaults(func=_cmd_capture)
314
+ capture_parser.add_argument("--json", action="store_true", help="Print errors as canonical JSON.")
315
+ capture_parser.add_argument(
316
+ "--file", action="append", default=[], metavar="PATH", help="File to hash; repeat for several."
317
+ )
318
+ capture_parser.add_argument(
319
+ "--env", action="store_true", help="Include the environment (implied when no --file is given)."
320
+ )
321
+ schema_parser = subparsers.add_parser(
322
+ "schema",
323
+ help="Print the JSON Schema of an input body.",
324
+ description="Print a JSON Schema (draft 2020-12) generated from the rules.",
325
+ )
326
+ schema_parser.set_defaults(func=_cmd_schema)
327
+ schema_parser.add_argument(
328
+ "name", nargs="?", default="all", choices=[*NAMES, "all"], help="Which schema (default all)."
329
+ )
330
+ add("head", _cmd_head, "Print the ledger head (last hash and seq).", with_json)
331
+ repair = add("repair", _cmd_repair, "Repair a crash-damaged ledger.", with_json)
332
+ repair.add_argument(
333
+ "--truncate-partial-tail", action="store_true", required=True, help="Remove the partial last line."
334
+ )
335
+ atlas = add(
336
+ "atlas",
337
+ _cmd_atlas,
338
+ "Build a self-contained offline HTML atlas of experiments from a ledger and/or evidence card directories.",
339
+ with_json,
340
+ )
341
+ atlas.add_argument(
342
+ "--cards",
343
+ action="append",
344
+ default=[],
345
+ metavar="DIR",
346
+ help="Directory of evidence card JSON files, searched recursively; repeat for several. "
347
+ "Without --store and --cards: a local ledger, else docs/evidence_cards.",
348
+ )
349
+ atlas.add_argument("--out", default=DEFAULT_OUT, metavar="FILE_OR_DIR", help=f"Output .html file or directory (default {DEFAULT_OUT}).")
350
+ atlas.add_argument("--title", default=DEFAULT_TITLE, metavar="TEXT", help="Page title.")
351
+ atlas.add_argument(
352
+ "--i18n", default=None, metavar="DIR", help="Directory of <code>.json translation files; adds a language switcher."
353
+ )
354
+ atlas.add_argument("--default-lang", default="en", metavar="CODE", help="Initial language (default en).")
355
+ atlas.add_argument("--max-rows", default=None, type=int, metavar="N", help="Embed at most N records (the newest); counts stay complete.")
356
+ add("mcp", _cmd_mcp, "Run the MCP server on stdio.", common)
@@ -0,0 +1,116 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Error types shared by the core. Every error carries a stable machine code."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from collections.abc import Iterator, Sequence
7
+ from contextlib import contextmanager
8
+ from dataclasses import dataclass
9
+ from typing import Any
10
+
11
+
12
+ # One-line advice per code, shown after the error. Codes without an entry have no hint.
13
+ HINTS: dict[str, str] = {
14
+ "NO_LEDGER": "run `protocolith freeze FILE` (or `protocolith init`) to start a ledger, or check --store / PROTOCOLITH_STORE",
15
+ "LOCK_TIMEOUT": "another protocolith process holds the store lock; wait for it to finish and retry",
16
+ "HEAD_MISMATCH": "the ledger is not the one you anchored: an entry was removed or replaced; compare with your published head",
17
+ "TRUNCATED_TAIL": "a write was interrupted; run `protocolith repair --truncate-partial-tail`",
18
+ "NO_PARTIAL_TAIL": "nothing to repair: the last line is complete",
19
+ "DUPLICATE_FREEZE": "a changed protocol needs a new `version`; freeze it with --supersedes HASH of the old one",
20
+ "UNKNOWN_PROTOCOL": "freeze the protocol first and copy its protocol_sha256 into the entry",
21
+ "BAD_STATUS": "use one of: PASSED_UNDER_PROTOCOL, NEGATIVE_RESULT_UNDER_PROTOCOL, BLOCKED_SOURCE, "
22
+ "INSUFFICIENT_COVERAGE, SOURCE_DRIFT, REPRODUCED_OUTCOME",
23
+ "MISSING_FIELD": "run `protocolith schema` to see the required fields",
24
+ "BAD_ENTRY": "run `protocolith schema` to see the allowed fields; unknown keys are rejected",
25
+ "DANGLING_REF": "refer only to an earlier entry of the right type (see `protocolith log`)",
26
+ "TS_REGRESSION": "the clock is earlier than the last entry; fix the system time or PROTOCOLITH_NOW",
27
+ "CARD_EXISTS": "a different card with this evidence_id is already there; use another --out directory",
28
+ "CARD_CONFLICT": "remove the contradicting keys from the record `card` object",
29
+ "CARD_INVALID": "fix the record `card` object; `protocolith validate-card` shows the validator output",
30
+ "FLOAT_NOT_ALLOWED": 'write decimals as strings, for example "0.55"',
31
+ "DUPLICATE_KEY": "an object repeats a key; remove the duplicate",
32
+ "BAD_JSON": "the file is not valid JSON (a byte-order mark is also refused)",
33
+ "BAD_PATH": "name an existing regular file inside the current directory",
34
+ "IO_ERROR": "check that the path exists and is readable and writable",
35
+ }
36
+
37
+
38
+ def hint_for(code: str) -> str | None:
39
+ return HINTS.get(code)
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class Violation:
44
+ """One rule violation: the rule code, the ledger line index and a message."""
45
+
46
+ code: str
47
+ seq: int
48
+ message: str
49
+
50
+ def to_dict(self) -> dict[str, Any]:
51
+ return {"code": self.code, "message": self.message, "seq": self.seq}
52
+
53
+
54
+ class ProtocolithError(Exception):
55
+ exit_code = 2
56
+
57
+ def __init__(self, code: str, message: str, violations: Sequence[Violation] = ()) -> None:
58
+ # Messages may echo user text; keep them encodable as UTF-8 everywhere.
59
+ self.message = message.encode("utf-8", "backslashreplace").decode("utf-8")
60
+ self.code = code
61
+ self.violations = tuple(violations)
62
+ super().__init__(f"{code}: {self.message}")
63
+
64
+ def codes(self) -> list[str]:
65
+ found = {v.code for v in self.violations} or {self.code}
66
+ return sorted(found)
67
+
68
+ @property
69
+ def hint(self) -> str | None:
70
+ return hint_for(self.code)
71
+
72
+ def to_dict(self) -> dict[str, Any]:
73
+ error = {"code": self.code, "message": self.message}
74
+ if self.hint is not None:
75
+ error["hint"] = self.hint
76
+ return {
77
+ "codes": self.codes(),
78
+ "error": error,
79
+ "ok": False,
80
+ "violations": [v.to_dict() for v in self.violations],
81
+ }
82
+
83
+
84
+ class InputError(ProtocolithError):
85
+ """Bad input or a rejected operation (CLI exit code 2)."""
86
+
87
+ exit_code = 2
88
+
89
+
90
+ class EnvError(ProtocolithError):
91
+ """I/O or environment problem (CLI exit code 3)."""
92
+
93
+ exit_code = 3
94
+
95
+
96
+ class VerificationFailed(ProtocolithError):
97
+ """The stored ledger does not verify (CLI exit code 1)."""
98
+
99
+ exit_code = 1
100
+
101
+ def __init__(self, violations: Sequence[Violation]) -> None:
102
+ codes = ", ".join(sorted({v.code for v in violations}))
103
+ super().__init__("VERIFICATION_FAILED", f"ledger does not verify: {codes}", violations)
104
+
105
+
106
+ @contextmanager
107
+ def io_guard() -> Iterator[None]:
108
+ """Turn OSError (and a NUL in a path) into EnvError so no raw I/O error escapes the API."""
109
+ try:
110
+ yield
111
+ except OSError as exc:
112
+ raise EnvError("IO_ERROR", f"{type(exc).__name__}: {exc}") from exc
113
+ except ValueError as exc:
114
+ if "embedded null" not in str(exc): # a NUL in a path is a ValueError, not an OSError
115
+ raise
116
+ raise EnvError("IO_ERROR", f"{type(exc).__name__}: {exc}") from exc
@@ -0,0 +1,98 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Build, validate and write the evidence card for a record."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import os
7
+ import re
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from protocolith.card_svg_render import render_svg
12
+ from protocolith.evidence_card import validate_evidence_card
13
+
14
+ from .canonical import encode, sha256_hex
15
+ from .errors import InputError
16
+ from .rules import Verifier
17
+
18
+ _MISSING_RE = re.compile(r"^missing (?:required |forecast |public claim )?field: (\w+)$")
19
+ _MUST_INCLUDE_RE = re.compile(r"must include (\w+)$")
20
+ _XML_INVALID = re.compile("[\x00-\x08\x0b\x0c\x0e-\x1f\ufffe\uffff]") # not allowed in XML 1.0 documents
21
+
22
+
23
+ def _missing_names(violations: list[str]) -> list[str]:
24
+ names: set[str] = set()
25
+ for text in violations:
26
+ found = _MISSING_RE.match(text) or _MUST_INCLUDE_RE.search(text)
27
+ if found:
28
+ names.add(found.group(1))
29
+ return sorted(names)
30
+
31
+
32
+ def build_card(verifier: Verifier, record_seq: int) -> dict[str, Any]:
33
+ """Derive the card for the record at ``record_seq`` from the ledger state held by ``verifier``."""
34
+ entry = verifier.entries[record_seq]
35
+ body = entry["body"]
36
+ frozen = verifier.protocols.get(body["protocol_sha256"])
37
+ if frozen is None:
38
+ raise InputError("UNKNOWN_PROTOCOL", "the record names a protocol that is not frozen")
39
+ day = entry["ts"][:10]
40
+ fixed: dict[str, Any] = {
41
+ "claim_boundary": body["claim_boundary"],
42
+ "created_at": entry["ts"],
43
+ "evidence_id": f"PLITH-{frozen['protocol_id']}-{day}-{record_seq:06d}",
44
+ "ledger_record_seq": record_seq,
45
+ "protocol_id": frozen["protocol_id"],
46
+ "protocol_sha256": body["protocol_sha256"],
47
+ "protocol_version": frozen["version"],
48
+ "raw_payload_committed": False,
49
+ "reproduction_level": body["reproduction_level"],
50
+ "result_status": body["status"],
51
+ "sources": body["sources"],
52
+ }
53
+ for reason in ("block_reason", "drift_reason"):
54
+ if reason in body:
55
+ fixed[reason] = body[reason]
56
+ extra: dict[str, Any] = body.get("card", {})
57
+ conflicts = sorted(key for key in extra if key in fixed and extra[key] != fixed[key])
58
+ if conflicts:
59
+ raise InputError("CARD_CONFLICT", "card fields contradict the record: " + ", ".join(conflicts))
60
+ defaults = {"last_verified_date": day, "record_type": "evidence_result", "registry_sequence": record_seq + 1}
61
+ card = {**defaults, **extra, **fixed}
62
+ try:
63
+ violations = validate_evidence_card(card)
64
+ except Exception as exc: # the validator was written for trusted input; card metadata is user data
65
+ raise InputError("CARD_INVALID", f"card cannot be validated: {type(exc).__name__}") from None
66
+ if violations:
67
+ names = _missing_names(violations)
68
+ if names:
69
+ raise InputError("MISSING_FIELD", "card is missing fields: " + ", ".join(names))
70
+ raise InputError("CARD_INVALID", "; ".join(violations))
71
+ return card
72
+
73
+
74
+ def card_hash(verifier: Verifier, record_seq: int) -> str:
75
+ return sha256_hex(build_card(verifier, record_seq))
76
+
77
+
78
+ def _atomic_write(path: Path, data: bytes) -> None:
79
+ tmp = path.with_name(path.name + ".tmp")
80
+ with open(tmp, "wb") as handle:
81
+ handle.write(data)
82
+ handle.flush()
83
+ os.fsync(handle.fileno())
84
+ os.replace(tmp, path)
85
+
86
+
87
+ def write_card_files(card: dict[str, Any], out_dir: Path) -> tuple[Path, Path]:
88
+ """Write ``<evidence_id>.json`` (PCJ-1 bytes) and ``.svg``; refuse to replace a different card."""
89
+ out_dir.mkdir(parents=True, exist_ok=True)
90
+ json_path = out_dir / f"{card['evidence_id']}.json"
91
+ svg_path = json_path.with_suffix(".svg")
92
+ payload = encode(card)
93
+ if json_path.exists() and json_path.read_bytes() != payload:
94
+ raise InputError("CARD_EXISTS", f"{json_path.name} already exists with different content; use another --out")
95
+ _atomic_write(json_path, payload)
96
+ # Card text is user data and may hold characters XML 1.0 forbids; the JSON card keeps them verbatim.
97
+ _atomic_write(svg_path, _XML_INVALID.sub("\ufffd", render_svg(json_path)).encode("utf-8"))
98
+ return json_path, svg_path