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,489 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Validation helpers for Protocolith R&D family ledgers and frontiers."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ ALLOWED_FAMILY_STATUSES = {
11
+ "DRAFT",
12
+ "ACTIVE",
13
+ "STOPPED",
14
+ "CLOSED",
15
+ "SUPERSEDED",
16
+ }
17
+
18
+ PROTOCOL_VERSION_V2 = "protocolith-rnd-family-v2"
19
+
20
+ ALLOWED_FAMILY_TYPES = {
21
+ "source_boundary_family",
22
+ "feature_signal_family",
23
+ "evaluation_family",
24
+ "reproduction_family",
25
+ "systems_performance_family",
26
+ "safety_policy_family",
27
+ "product_decision_family",
28
+ "publication_audit_family",
29
+ }
30
+
31
+ ALLOWED_FRONTIER_STATUSES = {
32
+ "alive",
33
+ "stopped",
34
+ "closed",
35
+ }
36
+
37
+ ALLOWED_CLAIM_CLASSES = {
38
+ "source",
39
+ "availability",
40
+ "causality",
41
+ "diagnostic",
42
+ "predictive",
43
+ "economic",
44
+ "deployment",
45
+ "reproduction",
46
+ "closure",
47
+ }
48
+
49
+ ALLOWED_CLAIM_STATUSES = {
50
+ "DRAFT",
51
+ "FROZEN",
52
+ "PASSED",
53
+ "NEGATIVE",
54
+ "BLOCKED",
55
+ "SUPERSEDED",
56
+ "STOPPED",
57
+ }
58
+
59
+ ALLOWED_TRACK_MODES = {
60
+ "source_audit",
61
+ "diagnostic",
62
+ "proof",
63
+ "reproduction",
64
+ "closure",
65
+ }
66
+
67
+ REQUIRED_TOP_LEVEL_FIELDS = {
68
+ "family_id",
69
+ "family_status",
70
+ "family_type",
71
+ "protocol_version",
72
+ "parent_claim",
73
+ "non_overlap_boundary",
74
+ "proof_surface",
75
+ "proof_surface_hash",
76
+ "allowed_next_tracks",
77
+ "blocked_claim_flags",
78
+ "context_budget",
79
+ "claim_scope",
80
+ "track_budget",
81
+ "stop_rules",
82
+ "claim_list",
83
+ "tracks",
84
+ }
85
+
86
+ REQUIRED_PROOF_SURFACE_FIELDS = {
87
+ "source_surface",
88
+ "selection_surface",
89
+ "label_or_target_surface",
90
+ "candidate_or_method_surface",
91
+ "decision_rule",
92
+ "target_metric",
93
+ "acceptance_gates",
94
+ }
95
+
96
+ REQUIRED_CLAIM_FIELDS = {
97
+ "claim_id",
98
+ "claim_class",
99
+ "status",
100
+ "claim_text",
101
+ "evidence_required",
102
+ "acceptance_gate",
103
+ "forbidden_inference",
104
+ }
105
+
106
+ REQUIRED_TRACK_FIELDS = {
107
+ "track_id",
108
+ "mode",
109
+ "hypothesis_family",
110
+ "claim_ids",
111
+ }
112
+
113
+ BROAD_CLAIM_FRAGMENTS = {
114
+ "best model",
115
+ "deployment ready",
116
+ "deployment-ready",
117
+ "live operation",
118
+ "production ready",
119
+ "universal edge",
120
+ "universal forecasting edge",
121
+ }
122
+
123
+
124
+ def load_family_ledger(path: Path) -> dict[str, Any]:
125
+ data = json.loads(path.read_text(encoding="utf-8"))
126
+ if not isinstance(data, dict):
127
+ raise ValueError("family ledger must be a JSON object")
128
+ return data
129
+
130
+
131
+ def load_frontier_ledger(path: Path) -> dict[str, Any]:
132
+ data = json.loads(path.read_text(encoding="utf-8"))
133
+ if not isinstance(data, dict):
134
+ raise ValueError("frontier ledger must be a JSON object")
135
+ return data
136
+
137
+
138
+ def validate_family_ledger(ledger: dict[str, Any]) -> list[str]:
139
+ violations: list[str] = []
140
+
141
+ missing = sorted(field for field in REQUIRED_TOP_LEVEL_FIELDS if _is_missing(ledger.get(field)))
142
+ violations.extend(f"missing required field: {field}" for field in missing)
143
+
144
+ family_status = ledger.get("family_status")
145
+ if family_status not in ALLOWED_FAMILY_STATUSES:
146
+ violations.append(
147
+ "family_status must be one of: "
148
+ + ", ".join(sorted(ALLOWED_FAMILY_STATUSES))
149
+ )
150
+
151
+ protocol_version = ledger.get("protocol_version")
152
+ if protocol_version != PROTOCOL_VERSION_V2:
153
+ violations.append(f"protocol_version must be {PROTOCOL_VERSION_V2!r}")
154
+
155
+ family_type = ledger.get("family_type")
156
+ if family_type not in ALLOWED_FAMILY_TYPES:
157
+ violations.append(
158
+ "family_type must be one of: "
159
+ + ", ".join(sorted(ALLOWED_FAMILY_TYPES))
160
+ )
161
+
162
+ proof_surface = ledger.get("proof_surface")
163
+ if isinstance(proof_surface, dict):
164
+ missing_surface = sorted(
165
+ field for field in REQUIRED_PROOF_SURFACE_FIELDS if _is_missing(proof_surface.get(field))
166
+ )
167
+ violations.extend(f"proof_surface missing required field: {field}" for field in missing_surface)
168
+ elif proof_surface is not None:
169
+ violations.append("proof_surface must be an object")
170
+
171
+ if not _looks_like_sha256_placeholder_or_hash(ledger.get("proof_surface_hash")):
172
+ violations.append("proof_surface_hash must be SHA-256 hex or NOT_COMPUTED_UNTIL_FREEZE")
173
+
174
+ for list_field in ("allowed_next_tracks", "blocked_claim_flags"):
175
+ if not isinstance(ledger.get(list_field), list) or not ledger.get(list_field):
176
+ violations.append(f"{list_field} must be a non-empty list")
177
+
178
+ context_budget = ledger.get("context_budget")
179
+ if isinstance(context_budget, dict):
180
+ max_lines = context_budget.get("max_context_lines")
181
+ if not isinstance(max_lines, int) or max_lines < 1:
182
+ violations.append("context_budget.max_context_lines must be a positive integer")
183
+ elif context_budget is not None:
184
+ violations.append("context_budget must be an object")
185
+
186
+ claim_scope = ledger.get("claim_scope")
187
+ if isinstance(claim_scope, dict):
188
+ for key in ("allowed", "forbidden"):
189
+ if not isinstance(claim_scope.get(key), list) or not claim_scope.get(key):
190
+ violations.append(f"claim_scope.{key} must be a non-empty list")
191
+ elif claim_scope is not None:
192
+ violations.append("claim_scope must be an object")
193
+
194
+ track_budget = ledger.get("track_budget")
195
+ max_proof_tracks = None
196
+ if isinstance(track_budget, dict):
197
+ max_proof_tracks = track_budget.get("max_proof_tracks_per_hypothesis")
198
+ if not isinstance(max_proof_tracks, int) or max_proof_tracks < 1:
199
+ violations.append("track_budget.max_proof_tracks_per_hypothesis must be a positive integer")
200
+ elif track_budget is not None:
201
+ violations.append("track_budget must be an object")
202
+
203
+ stop_rules = ledger.get("stop_rules")
204
+ if stop_rules is not None and (not isinstance(stop_rules, list) or not stop_rules):
205
+ violations.append("stop_rules must be a non-empty list")
206
+
207
+ claim_ids = _validate_claims(ledger.get("claim_list"), violations)
208
+ proof_counts = _validate_tracks(ledger.get("tracks"), claim_ids, violations)
209
+
210
+ if max_proof_tracks is not None:
211
+ for family, count in sorted(proof_counts.items()):
212
+ if count > max_proof_tracks:
213
+ violations.append(
214
+ f"hypothesis_family {family!r} has {count} proof tracks; "
215
+ f"budget allows {max_proof_tracks}"
216
+ )
217
+
218
+ if family_status in {"STOPPED", "CLOSED"} and _is_missing(ledger.get("closure_decision")):
219
+ violations.append("stopped or closed families must include closure_decision")
220
+
221
+ text = json.dumps(ledger, sort_keys=True).lower()
222
+ for fragment in sorted(BROAD_CLAIM_FRAGMENTS):
223
+ if fragment in text:
224
+ violations.append(f"forbidden broad claim fragment: {fragment!r}")
225
+
226
+ return violations
227
+
228
+
229
+ def validate_frontier_ledger(frontier: dict[str, Any], base_dir: Path | None = None) -> list[str]:
230
+ violations: list[str] = []
231
+
232
+ if frontier.get("protocol_version") != PROTOCOL_VERSION_V2:
233
+ violations.append(f"protocol_version must be {PROTOCOL_VERSION_V2!r}")
234
+
235
+ families = frontier.get("families")
236
+ if not isinstance(families, list):
237
+ violations.append("families must be a list")
238
+ families = []
239
+
240
+ tombstones = frontier.get("tombstones")
241
+ if not isinstance(tombstones, list):
242
+ violations.append("tombstones must be a list")
243
+ tombstones = []
244
+
245
+ tombstone_decisions = set()
246
+ for index, item in enumerate(tombstones):
247
+ prefix = f"tombstones[{index}]"
248
+ if not isinstance(item, dict):
249
+ violations.append(f"{prefix} must be an object")
250
+ continue
251
+ for field in (
252
+ "family_id",
253
+ "decision",
254
+ ):
255
+ if _is_missing(item.get(field)):
256
+ violations.append(f"{prefix} missing required field: {field}")
257
+
258
+ for list_field in (
259
+ "poisoned_proof_surface_hashes",
260
+ "blocked_future_work",
261
+ "non_overlap_requirements",
262
+ ):
263
+ if list_field not in item:
264
+ violations.append(f"{prefix} missing required field: {list_field}")
265
+ elif not isinstance(item.get(list_field), list) or not item.get(list_field):
266
+ violations.append(f"{prefix}.{list_field} must be a non-empty list")
267
+
268
+ decision = item.get("decision")
269
+ if isinstance(decision, str):
270
+ if decision in tombstone_decisions:
271
+ violations.append(f"duplicate tombstone decision: {decision}")
272
+ tombstone_decisions.add(decision)
273
+
274
+ hashes = item.get("poisoned_proof_surface_hashes")
275
+ if isinstance(hashes, list):
276
+ for proof_hash in hashes:
277
+ if not _looks_like_sha256_placeholder_or_hash(proof_hash):
278
+ violations.append(f"{prefix}.poisoned_proof_surface_hashes has invalid hash")
279
+
280
+ _validate_optional_frontier_file(item, base_dir, prefix, violations)
281
+
282
+ family_ids = set()
283
+ for index, item in enumerate(families):
284
+ prefix = f"families[{index}]"
285
+ if not isinstance(item, dict):
286
+ violations.append(f"{prefix} must be an object")
287
+ continue
288
+ for field in (
289
+ "family_id",
290
+ "family_type",
291
+ "status",
292
+ ):
293
+ if _is_missing(item.get(field)):
294
+ violations.append(f"{prefix} missing required field: {field}")
295
+
296
+ for list_field in (
297
+ "current_frontier",
298
+ "blocked_claim_flags",
299
+ "consumed_tombstones",
300
+ "proof_surface_hashes",
301
+ ):
302
+ if list_field not in item:
303
+ violations.append(f"{prefix} missing required field: {list_field}")
304
+
305
+ family_id = item.get("family_id")
306
+ if isinstance(family_id, str):
307
+ if family_id in family_ids:
308
+ violations.append(f"duplicate family_id: {family_id}")
309
+ family_ids.add(family_id)
310
+
311
+ if item.get("family_type") not in ALLOWED_FAMILY_TYPES:
312
+ violations.append(
313
+ f"{prefix}.family_type must be one of: "
314
+ + ", ".join(sorted(ALLOWED_FAMILY_TYPES))
315
+ )
316
+
317
+ if item.get("status") not in ALLOWED_FRONTIER_STATUSES:
318
+ violations.append(
319
+ f"{prefix}.status must be one of: "
320
+ + ", ".join(sorted(ALLOWED_FRONTIER_STATUSES))
321
+ )
322
+
323
+ for list_field in (
324
+ "current_frontier",
325
+ "blocked_claim_flags",
326
+ "consumed_tombstones",
327
+ "proof_surface_hashes",
328
+ ):
329
+ if not isinstance(item.get(list_field), list):
330
+ violations.append(f"{prefix}.{list_field} must be a list")
331
+
332
+ for consumed in item.get("consumed_tombstones", []):
333
+ if consumed not in tombstone_decisions:
334
+ violations.append(f"{prefix}.consumed_tombstones references unknown tombstone: {consumed!r}")
335
+
336
+ for proof_hash in item.get("proof_surface_hashes", []):
337
+ if not _looks_like_sha256_placeholder_or_hash(proof_hash):
338
+ violations.append(f"{prefix}.proof_surface_hashes has invalid hash")
339
+
340
+ _validate_optional_frontier_file(item, base_dir, prefix, violations)
341
+
342
+ text = json.dumps(frontier, sort_keys=True).lower()
343
+ for fragment in sorted(BROAD_CLAIM_FRAGMENTS):
344
+ if fragment in text:
345
+ violations.append(f"forbidden broad claim fragment: {fragment!r}")
346
+
347
+ return violations
348
+
349
+
350
+ def _validate_claims(value: object, violations: list[str]) -> set[str]:
351
+ if not isinstance(value, list) or not value:
352
+ violations.append("claim_list must be a non-empty list")
353
+ return set()
354
+
355
+ claim_ids: set[str] = set()
356
+ for index, item in enumerate(value):
357
+ prefix = f"claim_list[{index}]"
358
+ if not isinstance(item, dict):
359
+ violations.append(f"{prefix} must be an object")
360
+ continue
361
+
362
+ missing = sorted(field for field in REQUIRED_CLAIM_FIELDS if _is_missing(item.get(field)))
363
+ violations.extend(f"{prefix} missing required field: {field}" for field in missing)
364
+
365
+ claim_id = item.get("claim_id")
366
+ if isinstance(claim_id, str):
367
+ if claim_id in claim_ids:
368
+ violations.append(f"duplicate claim_id: {claim_id}")
369
+ claim_ids.add(claim_id)
370
+
371
+ if item.get("claim_class") not in ALLOWED_CLAIM_CLASSES:
372
+ violations.append(
373
+ f"{prefix}.claim_class must be one of: "
374
+ + ", ".join(sorted(ALLOWED_CLAIM_CLASSES))
375
+ )
376
+
377
+ if item.get("status") not in ALLOWED_CLAIM_STATUSES:
378
+ violations.append(
379
+ f"{prefix}.status must be one of: "
380
+ + ", ".join(sorted(ALLOWED_CLAIM_STATUSES))
381
+ )
382
+
383
+ for list_field in ("evidence_required", "forbidden_inference"):
384
+ if not isinstance(item.get(list_field), list) or not item.get(list_field):
385
+ violations.append(f"{prefix}.{list_field} must be a non-empty list")
386
+
387
+ return claim_ids
388
+
389
+
390
+ def _validate_tracks(
391
+ value: object, claim_ids: set[str], violations: list[str]
392
+ ) -> dict[str, int]:
393
+ if not isinstance(value, list) or not value:
394
+ violations.append("tracks must be a non-empty list")
395
+ return {}
396
+
397
+ track_ids: set[str] = set()
398
+ proof_counts: dict[str, int] = {}
399
+
400
+ for index, item in enumerate(value):
401
+ prefix = f"tracks[{index}]"
402
+ if not isinstance(item, dict):
403
+ violations.append(f"{prefix} must be an object")
404
+ continue
405
+
406
+ missing = sorted(field for field in REQUIRED_TRACK_FIELDS if _is_missing(item.get(field)))
407
+ violations.extend(f"{prefix} missing required field: {field}" for field in missing)
408
+
409
+ track_id = item.get("track_id")
410
+ if isinstance(track_id, str):
411
+ if track_id in track_ids:
412
+ violations.append(f"duplicate track_id: {track_id}")
413
+ track_ids.add(track_id)
414
+
415
+ mode = item.get("mode")
416
+ if mode not in ALLOWED_TRACK_MODES:
417
+ violations.append(
418
+ f"{prefix}.mode must be one of: "
419
+ + ", ".join(sorted(ALLOWED_TRACK_MODES))
420
+ )
421
+
422
+ family = item.get("hypothesis_family")
423
+ if mode == "proof" and isinstance(family, str):
424
+ proof_counts[family] = proof_counts.get(family, 0) + 1
425
+
426
+ refs = item.get("claim_ids")
427
+ if isinstance(refs, list):
428
+ for claim_id in refs:
429
+ if claim_id not in claim_ids:
430
+ violations.append(f"{prefix}.claim_ids references unknown claim_id: {claim_id!r}")
431
+ elif refs is not None:
432
+ violations.append(f"{prefix}.claim_ids must be a list")
433
+
434
+ for list_field in ("dependencies", "writes_artifacts"):
435
+ if not isinstance(item.get(list_field), list):
436
+ violations.append(f"{prefix}.{list_field} must be a list")
437
+
438
+ return proof_counts
439
+
440
+
441
+ def _validate_optional_frontier_file(
442
+ item: dict[str, Any],
443
+ base_dir: Path | None,
444
+ prefix: str,
445
+ violations: list[str],
446
+ ) -> None:
447
+ path_value = item.get("context_capsule_path") or item.get("path")
448
+ if base_dir is None or not isinstance(path_value, str) or not path_value:
449
+ return
450
+
451
+ path = base_dir / path_value
452
+ if not path.exists():
453
+ violations.append(f"{prefix} references missing file: {path_value}")
454
+ return
455
+
456
+ try:
457
+ detail = load_frontier_ledger(path)
458
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
459
+ violations.append(f"{prefix} referenced file is not valid JSON object: {path_value}: {exc}")
460
+ return
461
+
462
+ if detail.get("protocol_version") != PROTOCOL_VERSION_V2:
463
+ violations.append(f"{prefix} referenced file has wrong protocol_version: {path_value}")
464
+
465
+ if "family_id" in item and "family_id" in detail and detail["family_id"] != item["family_id"]:
466
+ violations.append(f"{prefix} referenced file has mismatched family_id: {path_value}")
467
+
468
+ if "decision" in item and "decision" in detail and detail["decision"] != item["decision"]:
469
+ violations.append(f"{prefix} referenced file has mismatched decision: {path_value}")
470
+
471
+
472
+ def _looks_like_sha256_placeholder_or_hash(value: object) -> bool:
473
+ if value == "NOT_COMPUTED_UNTIL_FREEZE":
474
+ return True
475
+ if not isinstance(value, str):
476
+ return False
477
+ if len(value) != 64:
478
+ return False
479
+ return all(char in "0123456789abcdef" for char in value.lower())
480
+
481
+
482
+ def _is_missing(value: object) -> bool:
483
+ if value is None:
484
+ return True
485
+ if isinstance(value, str) and value.strip() == "":
486
+ return True
487
+ if isinstance(value, (list, tuple, dict, set)) and len(value) == 0:
488
+ return True
489
+ return False
@@ -0,0 +1,123 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+
3
+ """Sanitization and reproducibility helpers for generic OHLCV non-spec batch JSON."""
4
+
5
+ from __future__ import annotations
6
+
7
+ from pathlib import Path
8
+
9
+ _DOMAIN_LABEL_MAX_LEN = 120
10
+ _OPERATOR_NOTES_MAX_LEN = 500
11
+ _DATASET_ID_MAX_LEN = 200
12
+ _DATASET_LICENSE_NOTE_MAX_LEN = 400
13
+
14
+
15
+ def sanitize_domain_label(value: str | None) -> str | None:
16
+ if value is None:
17
+ return None
18
+ s = " ".join(str(value).strip().split())
19
+ if not s:
20
+ return None
21
+ return s[:_DOMAIN_LABEL_MAX_LEN].rstrip()
22
+
23
+
24
+ def sanitize_operator_notes(value: str | None) -> str | None:
25
+ if value is None:
26
+ return None
27
+ s = " ".join(str(value).strip().split())
28
+ if not s:
29
+ return None
30
+ return s[:_OPERATOR_NOTES_MAX_LEN].rstrip()
31
+
32
+
33
+ def sanitize_dataset_id(value: str | None) -> str | None:
34
+ if value is None:
35
+ return None
36
+ s = " ".join(str(value).strip().split())
37
+ if not s:
38
+ return None
39
+ return s[:_DATASET_ID_MAX_LEN].rstrip()
40
+
41
+
42
+ def sanitize_dataset_license_note(value: str | None) -> str | None:
43
+ if value is None:
44
+ return None
45
+ s = " ".join(str(value).strip().split())
46
+ if not s:
47
+ return None
48
+ return s[:_DATASET_LICENSE_NOTE_MAX_LEN].rstrip()
49
+
50
+
51
+ def build_dataset_contract_v1(
52
+ dataset_id: str | None,
53
+ dataset_license_note: str | None,
54
+ ) -> dict[str, str] | None:
55
+ """Phase 2 hook: frozen dataset identity in pre_registration; does not affect scoring."""
56
+
57
+ sid = sanitize_dataset_id(dataset_id)
58
+ lic = sanitize_dataset_license_note(dataset_license_note)
59
+ if sid is None and lic is None:
60
+ return None
61
+ out: dict[str, str] = {"schema": "dataset_contract_v1"}
62
+ if sid is not None:
63
+ out["dataset_id"] = sid
64
+ if lic is not None:
65
+ out["license_note"] = lic
66
+ return out
67
+
68
+
69
+ def _find_repo_root_with_version_manifest(start: Path) -> Path | None:
70
+ for p in (start, *start.parents):
71
+ if (p / "specs" / "repo_version.yaml").is_file():
72
+ return p
73
+ return None
74
+
75
+
76
+ def _read_repo_semver_from_manifest(repo_root: Path) -> str | None:
77
+ path = repo_root / "specs" / "repo_version.yaml"
78
+ try:
79
+ text = path.read_text(encoding="utf-8")
80
+ except OSError:
81
+ return None
82
+ for line in text.splitlines():
83
+ stripped = line.strip()
84
+ if stripped.startswith("repo_semver:"):
85
+ return stripped.split(":", 1)[1].strip()
86
+ return None
87
+
88
+
89
+ def _git_head_short(repo_root: Path) -> str | None:
90
+ import subprocess
91
+
92
+ try:
93
+ proc = subprocess.run(
94
+ ["git", "rev-parse", "--short", "HEAD"],
95
+ cwd=str(repo_root),
96
+ capture_output=True,
97
+ text=True,
98
+ timeout=5,
99
+ check=False,
100
+ )
101
+ except (OSError, subprocess.TimeoutExpired):
102
+ return None
103
+ if proc.returncode != 0:
104
+ return None
105
+ out = proc.stdout.strip()
106
+ return out[:40] if out else None
107
+
108
+
109
+ def build_generic_ohlcv_batch_reproducibility() -> dict[str, object]:
110
+ """Release manifest hooks for the public release without changing scoring."""
111
+
112
+ root = _find_repo_root_with_version_manifest(Path(__file__).resolve().parent)
113
+ if root is None:
114
+ return {
115
+ "schema": "generic_ohlcv_batch_reproducibility_v1",
116
+ "repo_semver": None,
117
+ "git_commit_short": None,
118
+ }
119
+ return {
120
+ "schema": "generic_ohlcv_batch_reproducibility_v1",
121
+ "repo_semver": _read_repo_semver_from_manifest(root),
122
+ "git_commit_short": _git_head_short(root),
123
+ }
protocolith/inspect.py ADDED
@@ -0,0 +1,48 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """JSON field extraction and file hashing for cross-platform operator workflows."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import hashlib
7
+ import json
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+
12
+ def load_json(path: Path) -> dict[str, Any]:
13
+ data = json.loads(path.read_text(encoding="utf-8"))
14
+ if not isinstance(data, dict):
15
+ raise ValueError(f"{path}: expected JSON object at top level")
16
+ return data
17
+
18
+
19
+ def pick_fields(data: dict[str, Any], keys: tuple[str, ...]) -> dict[str, Any]:
20
+ missing = [key for key in keys if key not in data]
21
+ if missing:
22
+ raise KeyError(f"missing keys: {', '.join(missing)}")
23
+ return {key: data[key] for key in keys}
24
+
25
+
26
+ def format_json_subset(data: dict[str, Any]) -> str:
27
+ return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
28
+
29
+
30
+ def sha256_file(path: Path) -> str:
31
+ digest = hashlib.sha256()
32
+ with path.open("rb") as handle:
33
+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):
34
+ digest.update(chunk)
35
+ return digest.hexdigest()
36
+
37
+
38
+ def hash_files(paths: tuple[Path, ...]) -> list[tuple[str, Path]]:
39
+ lines: list[tuple[str, Path]] = []
40
+ for path in paths:
41
+ if not path.is_file():
42
+ raise FileNotFoundError(path)
43
+ lines.append((sha256_file(path), path))
44
+ return lines
45
+
46
+
47
+ def format_hash_lines(lines: list[tuple[str, Path]]) -> str:
48
+ return "".join(f"{digest} {path.as_posix()}\n" for digest, path in lines)