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
protocolith/scaffold.py
ADDED
|
@@ -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
|
+
}
|