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