opdev 0.7.0a2__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 (42) hide show
  1. opdev/__init__.py +1 -0
  2. opdev/__main__.py +3 -0
  3. opdev/checks.py +300 -0
  4. opdev/cli.py +459 -0
  5. opdev/commands.py +76 -0
  6. opdev/config.py +278 -0
  7. opdev/document_catalog.py +107 -0
  8. opdev/document_review.py +115 -0
  9. opdev/documents.py +415 -0
  10. opdev/errors.py +5 -0
  11. opdev/files.py +82 -0
  12. opdev/init.py +87 -0
  13. opdev/junit.py +99 -0
  14. opdev/output.py +141 -0
  15. opdev/process.py +145 -0
  16. opdev/providers/__init__.py +1 -0
  17. opdev/providers/gitlab.py +374 -0
  18. opdev/publication.py +209 -0
  19. opdev/reports.py +512 -0
  20. opdev/requirements.py +642 -0
  21. opdev/resources/reports/report.css +158 -0
  22. opdev/resources/reports/report.html +27 -0
  23. opdev/resources/reports/report.js +110 -0
  24. opdev/resources/skills/opdev/SKILL.md +190 -0
  25. opdev/resources/skills/opdev/references/adoption.md +144 -0
  26. opdev/resources/skills/opdev/references/design.md +141 -0
  27. opdev/resources/skills/opdev/references/development.md +294 -0
  28. opdev/resources/skills/opdev/references/engineering.md +206 -0
  29. opdev/resources/skills/opdev/references/planning.md +101 -0
  30. opdev/resources/skills/opdev/references/publication.md +34 -0
  31. opdev/resources/templates/AGENTS.md +7 -0
  32. opdev/resources/templates/CLAUDE.md +6 -0
  33. opdev/resources/templates/guidance.md +36 -0
  34. opdev/snapshot.py +484 -0
  35. opdev/tracking.py +224 -0
  36. opdev/verification.py +234 -0
  37. opdev/version.py +45 -0
  38. opdev-0.7.0a2.dist-info/METADATA +99 -0
  39. opdev-0.7.0a2.dist-info/RECORD +42 -0
  40. opdev-0.7.0a2.dist-info/WHEEL +4 -0
  41. opdev-0.7.0a2.dist-info/entry_points.txt +3 -0
  42. opdev-0.7.0a2.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,101 @@
