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,565 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Deterministic scaffold generation for Protocolith tracks."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ import re
8
+ from dataclasses import dataclass
9
+ from datetime import UTC, datetime
10
+ from pathlib import Path
11
+ from urllib.parse import urlparse
12
+
13
+
14
+ _PROTOCOL_ID_RE = re.compile(r"^[A-Z0-9][A-Z0-9_]{2,63}$")
15
+ _RAW_PROTOCOL_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_ -]{2,63}$")
16
+ _DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
17
+ _GRAY_BANNER = "STATUS: GRAY DRAFT / NOT_EVIDENCE. Prepared workspace only; no result is claimed."
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class ScaffoldRequest:
22
+ source_url: str
23
+ protocol_id: str
24
+ domain: str
25
+ track_type: str
26
+ execution_mode: str
27
+ out_dir: Path
28
+ source_name: str
29
+ audience: str
30
+ # Optional fixed date (YYYY-MM-DD) for deterministic output; defaults to today (UTC).
31
+ created_at: str | None = None
32
+
33
+
34
+ def validate_request(request: ScaffoldRequest) -> str:
35
+ """Validate scaffold inputs and return the normalized protocol id."""
36
+
37
+ parsed = urlparse(request.source_url.strip())
38
+ if parsed.scheme not in ("http", "https") or not parsed.netloc:
39
+ raise ValueError("source_url must be an http or https URL with a host")
40
+ if request.source_url != request.source_url.strip() or any(c.isspace() for c in request.source_url):
41
+ raise ValueError("source_url must not contain whitespace")
42
+ if not _RAW_PROTOCOL_ID_RE.match(request.protocol_id.strip()):
43
+ raise ValueError("protocol_id must be 3-64 characters of letters, digits, '_', '-' or space")
44
+ protocol_id = _normalize_protocol_id(request.protocol_id)
45
+ if not _PROTOCOL_ID_RE.match(protocol_id):
46
+ raise ValueError("protocol_id must normalize to [A-Z0-9_], 3-64 characters")
47
+ for name in ("domain", "track_type", "source_name", "audience"):
48
+ if not getattr(request, name).strip():
49
+ raise ValueError(f"{name} must not be empty")
50
+ if request.created_at is not None and not _DATE_RE.match(request.created_at):
51
+ raise ValueError("created_at must be YYYY-MM-DD")
52
+ return protocol_id
53
+
54
+
55
+ def plan_scaffold(request: ScaffoldRequest, repo_root: Path) -> list[Path]:
56
+ """Return the files a scaffold would create, in deterministic order. Writes nothing."""
57
+
58
+ protocol_id = validate_request(request)
59
+ slug = protocol_id.lower()
60
+ out = request.out_dir
61
+ return [
62
+ repo_root / "docs" / "protocols" / f"{protocol_id}_PREREG_CHARTER.md",
63
+ repo_root / "docs" / "evidence_requests" / f"{protocol_id}_REQUEST.md",
64
+ out / f"{protocol_id}_PLAYBOOK.md",
65
+ out / f"{protocol_id}_CHECKLIST.md",
66
+ out / f"{protocol_id}_OPERATOR_DECLARATION.md",
67
+ repo_root / "docs" / "evidence_card_drafts" / f"PLITH-{protocol_id}-DRAFT.json",
68
+ repo_root / "docs" / "registry_patch_drafts" / f"{protocol_id}_REGISTRY_PATCH.json",
69
+ repo_root / "docs" / "track_families" / f"{protocol_id}_FAMILY_LEDGER.json",
70
+ repo_root / "docs" / "track_families" / f"{protocol_id}_TREE.json",
71
+ repo_root / "artifacts" / f"{slug}_source_probe_summary.json",
72
+ ]
73
+
74
+
75
+ def _check_paths(paths: list[Path], repo_root: Path, out_dir: Path) -> None:
76
+ roots = [repo_root.resolve(), out_dir.resolve()]
77
+ for path in paths:
78
+ resolved = path.resolve()
79
+ if not any(resolved.is_relative_to(root) for root in roots):
80
+ raise ValueError(f"refusing to write outside the repository root or --out: {path}")
81
+ if path.is_symlink():
82
+ raise ValueError(f"refusing to write through a symlink: {path}")
83
+ existing = [str(p) for p in paths if p.exists()]
84
+ if existing:
85
+ raise FileExistsError("refusing to overwrite existing files: " + ", ".join(existing))
86
+
87
+
88
+ def build_scaffold(request: ScaffoldRequest, repo_root: Path, *, dry_run: bool = False) -> list[Path]:
89
+ """Create a draft request/protocol/playbook/checklist/declaration/card/patch scaffold.
90
+
91
+ The scaffold deliberately does not create a result status. A draft track is
92
+ not evidence until an operator executes it and validates a completed card.
93
+ Existing files are never overwritten and nothing is written outside
94
+ ``repo_root`` or ``request.out_dir``. With ``dry_run`` only the planned
95
+ paths are returned.
96
+ """
97
+
98
+ created_at = request.created_at or datetime.now(UTC).date().isoformat()
99
+ protocol_id = validate_request(request)
100
+ paths = plan_scaffold(request, repo_root)
101
+ if dry_run:
102
+ return paths
103
+ _check_paths(paths, repo_root, request.out_dir)
104
+
105
+ (
106
+ protocol_path,
107
+ request_path,
108
+ playbook_path,
109
+ checklist_path,
110
+ declaration_path,
111
+ draft_card_path,
112
+ patch_path,
113
+ family_ledger_path,
114
+ tree_overlay_path,
115
+ source_probe_path,
116
+ ) = paths
117
+
118
+ for path in paths:
119
+ path.parent.mkdir(parents=True, exist_ok=True)
120
+
121
+ _write_text(request_path, _render_request(request, protocol_id))
122
+ _write_text(protocol_path, _render_protocol(request, protocol_id, created_at))
123
+ _write_text(playbook_path, _render_playbook(request, protocol_id))
124
+ _write_text(checklist_path, _render_checklist(request, protocol_id))
125
+ _write_text(declaration_path, _render_operator_declaration(protocol_id))
126
+ _write_json(draft_card_path, _render_draft_card(request, protocol_id, created_at))
127
+ _write_json(patch_path, _render_registry_patch(protocol_id))
128
+ _write_json(family_ledger_path, _render_family_ledger(request, protocol_id))
129
+ _write_json(tree_overlay_path, _render_tree_overlay(request, protocol_id))
130
+ _write_json(source_probe_path, _render_source_probe(request, protocol_id, created_at))
131
+
132
+ return paths
133
+
134
+
135
+ def _render_registry_patch(protocol_id: str) -> dict[str, object]:
136
+ return {
137
+ "patch_status": "GRAY_DRAFT_NOT_EVIDENCE",
138
+ "gray_marker": _GRAY_BANNER,
139
+ "target_registry": "docs/registry/evidence_index.json",
140
+ "protocol_id": protocol_id,
141
+ "evidence_id": f"PLITH-{protocol_id}-DRAFT",
142
+ "apply_only_after": [
143
+ "protocol frozen before outcome inspection",
144
+ "completed evidence card validates",
145
+ "owner approval",
146
+ ],
147
+ "entry": "NOT_CREATED_YET",
148
+ "note": "Scaffold only. Do not merge into the registry while this file says GRAY_DRAFT_NOT_EVIDENCE.",
149
+ }
150
+
151
+
152
+ def _normalize_protocol_id(protocol_id: str) -> str:
153
+ out = protocol_id.strip().upper().replace("-", "_").replace(" ", "_")
154
+ if not out:
155
+ raise ValueError("protocol_id must not be empty")
156
+ return out
157
+
158
+
159
+ def _write_text(path: Path, text: str) -> None:
160
+ path.write_text(text.rstrip() + "\n", encoding="utf-8")
161
+
162
+
163
+ def _write_json(path: Path, data: dict[str, object]) -> None:
164
+ path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
165
+
166
+
167
+ def _render_request(request: ScaffoldRequest, protocol_id: str) -> str:
168
+ return f"""# Evidence Request: {protocol_id}
169
+
170
+ Status: request scaffold. GRAY DRAFT / NOT_EVIDENCE.
171
+
172
+ ## Public Claim
173
+
174
+ To be written narrowly by the requester before protocol freeze.
175
+
176
+ ## Claim Source URL
177
+
178
+ {request.source_url}
179
+
180
+ ## Narrow Protocolith Question
181
+
182
+ Can this claim be checked under a frozen protocol with source boundary, scoring
183
+ rule, hashes, result status, limitation and rerun path?
184
+
185
+ ## Main Audience
186
+
187
+ {request.audience}
188
+
189
+ ## Preferred Track
190
+
191
+ {request.execution_mode}
192
+
193
+ ## Proposed Sources
194
+
195
+ - {request.source_name}: {request.source_url}
196
+
197
+ ## Proposed Scoring Or Resolution Rule
198
+
199
+ Not recorded yet. Must be fixed before execution.
200
+
201
+ ## Known Reproducibility Risks
202
+
203
+ - source rights may be unclear;
204
+ - source access may change;
205
+ - prompt, payload, benchmark or transcript hashes may be unavailable;
206
+ - another operator may be unable to rerun the same environment.
207
+
208
+ ## Claims This Card Must Not Make
209
+
210
+ - no broad model superiority claim;
211
+ - no deployment-readiness claim;
212
+ - no legal certification claim;
213
+ - no correctness claim outside this protocol.
214
+ """
215
+
216
+
217
+ def _render_protocol(request: ScaffoldRequest, protocol_id: str, created_at: str) -> str:
218
+ return f"""# {protocol_id} Pre-Registration Charter
219
+
220
+ Status: draft scaffold. GRAY DRAFT / NOT_EVIDENCE. This file is not a completed evidence record.
221
+
222
+ Created: {created_at}
223
+
224
+ ## Claim Boundary
225
+
226
+ This track may check only a narrow `{request.track_type}` claim for the source
227
+ listed below. It must not claim broad model superiority, deployment readiness,
228
+ legal certification, or correctness outside this protocol.
229
+
230
+ ## Source
231
+
232
+ - Source name: {request.source_name}
233
+ - Source URL: {request.source_url}
234
+ - Domain: {request.domain}
235
+ - Audience: {request.audience}
236
+ - Execution mode: {request.execution_mode}
237
+
238
+ ## Fields To Freeze Before Execution
239
+
240
+ - exact public claim;
241
+ - claim list and claim IDs for the track family;
242
+ - optional protocol v3 tree overlay claim nodes and branch block rules;
243
+ - diagnostic, proof, reproduction or closure mode for this track;
244
+ - non-overlap boundary from previous tracks in the same family;
245
+ - official or public source boundary;
246
+ - source rights note;
247
+ - raw payload or transcript policy;
248
+ - target or question set;
249
+ - prompt set and prompt hash, when applicable;
250
+ - model or method identifier, when applicable;
251
+ - baselines and controls, when applicable;
252
+ - scoring or resolution rule;
253
+ - pass, negative, blocked and insufficient-coverage decision rules;
254
+ - stop conditions;
255
+ - forbidden after-result changes.
256
+
257
+ ## Stop Conditions
258
+
259
+ Stop and record an honest blocked or insufficient status when source access,
260
+ rights, coverage, prompt disclosure, model identity, scoring, logs or hashes are
261
+ not good enough for a fair run.
262
+
263
+ If this track belongs to a larger R&D family, stop or create a closure track
264
+ when the family budget is exhausted, repeated proof tracks fail under the same
265
+ hypothesis family, or the next proposed track only repeats the same source,
266
+ label, mechanics or gate with cosmetic changes.
267
+ """
268
+
269
+
270
+ def _render_playbook(request: ScaffoldRequest, protocol_id: str) -> str:
271
+ return f"""# {protocol_id} Playbook
272
+
273
+ Status: GRAY DRAFT / NOT_EVIDENCE.
274
+
275
+ This playbook is a scaffold. Follow it only after the protocol is reviewed and
276
+ frozen.
277
+
278
+ ## Setup
279
+
280
+ ```bash
281
+ uv sync --extra dev
282
+ uv run --extra dev python scripts/protocolith_validate_evidence_card.py --help
283
+ uv run protocolith validate-tree docs/track_families/{protocol_id}_TREE.json
284
+ ```
285
+
286
+ ## Operator Flow
287
+
288
+ 1. Open the public claim source: {request.source_url}
289
+ 2. Record the exact claim being checked.
290
+ 3. Freeze the protocol before collecting outcomes.
291
+ 4. Create a run root outside this repository.
292
+ 5. Record source rights and raw payload policy.
293
+ 6. Collect local-only raw payloads, prompts, transcripts or logs.
294
+ 7. Hash local-only artifacts.
295
+ 8. Produce a sanitized summary in `artifacts/`.
296
+ 9. Complete an evidence card JSON.
297
+ 10. Run the evidence-card validator.
298
+ 11. Validate optional family, frontier or v3 tree overlays when present.
299
+ 12. Update the registry only after validation.
300
+
301
+ ## Expected Public Outputs
302
+
303
+ ```text
304
+ docs/protocols/{protocol_id}_PREREG_CHARTER.md
305
+ docs/manual_audit/{protocol_id}_CHECKLIST.md
306
+ docs/track_families/{protocol_id}_TREE.json
307
+ docs/evidence_cards/PLITH-{protocol_id}-<DATE>.json
308
+ artifacts/{protocol_id.lower()}_summary.json
309
+ ```
310
+ """
311
+
312
+
313
+ def _render_checklist(request: ScaffoldRequest, protocol_id: str) -> str:
314
+ return f"""# {protocol_id} Checklist
315
+
316
+ Status: GRAY DRAFT / NOT_EVIDENCE.
317
+
318
+ - [ ] Public claim source opens: {request.source_url}
319
+ - [ ] Exact claim is written narrowly.
320
+ - [ ] Official or public source boundary is recorded.
321
+ - [ ] Source rights and attribution note are recorded.
322
+ - [ ] Raw payload or transcript policy is recorded.
323
+ - [ ] Protocol file is frozen before execution.
324
+ - [ ] Prompt set or source selection is frozen before execution.
325
+ - [ ] Model/method identifier is recorded when applicable.
326
+ - [ ] Scoring or resolution rule is frozen before execution.
327
+ - [ ] Stop conditions are listed.
328
+ - [ ] Family ledger exists when this is part of a multi-track R&D family.
329
+ - [ ] Optional v3 tree overlay exists for complex branch tracking.
330
+ - [ ] Claim IDs are unique and each claim has evidence required, gate and forbidden inference.
331
+ - [ ] Diagnostic and flow claims are not used as proof, deployment or production claims.
332
+ - [ ] Proof tracks are counted against the family budget.
333
+ - [ ] Local-only raw artifacts are kept outside the repository.
334
+ - [ ] Raw artifact hashes or blocked reason are recorded.
335
+ - [ ] Sanitized public summary is created.
336
+ - [ ] Evidence card uses an exact documented result status.
337
+ - [ ] Evidence card states a narrow claim boundary.
338
+ - [ ] Evidence card validates.
339
+ - [ ] Optional family, frontier and tree overlays validate.
340
+ - [ ] Registry update is made only after validation.
341
+ """
342
+
343
+
344
+ def _render_operator_declaration(protocol_id: str) -> str:
345
+ return f"""# {protocol_id} Operator Declaration
346
+
347
+ Status: GRAY DRAFT / NOT_EVIDENCE. Unsigned template; the operator must review before use.
348
+
349
+ ```text
350
+ I fixed source, selection, prompt or target, scoring rule, controls, stop
351
+ conditions and acceptance gate before outcome scoring.
352
+
353
+ I did not remove weak data after seeing outcomes.
354
+ I did not tune thresholds after seeing outcomes.
355
+ I did not rewrite a negative, blocked or limited result as a positive claim.
356
+ I did not treat diagnostic screening or flow routing as a proof or deployment claim.
357
+ I did not repeat the same failed hypothesis family after the stop rule fired.
358
+ I recorded deviations and limitations.
359
+ ```
360
+ """
361
+
362
+
363
+ def _render_draft_card(request: ScaffoldRequest, protocol_id: str, created_at: str) -> dict[str, object]:
364
+ return {
365
+ "evidence_id": f"PLITH-{protocol_id}-DRAFT",
366
+ "draft_status": "GRAY_DRAFT_NOT_EXECUTED",
367
+ "gray_marker": _GRAY_BANNER,
368
+ "evidence_status": "NOT_EVIDENCE",
369
+ "registry_sequence": 0,
370
+ "record_type": "protocol_registration",
371
+ "protocol_id": protocol_id,
372
+ "protocol_version": "DRAFT",
373
+ "domain": request.domain,
374
+ "claim_type": request.track_type,
375
+ "execution_mode": request.execution_mode,
376
+ "claim_boundary": "Draft only. No result is claimed until a real run produces validated artifacts under the frozen protocol.",
377
+ "official_source_name": request.source_name,
378
+ "official_source_url": request.source_url,
379
+ "access_date": created_at,
380
+ "source_rights_note": "NOT_RECORDED_YET",
381
+ "raw_payload_committed": False,
382
+ "raw_payload_manifest": "NOT_RECORDED_YET",
383
+ "sanitized_report_path": "NOT_CREATED_YET",
384
+ "sanitized_report_sha256": "NOT_CREATED_YET",
385
+ "git_commit": "NOT_RECORDED_YET",
386
+ "runner_command": "NOT_EXECUTED_YET",
387
+ "operator": "NOT_RECORDED_YET",
388
+ "created_at": created_at,
389
+ "last_verified_date": "NOT_VERIFIED_YET",
390
+ "verification_count": 0,
391
+ "verification_level": "NOT_EXECUTED",
392
+ "reproduction_level": "not executed",
393
+ "ai_assistance": "not used for outcome selection or gate changes",
394
+ "manual_review": "required before execution",
395
+ "known_limitations": [
396
+ "This is a scaffold, not evidence.",
397
+ "No result status has been assigned.",
398
+ "No broad claim is supported.",
399
+ ],
400
+ }
401
+
402
+
403
+ def _render_family_ledger(request: ScaffoldRequest, protocol_id: str) -> dict[str, object]:
404
+ return {
405
+ "family_id": f"{protocol_id}_FAMILY",
406
+ "protocol_version": "protocolith-rnd-family-v2",
407
+ "family_status": "DRAFT",
408
+ "family_type": _family_type_for_track(request.track_type),
409
+ "parent_claim": "Write the narrow parent hypothesis before protocol freeze.",
410
+ "non_overlap_boundary": "Describe what makes this family new relative to previous tracks. Do not reuse a failed source, label, mechanics or gate as a new proof.",
411
+ "proof_surface": {
412
+ "source_surface": request.source_url,
413
+ "selection_surface": "NOT_FROZEN_YET",
414
+ "label_or_target_surface": "NOT_FROZEN_YET",
415
+ "candidate_or_method_surface": "NOT_FROZEN_YET",
416
+ "decision_rule": "NOT_FROZEN_YET",
417
+ "target_metric": "NOT_FROZEN_YET",
418
+ "acceptance_gates": ["NOT_FROZEN_YET"],
419
+ },
420
+ "proof_surface_hash": "NOT_COMPUTED_UNTIL_FREEZE",
421
+ "allowed_next_tracks": ["source_audit", "diagnostic", "proof_after_freeze", "closure"],
422
+ "blocked_claim_flags": ["broad_model_superiority", "deployment_readiness", "correctness_outside_protocol"],
423
+ "context_budget": {"max_context_lines": 80, "capsule_required": True, "capsule_note": "Future related tracks should read this ledger before full reports."},
424
+ "claim_scope": {
425
+ "allowed": [f"Draft family planning for {request.track_type} evidence under {protocol_id}.", "Diagnostic claims may identify candidates only."],
426
+ "forbidden": ["No broad model superiority claim.", "No deployment-readiness claim.", "No correctness claim outside the protocol boundary."],
427
+ },
428
+ "track_budget": {"max_proof_tracks_per_hypothesis": 3, "budget_note": "After the budget is exhausted, add a closure decision or register a genuinely non-overlapping hypothesis family."},
429
+ "stop_rules": [
430
+ "Stop when source access, rights, hashes or scoring evidence are insufficient.",
431
+ "Stop repeated proof attempts after the family budget is exhausted.",
432
+ "Stop when the next track only changes cosmetic parameters after a negative result.",
433
+ ],
434
+ "claim_list": [
435
+ {
436
+ "claim_id": f"{protocol_id}-C001",
437
+ "claim_class": "source",
438
+ "status": "DRAFT",
439
+ "claim_text": "Official or public source boundary is identified and usable.",
440
+ "evidence_required": ["source name", "source URL", "access date", "rights or attribution note"],
441
+ "acceptance_gate": "Source boundary is recorded before outcome scoring.",
442
+ "forbidden_inference": ["source availability alone does not prove the empirical claim"],
443
+ "depends_on": [],
444
+ "unlocks": [f"{protocol_id}-C002"],
445
+ },
446
+ {
447
+ "claim_id": f"{protocol_id}-C002",
448
+ "claim_class": "diagnostic",
449
+ "status": "DRAFT",
450
+ "claim_text": "Diagnostic screening may identify candidate signals or source gaps.",
451
+ "evidence_required": ["frozen diagnostic labels or checks", "sanitized diagnostic summary", "explicit no-proof boundary"],
452
+ "acceptance_gate": "Candidate or blocker is recorded without a positive result claim.",
453
+ "forbidden_inference": ["diagnostic output is not a proof claim", "diagnostic output is not a deployment claim"],
454
+ "depends_on": [f"{protocol_id}-C001"],
455
+ "unlocks": [f"{protocol_id}-C003"],
456
+ },
457
+ {
458
+ "claim_id": f"{protocol_id}-C003",
459
+ "claim_class": "predictive",
460
+ "status": "DRAFT",
461
+ "claim_text": "A frozen proof track may test one pre-registered candidate.",
462
+ "evidence_required": ["frozen candidate", "frozen labels or target", "baselines and controls", "acceptance gate", "sanitized result summary"],
463
+ "acceptance_gate": "The candidate passes only if the frozen gate passes.",
464
+ "forbidden_inference": ["one passed proof does not support a broader family claim", "negative or blocked outcomes must not be renamed as success"],
465
+ "depends_on": [f"{protocol_id}-C002"],
466
+ "unlocks": [],
467
+ },
468
+ ],
469
+ "tracks": [
470
+ {
471
+ "track_id": f"{protocol_id}-T001",
472
+ "mode": "source_audit",
473
+ "hypothesis_family": request.track_type,
474
+ "claim_ids": [f"{protocol_id}-C001"],
475
+ "dependencies": [],
476
+ "writes_artifacts": [],
477
+ }
478
+ ],
479
+ "frontier": {"current_frontier": [f"{protocol_id}-T001"], "consumed_tombstones": [], "tombstone_required_before_descendants": True},
480
+ }
481
+
482
+
483
+ def _render_tree_overlay(request: ScaffoldRequest, protocol_id: str) -> dict[str, object]:
484
+ return {
485
+ "tree_id": f"{protocol_id}_TREE",
486
+ "protocol_version": "protocolith-tree-v3",
487
+ "tree_status": "DRAFT",
488
+ "root_family_id": f"{protocol_id}_FAMILY",
489
+ "claim_nodes": [
490
+ {
491
+ "claim_id": f"{protocol_id}-C001",
492
+ "claim_kind": "iron_claim",
493
+ "status": "DRAFT",
494
+ "claim_text": "Official or public source boundary is identified before outcome scoring.",
495
+ "evidence_required": ["source name", "source URL", "access date", "rights or attribution note"],
496
+ "acceptance_gate": "Source boundary is recorded before outcome scoring.",
497
+ "forbidden_inference": ["source availability alone does not prove the empirical claim"],
498
+ "proof_surface_hash": "NOT_COMPUTED_UNTIL_FREEZE",
499
+ },
500
+ {
501
+ "claim_id": f"{protocol_id}-C002",
502
+ "claim_kind": "flow_claim",
503
+ "status": "DRAFT",
504
+ "claim_text": "Diagnostic screening may identify candidate signals or source gaps without proof status.",
505
+ "evidence_required": ["diagnostic summary", "explicit no-proof boundary"],
506
+ "acceptance_gate": "Candidate or blocker is recorded without a positive result claim.",
507
+ "forbidden_inference": ["diagnostic output is not a proof, deployment or production claim"],
508
+ },
509
+ ],
510
+ "track_nodes": [
511
+ {
512
+ "track_id": f"{protocol_id}-T001",
513
+ "mode": "source_audit",
514
+ "claim_ids": [f"{protocol_id}-C001"],
515
+ "dependencies": [],
516
+ "branch_status": "runnable",
517
+ }
518
+ ],
519
+ "tombstones": [],
520
+ "badge_counts": {"iron_claims": 1, "flow_claims": 1, "tombstones": 0},
521
+ "branch_block_rules": [
522
+ "A stopped branch must publish a tombstone before descendants can be treated as runnable.",
523
+ "A diagnostic or flow claim must not be cited as proof, deployment readiness or production readiness.",
524
+ ],
525
+ }
526
+
527
+
528
+ def _family_type_for_track(track_type: str) -> str:
529
+ normalized = track_type.lower()
530
+ if "source" in normalized:
531
+ return "source_boundary_family"
532
+ if "repro" in normalized:
533
+ return "reproduction_family"
534
+ if "safety" in normalized or "policy" in normalized:
535
+ return "safety_policy_family"
536
+ if "product" in normalized:
537
+ return "product_decision_family"
538
+ if "audit" in normalized:
539
+ return "publication_audit_family"
540
+ if "signal" in normalized or "forecast" in normalized:
541
+ return "feature_signal_family"
542
+ return "evaluation_family"
543
+
544
+
545
+ def _render_source_probe(request: ScaffoldRequest, protocol_id: str, created_at: str) -> dict[str, object]:
546
+ parsed = urlparse(request.source_url)
547
+ return {
548
+ "protocol_id": protocol_id,
549
+ "created_at": created_at,
550
+ "source_name": request.source_name,
551
+ "source_url": request.source_url,
552
+ "url_scheme": parsed.scheme,
553
+ "url_netloc": parsed.netloc,
554
+ "probe_mode": "static_scaffold_only",
555
+ "network_fetch_performed": False,
556
+ "rights_probe_status": "NOT_RECORDED_YET",
557
+ "coverage_probe_status": "NOT_RECORDED_YET",
558
+ "raw_payload_policy": "raw payloads must stay outside this repository",
559
+ "claim_boundary": "Static source probe scaffold only. This summary does not prove source access, source rights, coverage or result status.",
560
+ "unresolved_questions": [
561
+ "Does the source allow the proposed use?",
562
+ "Can required prompts, payloads, transcripts or benchmark items be hashed?",
563
+ "Can another operator rerun the track?",
564
+ ],
565
+ }