1
+ # Plan useful increments and bounded issues
2
+
3
+ Start from the accepted product, interface and technical decisions. Resolve
4
+ consequential open decisions with the developer unless they explicitly delegated
5
+ them. Do not use roadmap approval as a substitute for technical approval.
6
+
7
+ Propose a phased path to the whole accepted outcome. Make an early milestone a
8
+ usable end-to-end MVP, followed by useful increments; avoid plans composed only
9
+ of disconnected technical layers. Every milestone needs an outcome, scope,
10
+ dependencies and a concrete completion demonstration, including later milestones.
11
+ The expected result names an observable product effect, not "implemented and tested".
12
+ The demonstration action is something a user or caller does with the product, not
13
+ the developer's activity of implementing or testing it. Even a later milestone must
14
+ show the input reaching its intended visible destination or result.
15
+ Distinguish accepted later work from optional ideas; don't silently discard or
16
+ promote either. Recommend scope cuts as choices, not decisions already made.
17
+ Later milestones can demonstrate user-visible outcomes without freezing future
18
+ commands, formats or internal APIs. Mark those implementation details as proposed
19
+ or unresolved; an accepted outcome does not approve an unspecified contract.
20
+ When saying a technical detail is approved, name its actual selected value and
21
+ where that decision was accepted. Without both, leave that detail pending. An
22
+ accepted document can explicitly defer decisions; preserve those open choices in
23
+ the proposal instead of treating document acceptance as approval of their answers.
24
+
25
+ Obtain acceptance of the roadmap, reusing genuine prior acceptance. When tracker
26
+ access and writes are authorized, materialize all accepted phases and milestones
27
+ through `opdev phase` and `opdev milestone`. Missing access or a planning-only request
28
+ blocks saving, not issue planning: refer to accepted unsaved milestones by title in
29
+ the proposal. Provider IDs are assigned when saved; do not ask for an ID that does
30
+ not exist. Use observed IDs for existing records and resolve membership before writes.
31
+ Use stable creation keys, inspect existing records, and reconcile uncertain creates
32
+ before retrying. A reset or interrupted tracker setup is not permission to create
33
+ a second roadmap. Keep tracker-native records authoritative, not a repo checklist.
34
+ Use the [tracker identity rules](development.md#tracker-identities) when naming
35
+ existing work or distinguishing proposed renames from current titles.
36
+
37
+ Before starting **each** milestone, lead an issue-planning discussion. Define bounded
38
+ issues with an observable outcome, scope/exclusions, acceptance demonstration,
39
+ relevant requirement IDs and dependencies. An issue should be a reviewable slice,
40
+ not "implement the whole MVP" with all implementation hidden inside it. Plan the
41
+ next milestone's issues in detail when it becomes current; don't freeze every future
42
+ task prematurely. Ask about unresolved design decisions before dependent issues.
43
+
44
+ Build the acceptance demonstration before finalizing an issue's scope. Use this
45
+ small worksheet **inside the issue proposal**, not a new repository document:
46
+
47
+ - **Setup:** exact inputs, empty/seeded state and how every process selects that state.
48
+ - **Action:** the literal command/API call or precise user interaction. Preserve
49
+ argument boundaries: quote multiword arguments or give a literal argument vector.
50
+ - **Observation:** a separate literal read/query/assertion or visible interaction,
51
+ with its expected value. Name the operation, arguments and any schema it uses.
52
+ - **Capability owners:** for each action and observation, name the existing contract,
53
+ this issue's concrete proposed contract, or a declared prerequisite issue's contract.
54
+ Put a proposed signature/schema in this issue's scope before using it in the example.
55
+ Existing means implemented and available now; an accepted but unimplemented
56
+ interface is supplied by this issue or a declared prerequisite, not by approval.
57
+ - **Failure witness:** what this observation shows if the feature is a no-op or loses
58
+ the promised state. A success message/exit code is not evidence of a saved effect.
59
+
60
+ For example, an issue adding `notes save TEXT` could propose `notes(body TEXT)` in
61
+ `notes.sqlite3` under the current directory. Its demonstration starts in a new empty
62
+ directory, runs `notes save "alpha beta"`, then runs a **separate Python process** there:
63
+
64
+ ```python
65
+ import sqlite3
66
+
67
+ with sqlite3.connect("notes.sqlite3") as connection:
68
+ assert connection.execute("SELECT body FROM notes").fetchall() == [("alpha beta",)]
69
+ ```
70
+
71
+ Here this issue supplies the save command and table; the selected SQLite/Python
72
+ runtime supplies the query. A no-op save yields no table/row and fails the assertion.
73
+ The later `notes list` command is unnecessary. This is an example of making a
74
+ boundary concrete, not a required technology or permission to change a chosen schema.
75
+ For a UI, specify the exact screen/element and visible value; for an API, its actual
76
+ request and returned value. "Inspect storage", "use the proposed API" or "verify it
77
+ works" leaves the observation unwritten. Replace that placeholder before presenting
78
+ an issue as ready; don't simply add a promise to define it during implementation.
79
+
80
+ Walk the worksheet against the proposed dependency order. Every operation needs its
81
+ named owner available at that boundary; a later issue cannot supply it. Dependencies
82
+ supply capabilities, not leftover data from their examples. Each demonstration
83
+ creates its own state. Keep one bounded outcome per issue, repair missing boundaries
84
+ or reslice dependencies, and keep new interfaces explicitly proposed. A remaining
85
+ consequential decision goes to the developer unless delegated; don't invent approval.
86
+ This is part of constructing the same proposal, not a separate approval stage.
87
+
88
+ Use existing authorization to materialize and execute the accepted plan; don't
89
+ re-request permission for every issue when the developer authorized the milestone.
90
+ Roadmap acceptance alone does not necessarily authorize implementation. When intent
91
+ is unclear, ask once about the scope of execution. Keep implementation plans and
92
+ progress in the configured tracker. Requirements are enduring product promises,
93
+ not copied issue text or milestones masquerading as requirements.
94
+
95
+ After issue planning and authorization, use that issue as the
96
+ [change brief](development.md#change-brief-and-checkpoint) and move to development.
97
+ The brief reuses the accepted scope and demonstrations; it is not another planning artifact.
98
+ When asked "what next?", identify the next unresolved decision or useful milestone
99
+ from the current accepted plan; do not invent a fresh plan or automatically publish.
100
+ For additions or changed direction during implementation, reconcile only affected
101
+ scope through [Changing direction](development.md#changing-direction).
@@ -0,0 +1,34 @@
1
+ # Separately authorized publication
2
+
3
+ Establish the actual requested release scope and destination. Implementation
4
+ completion, green CI, milestone acceptance and an existing publication command
5
+ do not grant authority. Reuse explicit authority already given for this release;
6
+ do not ask again for actions within that scope. Prepare reviewable work before
7
+ asking about a genuinely unresolved release decision. Do not choose a version,
8
+ tag, deploy or migrate consumers as an implied side effect.
9
+
10
+ The protected integration rule also applies to release/version commits and
11
+ publisher automation. Complete those changes through a work branch and merge/pull
12
+ request first. Inspect configured publisher behavior for direct integration-branch
13
+ updates; release approval does not authorize them or weakening branch protections.
14
+ A local-only artifact exercise does not establish a hosted merge gate.
15
+
16
+ Use the project's established build/publishing tools and native services. OpDev
17
+ does not manage user documentation or choose a release platform. Inspect
18
+ `opdev publish --plan`, verify the selected fixed prebuilt inputs and destination,
19
+ and build separately with `opdev build` where configured. Never rebuild artifacts
20
+ inside the publisher after their verification. Do not place credentials in config,
21
+ logs or committed files; use the project's authorized credential mechanism.
22
+
23
+ `opdev publish` requires valid fixed-catalog document structure and clean committed
24
+ Git source, runs fresh required checks and
25
+ publication prerequisites, requires complete active direct-test verification, and refuses changed inputs before invoking the configured
26
+ publisher. It does not authenticate consent or make external effects atomic.
27
+ Never bypass its refusal with a direct publisher merely to obtain success.
28
+
29
+ After publication, inspect the destination through its normal read-only interface.
30
+ A successful command is not independent proof of delivery. On an uncertain,
31
+ interrupted or partial outcome, reconcile the destination before any retry.
32
+ Report precisely what was published and what remains unknown. Record completion in
33
+ the tracker, not a local evidence ledger. Updating a consumer's runtime/plugin or
34
+ changing a managed pin remains within scope only when explicitly authorized.
@@ -0,0 +1,7 @@
1
+ <!-- opdev:start -->
2
+ For substantive software work in this initialized project, read `.opdev/guidance.md`
3
+ and `.opdev/project.yaml`, including after a context reset. Use the installed OpDev
4
+ skill and selected runtime; if missing, inform the developer and offer setup.
5
+ Routine pulls, status and dev servers do not activate the workflow. Do not silently
6
+ install, upgrade or replace project decisions.
7
+ <!-- opdev:end -->
@@ -0,0 +1,6 @@
1
+ <!-- opdev:start -->
2
+ @.opdev/guidance.md
3
+
4
+ Read `.opdev/project.yaml` for substantive software work. Reload the project guide
5
+ after a context reset. Routine pulls, status and dev servers need no workflow.
6
+ <!-- opdev:end -->
@@ -0,0 +1,36 @@
1
+ # This project's OpDev entry point
2
+
3
+ ## Workflow
4
+
5
+ Use the installed OpDev skill for reusable workflow procedures. After a context
6
+ reset, reload this guide and `.opdev/project.yaml`, then read only the procedure
7
+ and project decisions needed for the current task. Use focused feedback while
8
+ iterating; the selected workflow explains integration and separate publication.
9
+
10
+ Use the developer-selected Python runtime and a matching OpDev plugin. If either
11
+ is absent or incompatible, tell the developer and offer setup or repair. Do not
12
+ silently install, substitute the retired Rust tool or change project decisions.
13
+ Independent discussion can continue while tool-dependent work is blocked.
14
+
15
+ Keep project-specific instructions here. Generic procedures belong in the plugin;
16
+ upgrades do not approve or overwrite this project's decisions.
17
+
18
+ ## Project routes
19
+
20
+ The runtime owns the fixed document catalog. Project configuration owns commands,
21
+ optional technical-role selection and tracking. Read only the relevant owners:
22
+
23
+ - Product direction: [design](design.md).
24
+ - Observable behavior: [interface](interface.md).
25
+ - Languages, tools and platform: [stack](technical/stack.md).
26
+ - Architectural decisions and rationale: [architecture](technical/architecture.md).
27
+ - Coding conventions and native enforcement: [standards](technical/standards.md).
28
+ - Test strategy and integration boundaries: [verification](technical/verification.md).
29
+
30
+ Read optional technical roles only when selected in project.yaml and relevant to
31
+ the task. Requirements and their test mappings live in `.opdev/requirements.json`;
32
+ query affected records through the CLI. Work progress lives in the configured
33
+ tracker. User-facing documentation remains developer-owned.
34
+
35
+ Initialization supplies this routing entry point, not substantive accepted project
36
+ decisions. Missing or unresolved designs remain incomplete until reviewed.
opdev/snapshot.py ADDED
@@ -0,0 +1,484 @@
1
+ """Explicit, bounded run snapshots. No ledger, test execution or report uploads."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import math
7
+ import re
8
+ from collections import Counter
9
+ from dataclasses import asdict
10
+ from datetime import UTC, datetime
11
+ from pathlib import Path, PurePosixPath, PureWindowsPath
12
+ from typing import TYPE_CHECKING, Any
13
+ from uuid import uuid4
14
+
15
+ from opdev.config import PURPOSES, Command, Project
16
+ from opdev.errors import OpDevError
17
+ from opdev.files import contained_path, read_optional, read_regular, regular_path
18
+ from opdev.junit import Case
19
+ from opdev.requirements import (
20
+ STORE,
21
+ Database,
22
+ decode,
23
+ invalid_constant,
24
+ load,
25
+ object_fields,
26
+ revision,
27
+ unique_object,
28
+ )
29
+ from opdev.verification import TestResults, assess
30
+ from opdev.version import identity
31
+
32
+ if TYPE_CHECKING:
33
+ from opdev.checks import CheckReport
34
+
35
+ SCHEMA = "opdev-report/3"
36
+ PREVIOUS_SCHEMA = "opdev-report/2"
37
+ LEGACY_SCHEMA = "opdev-report/1"
38
+ MAX_BYTES = 20 * 1024 * 1024
39
+ COMMAND_STATES = {
40
+ "passed",
41
+ "failed",
42
+ "error",
43
+ "timed_out",
44
+ "interrupted",
45
+ "not_run",
46
+ "not_selected",
47
+ }
48
+ CASE_STATES = {"passed", "failed", "error", "skipped", "ambiguous"}
49
+
50
+
51
+ def destination(path: Path) -> Path:
52
+ path = path.absolute()
53
+ regular_path(path)
54
+ if any(part.casefold() in {".git", ".opdev"} for part in path.parts):
55
+ raise OpDevError(
56
+ "Reports belong outside .git and .opdev; choose an artifact/output location."
57
+ )
58
+ if path.exists() or not path.parent.is_dir():
59
+ raise OpDevError(
60
+ "Report output must be a new file in an existing directory; nothing overwritten."
61
+ )
62
+ return path
63
+
64
+
65
+ def save(path: Path, content: str) -> None:
66
+ data = content.encode("utf-8")
67
+ if len(data) > 64 * 1024 * 1024:
68
+ raise OpDevError("Report output exceeds 64 MiB; no report written.")
69
+ destination(path)
70
+ try:
71
+ with path.open("xb") as stream:
72
+ stream.write(data)
73
+ except (OSError, KeyboardInterrupt) as exc:
74
+ raise OpDevError(
75
+ "Report write did not complete; inspect the destination before retrying. "
76
+ "Any preceding checks may already have run."
77
+ ) from exc
78
+
79
+
80
+ class Capture:
81
+ def __init__(self, project: Project, path: Path):
82
+ self.path = destination(path)
83
+ self.project = project
84
+ self.database, self.raw = load(project)
85
+ self.started = datetime.now(UTC).isoformat()
86
+ self.tool = identity()
87
+ self.run_id = str(uuid4())
88
+
89
+ def finish(self, report: CheckReport) -> None:
90
+ try:
91
+ current = (
92
+ self.project.unchanged()
93
+ and read_optional(contained_path(self.project.root, STORE)) == self.raw
94
+ and report.document_inputs_unchanged
95
+ )
96
+ except (OSError, OpDevError):
97
+ current = False
98
+ if not current:
99
+ report.status, report.full_check_passed = "error", False
100
+ report.requirements = []
101
+ report.verification = assess(
102
+ self.database, {}, catalog_present=self.raw is not None, inputs_unchanged=False
103
+ )
104
+ report.detail = (
105
+ "Configuration, mappings or documents changed; snapshot cannot verify requirements."
106
+ )
107
+ # Retain authored obligations, not machine paths, source URLs or raw diagnostics.
108
+ catalog = json.loads(self.database.encode())
109
+ for req in catalog["requirements"].values():
110
+ req["sources"] = []
111
+ for test in catalog["tests"].values():
112
+ location = test["location"]
113
+ if PurePosixPath(location).is_absolute() or PureWindowsPath(location).anchor:
114
+ test["location"] = "Absolute location omitted"
115
+ ran = {item.id: item for item in report.checks}
116
+ commands = []
117
+ for name, command in self.project.commands.items():
118
+ item = ran.get(name)
119
+ results = asdict(item.test_results) if item and item.test_results else None
120
+ if results is not None:
121
+ results.pop("detail")
122
+ results.pop(
123
+ "mappings"
124
+ ) # Derive from the captured catalog, never duplicate judgments.
125
+ commands.append(
126
+ {
127
+ "id": name,
128
+ "purpose": command.purpose,
129
+ "required": name in self.project.checks,
130
+ "selected": item is not None,
131
+ "results": command.results,
132
+ "status": item.status if item else "not_selected",
133
+ "exit_code": item.exit_code if item else None,
134
+ "duration_seconds": item.duration_seconds if item else 0.0,
135
+ "test_results": results,
136
+ }
137
+ )
138
+ data = {
139
+ "schema": SCHEMA,
140
+ "run_id": self.run_id,
141
+ "tool": self.tool,
142
+ "started_at": self.started,
143
+ "finished_at": datetime.now(UTC).isoformat(),
144
+ "operation": report.operation,
145
+ "scope": report.scope,
146
+ "status": report.status,
147
+ "full_check_passed": report.full_check_passed,
148
+ "inputs_unchanged": current,
149
+ "config_sha256": self.project.digest,
150
+ "requirements_revision": revision(self.raw),
151
+ "source_binding": "not_captured",
152
+ "commands": commands,
153
+ "catalog": catalog,
154
+ "documents": {
155
+ "status": report.documents["status"] if report.documents else "not_run",
156
+ "input_sha256": report.documents["input_sha256"] if report.documents else None,
157
+ "findings": report.documents["findings"] if report.documents else [],
158
+ },
159
+ }
160
+ raw = json.dumps(data, ensure_ascii=True, indent=2) + "\n"
161
+ try:
162
+ validate(raw.encode())
163
+ save(self.path, raw)
164
+ except (OpDevError, OSError) as exc:
165
+ raise OpDevError(
166
+ "Snapshot export failed. Checks may already have run; inspect this "
167
+ f"invocation's output and destination before retrying. {exc}"
168
+ ) from exc
169
+
170
+
171
+ def validate(
172
+ raw: bytes,
173
+ ) -> tuple[dict[str, Any], Database, dict[str, tuple[str, TestResults | None]]]:
174
+ """Validate stored observations without reading the checkout or trusting derived claims."""
175
+ if len(raw) > MAX_BYTES:
176
+ raise OpDevError("Snapshot exceeds 20 MiB.")
177
+ try:
178
+ data = json.loads(
179
+ raw.decode("utf-8"), object_pairs_hook=unique_object, parse_constant=invalid_constant
180
+ )
181
+ if not isinstance(data, dict):
182
+ raise ValueError("Report snapshot must be a JSON object")
183
+ data = object_fields(
184
+ data,
185
+ {
186
+ "schema",
187
+ "run_id",
188
+ "tool",
189
+ "started_at",
190
+ "finished_at",
191
+ "operation",
192
+ "scope",
193
+ "status",
194
+ "full_check_passed",
195
+ "inputs_unchanged",
196
+ "config_sha256",
197
+ "requirements_revision",
198
+ "source_binding",
199
+ "commands",
200
+ "catalog",
201
+ *({"documents"} if data.get("schema") == SCHEMA else set()),
202
+ },
203
+ "report snapshot",
204
+ )
205
+ _validate_identity(data)
206
+ _validate_run_context(data)
207
+ _validate_documents(data)
208
+ declared = _decode_inventory(data)
209
+ database = _decode_catalog(data, declared)
210
+ outcomes = _decode_outcomes(data, database)
211
+ _validate_outcomes(data, database, outcomes)
212
+ return data, database, outcomes
213
+ except (TypeError, KeyError, ValueError, RecursionError, UnicodeError, OverflowError) as exc:
214
+ raise OpDevError(
215
+ f"Invalid report snapshot: {exc}. Capture with opdev check --report FILE."
216
+ ) from exc
217
+
218
+
219
+ def _validate_identity(data: dict[str, Any]) -> None:
220
+ if (
221
+ data["schema"] not in {SCHEMA, PREVIOUS_SCHEMA, LEGACY_SCHEMA}
222
+ or data["source_binding"] != "not_captured"
223
+ ):
224
+ raise ValueError("Unsupported snapshot format or source binding")
225
+ if not isinstance(data["run_id"], str) or not re.fullmatch(r"[a-f0-9-]{36}", data["run_id"]):
226
+ raise ValueError("Invalid run identity")
227
+ tool = object_fields(data["tool"], {"implementation", "version", "workflow_sha256"}, "tool")
228
+ if (
229
+ tool["implementation"] != "python"
230
+ or not isinstance(tool["version"], str)
231
+ or not 1 <= len(tool["version"]) <= 128
232
+ ):
233
+ raise ValueError("Invalid tool identity")
234
+ for value in (data["config_sha256"], tool["workflow_sha256"]):
235
+ if not isinstance(value, str) or not re.fullmatch(r"[a-f0-9]{64}", value):
236
+ raise ValueError("Invalid input fingerprint")
237
+ if not isinstance(data["requirements_revision"], str) or not re.fullmatch(
238
+ r"absent|[a-f0-9]{64}", data["requirements_revision"]
239
+ ):
240
+ raise ValueError("Invalid requirements revision")
241
+
242
+
243
+ def _validate_run_context(data: dict[str, Any]) -> None:
244
+ times = [datetime.fromisoformat(data[k]) for k in ("started_at", "finished_at")]
245
+ if any(t.tzinfo is None for t in times) or times[1] < times[0]:
246
+ raise ValueError("Invalid run times")
247
+ if data["operation"] not in {"check", "test"} or data["scope"] not in {
248
+ "full",
249
+ "focused",
250
+ "test",
251
+ }:
252
+ raise ValueError("Unsupported operation/scope")
253
+ if (data["operation"] == "test") != (data["scope"] == "test"):
254
+ raise ValueError("Operation/scope disagree")
255
+ if data["status"] not in (COMMAND_STATES - {"not_run", "not_selected"}) | (
256
+ {"incomplete"} if data["schema"] != LEGACY_SCHEMA else set()
257
+ ):
258
+ raise ValueError("Invalid run outcome")
259
+ if type(data["inputs_unchanged"]) is not bool or type(data["full_check_passed"]) is not bool:
260
+ raise ValueError("Invalid verification flags")
261
+
262
+
263
+ def _decode_command(item: Any, declared: dict[str, Command]) -> tuple[str, Command]:
264
+ item = object_fields(
265
+ item,
266
+ {
267
+ "id",
268
+ "purpose",
269
+ "required",
270
+ "selected",
271
+ "results",
272
+ "status",
273
+ "exit_code",
274
+ "duration_seconds",
275
+ "test_results",
276
+ },
277
+ "command",
278
+ )
279
+ key = item["id"]
280
+ if (
281
+ not isinstance(key, str)
282
+ or not re.fullmatch(r"[a-z][a-z0-9_-]{0,63}", key)
283
+ or key in declared
284
+ ):
285
+ raise ValueError("Invalid/duplicate command identity")
286
+ if item["purpose"] not in PURPOSES or item["results"] not in {None, "junit"}:
287
+ raise ValueError("Invalid command role/results")
288
+ if any(type(item[k]) is not bool for k in ("required", "selected")):
289
+ raise ValueError("Invalid command selection")
290
+ if (
291
+ item["status"] not in COMMAND_STATES
292
+ or (item["status"] == "not_selected") == item["selected"]
293
+ ):
294
+ raise ValueError("Command status/selection disagree")
295
+ if item["exit_code"] is not None and type(item["exit_code"]) is not int:
296
+ raise ValueError("Invalid exit code")
297
+ duration = item["duration_seconds"]
298
+ if type(duration) not in (int, float) or not math.isfinite(duration) or duration < 0:
299
+ raise ValueError("Invalid command duration")
300
+ if item["status"] == "passed" and item["exit_code"] != 0:
301
+ raise ValueError("Passing command needs exit zero")
302
+ if item["status"] in {"not_run", "not_selected"} and (
303
+ item["exit_code"] is not None or duration != 0
304
+ ):
305
+ raise ValueError("Unexecuted command cannot have execution observations")
306
+ return key, Command((), ".", 300, item["purpose"], item["results"])
307
+
308
+
309
+ def _decode_inventory(data: dict[str, Any]) -> dict[str, Command]:
310
+ if not isinstance(data["commands"], list) or not 1 <= len(data["commands"]) <= 10000:
311
+ raise ValueError("Invalid command inventory")
312
+ declared: dict[str, Command] = {}
313
+ for item in data["commands"]:
314
+ key, command = _decode_command(item, declared)
315
+ declared[key] = command
316
+ return declared
317
+
318
+
319
+ def _decode_catalog(data: dict[str, Any], declared: dict[str, Command]) -> Database:
320
+ # Reuse the owned mapping validator; this structural Project performs no I/O.
321
+ project = Project(Path("."), Path("."), b"", declared, (), {})
322
+ catalog_raw = json.dumps(data["catalog"]).encode()
323
+ if len(catalog_raw) > 1_048_576:
324
+ raise ValueError("Captured catalog exceeds 1 MiB")
325
+ database = decode(catalog_raw, project)
326
+ if data["requirements_revision"] == "absent" and (database.requirements or database.tests):
327
+ raise ValueError("Absent catalog revision cannot contain records")
328
+ return database
329
+
330
+
331
+ def _decode_cases(result: dict[str, Any]) -> list[Case]:
332
+ cases = []
333
+ for case in result["cases"]:
334
+ case = object_fields(case, {"classname", "name", "status"}, "case")
335
+ if (
336
+ any(not isinstance(case[k], str) or len(case[k]) > 10000 for k in ("classname", "name"))
337
+ or not case["name"].strip()
338
+ or case["status"] not in CASE_STATES
339
+ ):
340
+ raise ValueError("Invalid case identity/outcome")
341
+ cases.append(Case(**case))
342
+ return cases
343
+
344
+
345
+ def _match_case_results(
346
+ item: dict[str, Any], result: dict[str, Any], cases: list[Case], database: Database
347
+ ) -> TestResults:
348
+ parsed = TestResults(status=result["status"], sha256=result["sha256"], cases=cases)
349
+ if result["status"] in {"passed", "failed"}:
350
+ if not cases or result["sha256"] is None:
351
+ raise ValueError("Missing observed cases/fingerprint")
352
+ identities = [(c.classname, c.name) for c in cases]
353
+ counts = Counter(identities)
354
+ if any(counts[c.classname, c.name] > 1 and c.status != "ambiguous" for c in cases):
355
+ raise ValueError("Duplicate cases must be ambiguous")
356
+ parsed.match(item["id"], database)
357
+ if parsed.status != result["status"]:
358
+ raise ValueError("Case outcome contradicts captured mappings")
359
+ elif cases:
360
+ raise ValueError("Unverified results cannot contain qualifying cases")
361
+ return parsed
362
+
363
+
364
+ def _decode_test_results(item: dict[str, Any], database: Database) -> TestResults | None:
365
+ result = item["test_results"]
366
+ if result is None:
367
+ return None
368
+ result = object_fields(result, {"format", "status", "sha256", "cases"}, "test results")
369
+ if item["results"] != "junit" or not item["selected"] or result["format"] != "junit":
370
+ raise ValueError("Unexpected case results")
371
+ if result["status"] not in {"passed", "failed", "error", "not_run"}:
372
+ raise ValueError("Invalid case-result status")
373
+ if item["status"] == "not_run" and result["status"] != "not_run":
374
+ raise ValueError("Unexecuted command cannot report test execution")
375
+ if result["status"] == "not_run" and result["sha256"] is not None:
376
+ raise ValueError("Unexecuted results cannot identify an observed report")
377
+ if result["sha256"] is not None and not re.fullmatch(r"[a-f0-9]{64}", result["sha256"]):
378
+ raise ValueError("Invalid report fingerprint")
379
+ if not isinstance(result["cases"], list) or len(result["cases"]) > 100000:
380
+ raise ValueError("Invalid case inventory")
381
+ cases = _decode_cases(result)
382
+ return _match_case_results(item, result, cases, database)
383
+
384
+
385
+ def _decode_outcomes(
386
+ data: dict[str, Any], database: Database
387
+ ) -> dict[str, tuple[str, TestResults | None]]:
388
+ outcomes: dict[str, tuple[str, TestResults | None]] = {}
389
+ for item in data["commands"]:
390
+ parsed = _decode_test_results(item, database)
391
+ if item["selected"]:
392
+ if item["results"] == "junit" and parsed is None:
393
+ raise ValueError("Selected JUnit command needs explicit result state")
394
+ if item["status"] == "passed" and parsed is not None and parsed.status != "passed":
395
+ raise ValueError("Passing command has non-passing test results")
396
+ outcomes[item["id"]] = (item["status"], parsed)
397
+ return outcomes
398
+
399
+
400
+ def _validate_outcomes(
401
+ data: dict[str, Any], database: Database, outcomes: dict[str, tuple[str, TestResults | None]]
402
+ ) -> None:
403
+ if not outcomes or (
404
+ data["status"] == "passed"
405
+ and (
406
+ not data["inputs_unchanged"]
407
+ or any(status != "passed" for status, _ in outcomes.values())
408
+ )
409
+ ):
410
+ raise ValueError("Run outcome contradicts its commands/context")
411
+ if data["scope"] == "full" and any(c["required"] != c["selected"] for c in data["commands"]):
412
+ raise ValueError("Full check must select exactly the required inventory")
413
+ if data["schema"] != LEGACY_SCHEMA:
414
+ assessment = assess(
415
+ database,
416
+ outcomes,
417
+ catalog_present=data["requirements_revision"] != "absent",
418
+ inputs_unchanged=data["inputs_unchanged"],
419
+ )
420
+ if data["status"] == "incomplete" and (
421
+ data["scope"] != "full"
422
+ or not data["inputs_unchanged"]
423
+ or any(status != "passed" for status, _ in outcomes.values())
424
+ or assessment.status == "passed"
425
+ ):
426
+ raise ValueError("Incomplete outcome contradicts commands or assessment")
427
+ if data["scope"] == "full" and data["status"] == "passed" and assessment.status != "passed":
428
+ raise ValueError("Passing full check has incomplete active verification")
429
+ full = data["scope"] == "full" and data["status"] == "passed"
430
+ if data["full_check_passed"] != full:
431
+ raise ValueError("Full-check flag contradicts the run")
432
+
433
+
434
+ def read(path: Path) -> tuple[dict[str, Any], Database, dict[str, tuple[str, TestResults | None]]]:
435
+ return validate(read_regular(path, limit=MAX_BYTES))
436
+
437
+
438
+ def _validate_documents(data: dict[str, Any]) -> None:
439
+ if data["schema"] != SCHEMA:
440
+ return
441
+ docs = object_fields(data["documents"], {"status", "input_sha256", "findings"}, "documents")
442
+ if docs["status"] not in {"valid", "invalid", "changed", "not_run"}:
443
+ raise ValueError("Invalid document verdict")
444
+ digest = docs["input_sha256"]
445
+ if docs["status"] == "not_run":
446
+ if digest is not None or docs["findings"]:
447
+ raise ValueError("Uninspected documents cannot contain a result")
448
+ elif not isinstance(digest, str) or not re.fullmatch(r"[a-f0-9]{64}", digest):
449
+ raise ValueError("Inspected documents need an input fingerprint")
450
+ if not isinstance(docs["findings"], list) or len(docs["findings"]) > 10000:
451
+ raise ValueError("Invalid document findings")
452
+ for finding in docs["findings"]:
453
+ _validate_document_finding(finding)
454
+ if (docs["status"] in {"invalid", "changed"}) != bool(docs["findings"]):
455
+ raise ValueError("Document verdict contradicts its findings")
456
+ _validate_document_scope(data, docs)
457
+
458
+
459
+ def _validate_document_scope(data: dict[str, Any], docs: dict[str, Any]) -> None:
460
+ if docs["status"] == "changed" and data["inputs_unchanged"]:
461
+ raise ValueError("Changed documents cannot claim unchanged inputs")
462
+ if data["scope"] == "full" and (
463
+ docs["status"] == "not_run"
464
+ or (data["status"] in {"passed", "incomplete"} and docs["status"] != "valid")
465
+ ):
466
+ raise ValueError("Full verification requires valid inspected documents")
467
+ if data["scope"] != "full" and docs["status"] != "not_run":
468
+ raise ValueError("Focused snapshot cannot claim a full document inspection")
469
+
470
+
471
+ def _validate_document_finding(value: Any) -> None:
472
+ item = object_fields(value, {"code", "path", "line", "message", "remedy"}, "document finding")
473
+ for key in ("code", "path", "message", "remedy"):
474
+ if not isinstance(item[key], str) or not item[key] or len(item[key]) > 4096:
475
+ raise ValueError("Invalid document finding text")
476
+ if item["line"] is not None and (type(item["line"]) is not int or item["line"] < 1):
477
+ raise ValueError("Invalid document finding line")
478
+ path = item["path"]
479
+ if (
480
+ PurePosixPath(path).is_absolute()
481
+ or PureWindowsPath(path).anchor
482
+ or ".." in Path(path).parts
483
+ ):
484
+ raise ValueError("Document finding path must be project-relative")