okstra 0.228.1 → 0.229.0

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.
@@ -8,8 +8,10 @@ import subprocess
8
8
  from collections.abc import Mapping, Sequence
9
9
  from dataclasses import dataclass
10
10
  from pathlib import Path
11
+ from types import MappingProxyType
11
12
  from typing import Any
12
13
 
14
+ from .qa_procedures import existing_qa_file, safe_qa_path
13
15
  from .worktree.cleanliness import nested_worktree_excludes
14
16
  from .write_policy import WritePolicy
15
17
 
@@ -23,6 +25,24 @@ def assert_compatible_batch(policies: Sequence[WritePolicy]) -> None:
23
25
  _validate_batch(tuple(policies))
24
26
 
25
27
 
28
+ @dataclass(frozen=True)
29
+ class VerificationSourceSnapshot:
30
+ root: Path
31
+ tracked_paths: frozenset[str]
32
+ generated_roots: frozenset[str]
33
+ input_paths: frozenset[str]
34
+ protected_files: Mapping[str, str]
35
+ generated_files: Mapping[str, str]
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class VerificationSourceChanges:
40
+ protected_changes: tuple[str, ...]
41
+ generated_changes: tuple[str, ...]
42
+ unclassified_paths: tuple[str, ...]
43
+ tracked_paths_changed: bool
44
+
45
+
26
46
  @dataclass(frozen=True)
27
47
  class MutationSnapshot:
28
48
  root: Path
@@ -503,6 +523,83 @@ def source_content_snapshot(root: Path, excluded: frozenset[str] = frozenset())
503
523
  return _content_snapshot(root, excluded | _non_source_paths(root))
504
524
 
505
525
 
526
+ def _verification_paths(root: Path, paths: frozenset[str]) -> frozenset[str]:
527
+ return frozenset(
528
+ safe_qa_path(root, relative).relative_to(root).as_posix()
529
+ for relative in paths
530
+ )
531
+
532
+
533
+ def is_generated_verification_path(
534
+ relative: str, generated_roots: frozenset[str], protected_roots: frozenset[str],
535
+ ) -> bool:
536
+ return (_excluded(Path(relative), generated_roots)
537
+ and not _excluded(Path(relative), protected_roots))
538
+
539
+
540
+ def capture_verification_source(
541
+ root: Path, *, generated_roots: frozenset[str], input_paths: frozenset[str],
542
+ ) -> VerificationSourceSnapshot:
543
+ root = root.resolve()
544
+ tracked = _tracked_paths(root)
545
+ if tracked is None:
546
+ raise ValueError("verification source tracked paths are unavailable")
547
+ generated = _verification_paths(root, generated_roots)
548
+ inputs = frozenset(
549
+ existing_qa_file(root, relative).relative_to(root).as_posix()
550
+ for relative in input_paths
551
+ )
552
+ nested = _nested_worktree_paths(root)
553
+ files = _content_snapshot(root, nested | {_OKSTRA_ARTIFACT_SUBTREE})
554
+ protected = frozenset(
555
+ relative for relative in tracked if not _excluded(Path(relative), nested)
556
+ ) | inputs
557
+ for relative in protected - files.keys():
558
+ path = root / relative
559
+ if path.is_file() or path.is_symlink():
560
+ if any((root / parent).is_symlink() for parent in Path(relative).parents):
561
+ raise ValueError(
562
+ f"verification source path contains a symlink ancestor: {relative}"
563
+ )
564
+ files[relative] = _path_digest(path)
565
+ generated_files = {
566
+ relative: digest for relative, digest in files.items()
567
+ if is_generated_verification_path(relative, generated, protected)
568
+ }
569
+ protected_files = {
570
+ relative: digest for relative, digest in files.items()
571
+ if relative not in generated_files
572
+ }
573
+ return VerificationSourceSnapshot(
574
+ root=root, tracked_paths=tracked, generated_roots=generated,
575
+ input_paths=inputs, protected_files=MappingProxyType(protected_files),
576
+ generated_files=MappingProxyType(generated_files),
577
+ )
578
+
579
+
580
+ def compare_verification_sources(
581
+ before: VerificationSourceSnapshot, after: VerificationSourceSnapshot,
582
+ ) -> VerificationSourceChanges:
583
+ if before.root != after.root:
584
+ raise ValueError("verification source root changed")
585
+ if (before.generated_roots != after.generated_roots
586
+ or before.input_paths != after.input_paths):
587
+ raise ValueError("verification source classification changed")
588
+ return VerificationSourceChanges(
589
+ protected_changes=tuple(sorted(_changed_keys(
590
+ before.protected_files, after.protected_files,
591
+ ))),
592
+ generated_changes=tuple(sorted(_changed_keys(
593
+ before.generated_files, after.generated_files,
594
+ ))),
595
+ unclassified_paths=tuple(sorted(
596
+ set(after.protected_files) - before.protected_files.keys()
597
+ - before.generated_files.keys()
598
+ )),
599
+ tracked_paths_changed=before.tracked_paths != after.tracked_paths,
600
+ )
601
+
602
+
506
603
  def _content_snapshot(root: Path, excluded: frozenset[str]) -> dict[str, str]:
507
604
  """감사 대상 트리의 내용 다이제스트. `excluded` 는 정책이 선언한 생성
508
605
  경로와 레포가 무시하는 경로를 합친 접두사 집합이다."""
@@ -560,8 +657,9 @@ def _path_digest(path: Path) -> str:
560
657
 
561
658
 
562
659
  def _excluded(path: Path, excluded: frozenset[str]) -> bool:
563
- relative = path.as_posix()
564
- return any(relative == item or relative.startswith(item + "/") for item in excluded)
660
+ return path.as_posix() in excluded or any(
661
+ parent.as_posix() in excluded for parent in path.parents[:-1]
662
+ )
565
663
 
566
664
 
567
665
  def _non_source_paths(root: Path) -> frozenset[str]:
@@ -161,9 +161,18 @@ def render_verification_input(
161
161
  "when reading commands and procedure bodies.\n",
162
162
  "\n## QA Commands\n\n",
163
163
  *quoted_value_lines("QA commands", inputs["qaCommands"]),
164
+ ]
165
+ rows.append("\n## QA Source Observations\n\n")
166
+ if "qaSourceObservations" in inputs:
167
+ rows.extend(quoted_value_lines(
168
+ "QA source observations", inputs["qaSourceObservations"],
169
+ ))
170
+ else:
171
+ rows.append("Source observations were not captured in this input.\n")
172
+ rows.extend([
164
173
  "\n## Procedures\n\n",
165
174
  *quoted_value_lines("Procedures", inputs["procedures"]),
166
- ]
175
+ ])
167
176
  if "approvedPlan" in inputs:
168
177
  rows.extend([
169
178
  "\n## Approved Plan\n\n",
@@ -219,9 +219,20 @@ class RunRef:
219
219
  def manifest(self) -> Path:
220
220
  return self.run_dir / "manifests" / f"run-manifest{self._suffix}.json"
221
221
 
222
+ @property
223
+ def verification_dir(self) -> Path:
224
+ return self.run_dir / "verification"
225
+
222
226
  @property
223
227
  def verification_inputs(self) -> Path:
224
- return self.run_dir / "verification" / f"inputs{self._suffix}.json"
228
+ return self.verification_dir / f"inputs{self._suffix}.json"
229
+
230
+ def verification_generation(self, generation: int) -> Path:
231
+ if (isinstance(generation, bool) or not isinstance(generation, int)
232
+ or generation < 1):
233
+ raise ValueError("verification generation must be a positive integer")
234
+ return (self.verification_dir / f"generations{self._suffix}"
235
+ / f"generation-{generation}.json")
225
236
 
226
237
  @property
227
238
  def convergence_state(self) -> Path:
@@ -28,6 +28,7 @@ from typing import Iterable, Mapping
28
28
  # diff 가 DB 를 건드릴 때 이 카테고리(또는 plan validation 의 db 스텝)를 요구한다.
29
29
  ALLOWED_CATEGORIES: tuple[str, ...] = ("lint", "format", "typecheck", "test", "db-test")
30
30
  QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
31
+ QA_SOURCE_DIGEST_PATTERN = re.compile(r"sha256:[0-9a-f]{64}")
31
32
  QA_RELATIVE_PATH_DESCRIPTION = (
32
33
  "non-blank relative POSIX path with at least one component after normalization, "
33
34
  "without traversal or backslashes"
@@ -241,6 +242,12 @@ def validate_qa_commands(qa: object) -> list[str]:
241
242
 
242
243
  def qa_metadata_errors(entry: Mapping[str, object], seen_ids: set[str]) -> list[str]:
243
244
  errors: list[str] = []
245
+ language = entry.get("language")
246
+ if "language" in entry and (
247
+ not isinstance(language, str)
248
+ or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._+#-]*", language)
249
+ ):
250
+ errors.append("language must be a non-empty language identifier")
244
251
  identifier = entry.get("id")
245
252
  if identifier is not None:
246
253
  if not isinstance(identifier, str) or not re.fullmatch(
@@ -280,7 +287,7 @@ def qa_metadata_errors(entry: Mapping[str, object], seen_ids: set[str]) -> list[
280
287
  errors.append("resourceKeys must be non-secret resource identifiers")
281
288
  digest = entry.get("sourceBaselineDigest")
282
289
  if digest is not None and (
283
- not isinstance(digest, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", digest)
290
+ not isinstance(digest, str) or not QA_SOURCE_DIGEST_PATTERN.fullmatch(digest)
284
291
  ):
285
292
  errors.append("sourceBaselineDigest must be a sha256 digest")
286
293
  return errors
@@ -5,8 +5,9 @@ import hashlib
5
5
  import json
6
6
  import os
7
7
  import tempfile
8
+ from functools import cache
8
9
  from pathlib import Path
9
- from typing import Any, Literal, Mapping, TypedDict
10
+ from typing import Any, Callable, Literal, Mapping
10
11
 
11
12
  from okstra_project import project_json_path
12
13
  from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
@@ -16,13 +17,15 @@ from .json_boundary import load_owned_object, write_owned_object_atomic
16
17
  from .qa_commands import (
17
18
  QA_RELATIVE_PATH_DESCRIPTION, qa_relative_path_valid, validate_qa_commands,
18
19
  )
20
+ from .verification_input_types import QaSourceObservation, QaSourceStatus
19
21
 
20
22
  PROCEDURE_SECTIONS = (
21
23
  "Execution", "Environment", "User actions", "Success observations", "Cleanup",
22
24
  )
25
+ QA_SOURCE_PATH_LIMIT = 1024
23
26
 
24
27
 
25
- class QaInspectionRow(TypedDict, total=False):
28
+ class QaInspectionRow(QaSourceObservation, total=False):
26
29
  category: str
27
30
  index: int
28
31
  id: str
@@ -31,11 +34,7 @@ class QaInspectionRow(TypedDict, total=False):
31
34
  procedurePath: str
32
35
  entryDigest: str
33
36
  procedureDigest: str
34
- sourceStatus: Literal[
35
- "not-declared", "not-queried", "no-baseline", "unchanged", "changed",
36
- ]
37
37
  evidenceStatus: Literal["not-queried"]
38
- error: str
39
38
 
40
39
 
41
40
  def content_digest(value: bytes) -> str:
@@ -86,13 +85,62 @@ def read_validated_procedure(path: Path) -> bytes:
86
85
  return raw
87
86
 
88
87
 
89
- def source_digest(source: Path, relatives: list[str]) -> str:
88
+ def new_qa_source_digest_reader() -> Callable[[Path], str]:
89
+ @cache
90
+ def read_digest(path: Path) -> str:
91
+ return content_digest(path.read_bytes())
92
+
93
+ return read_digest
94
+
95
+
96
+ def source_digest(
97
+ source: Path, relatives: list[str], *,
98
+ read_digest: Callable[[Path], str] | None = None,
99
+ ) -> str:
100
+ if len(relatives) > QA_SOURCE_PATH_LIMIT:
101
+ raise ValueError(
102
+ f"related sources must contain at most {QA_SOURCE_PATH_LIMIT} paths"
103
+ )
104
+ reader = read_digest if read_digest is not None else new_qa_source_digest_reader()
90
105
  return canonical_json_digest({
91
- relative: content_digest(existing_qa_file(source, relative).read_bytes())
106
+ relative: reader(existing_qa_file(source, relative))
92
107
  for relative in sorted(relatives)
93
108
  })
94
109
 
95
110
 
111
+ def qa_source_status(
112
+ entry: Mapping[str, Any], observed_digest: str | None,
113
+ ) -> QaSourceStatus:
114
+ if not entry.get("sourcePaths"):
115
+ return "not-declared"
116
+ if observed_digest is None:
117
+ return "not-queried"
118
+ baseline = entry.get("sourceBaselineDigest")
119
+ if not baseline:
120
+ return "no-baseline"
121
+ return "unchanged" if observed_digest == baseline else "changed"
122
+
123
+
124
+ def observe_qa_sources(
125
+ source: Path, entry: Mapping[str, Any], read_digest: Callable[[Path], str],
126
+ ) -> QaSourceObservation:
127
+ observation: QaSourceObservation = {
128
+ "sourceStatus": qa_source_status(entry, None),
129
+ }
130
+ if not entry.get("sourcePaths"):
131
+ return observation
132
+ try:
133
+ observed = source_digest(source, entry["sourcePaths"], read_digest=read_digest)
134
+ except (OSError, ValueError) as exc:
135
+ observation["error"] = str(exc)
136
+ else:
137
+ observation.update(
138
+ sourceStatus=qa_source_status(entry, observed),
139
+ observedSourceDigest=observed,
140
+ )
141
+ return observation
142
+
143
+
96
144
  def load_qa_config(project: Path) -> dict[str, Any]:
97
145
  config = load_owned_object(project_json_path(project), artifact="project config")
98
146
  errors = validate_qa_commands(config.get("qaCommands"))
@@ -103,29 +151,24 @@ def load_qa_config(project: Path) -> dict[str, Any]:
103
151
 
104
152
  def inspect_commands(project: Path, source: Path) -> list[QaInspectionRow]:
105
153
  config = load_qa_config(project)
154
+ read_digest = new_qa_source_digest_reader()
106
155
  rows: list[QaInspectionRow] = []
107
156
  for category, entries in (config.get("qaCommands") or {}).items():
108
157
  for index, entry in enumerate(entries):
109
158
  row: QaInspectionRow = {
110
159
  **entry, "category": category, "index": index,
111
160
  "entryDigest": canonical_json_digest(entry),
112
- "sourceStatus": (
113
- "not-queried" if entry.get("sourcePaths") else "not-declared"
114
- ),
161
+ "sourceStatus": qa_source_status(entry, None),
115
162
  "evidenceStatus": "not-queried",
116
163
  }
164
+ row.pop("observedSourceDigest", None)
117
165
  try:
118
166
  relative = entry.get("procedurePath")
119
167
  if relative:
120
168
  root = procedure_root(project, source, relative)
121
169
  raw = read_validated_procedure(existing_qa_file(root, relative))
122
170
  row["procedureDigest"] = content_digest(raw)
123
- if entry.get("sourcePaths"):
124
- observed = source_digest(source, entry["sourcePaths"])
125
- baseline = entry.get("sourceBaselineDigest")
126
- row["sourceStatus"] = "no-baseline" if not baseline else (
127
- "unchanged" if observed == baseline else "changed"
128
- )
171
+ row.update(observe_qa_sources(source, entry, read_digest))
129
172
  except (OSError, ValueError) as exc:
130
173
  row["error"] = str(exc)
131
174
  rows.append(row)
@@ -0,0 +1,163 @@
1
+ """Select and validate actual conformance inputs for an immutable generation."""
2
+ from __future__ import annotations
3
+
4
+ import re
5
+ from dataclasses import dataclass
6
+ from pathlib import Path
7
+ from typing import Any, Mapping
8
+
9
+ from .conformance import (
10
+ conformance_entry_mismatches, normalize_conformance_script,
11
+ validate_conformance_manifest,
12
+ )
13
+ from .json_boundary import load_owned_object_snapshot
14
+ from .paths import RunRef
15
+ from .qa_procedures import content_digest, existing_qa_file, safe_qa_path
16
+ from .verification_input_types import FrozenVerificationPlan
17
+
18
+ _MAX_SCRIPT_PATH_LENGTH = 4096
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class GenerationConformance:
23
+ stages: tuple[int, ...]
24
+ artifact_paths: frozenset[str]
25
+ manifest: tuple[str, str] | None
26
+
27
+
28
+ def _project_script_path(project: Path, task_root: Path, script: str) -> str:
29
+ script = normalize_conformance_script(script)
30
+ path = Path(script)
31
+ task_relative = task_root.relative_to(project)
32
+ if path.is_absolute():
33
+ if not path.is_relative_to(task_root):
34
+ raise ValueError(f"conformance script escapes task root: {script}")
35
+ path = path.relative_to(task_root)
36
+ elif path.is_relative_to(task_relative):
37
+ path = path.relative_to(task_relative)
38
+ relative = path.as_posix()
39
+ if (len(relative) > _MAX_SCRIPT_PATH_LENGTH
40
+ or not relative.startswith("qa/scripts/")):
41
+ raise ValueError(
42
+ f"conformance script must remain under task qa/scripts: {script}"
43
+ )
44
+ safe = safe_qa_path(task_root, relative)
45
+ return safe.relative_to(project).as_posix()
46
+
47
+
48
+ def _entries_by_stage(
49
+ manifest: Mapping[str, Any], declared_stages: set[int],
50
+ ) -> dict[int, dict[str, Any]]:
51
+ entries = {}
52
+ for entry in manifest["entries"]:
53
+ match = re.fullmatch(r".+-stage-([1-9][0-9]*)", entry["stageKey"])
54
+ if match is None:
55
+ raise ValueError(
56
+ "conformance stageKey must end in -stage-<positive integer>"
57
+ )
58
+ stage = int(match[1])
59
+ if stage in entries:
60
+ raise ValueError(f"conformance stage {stage} has multiple entries")
61
+ if stage not in declared_stages:
62
+ raise ValueError(f"conformance stage {stage} is undeclared")
63
+ entries[stage] = entry
64
+ return entries
65
+
66
+
67
+ def _selected_stages(
68
+ ref: RunRef, declarations: Mapping[int, dict[str, Any]],
69
+ declared_paths: Mapping[int, str], actual_paths: Mapping[int, str],
70
+ baseline_paths: Mapping[int, str], changed_paths: frozenset[str],
71
+ ) -> tuple[int, ...]:
72
+ if ref.task_type == "final-verification":
73
+ return tuple(sorted(declarations))
74
+ stage = ref.stage
75
+ if stage not in declarations or isinstance(stage, bool):
76
+ raise ValueError(f"conformance stage {stage} has no approved declaration")
77
+ selected = {stage}
78
+ for number in declarations:
79
+ if number < stage and any(
80
+ paths.get(number) in changed_paths
81
+ for paths in (declared_paths, actual_paths, baseline_paths)
82
+ ):
83
+ selected.add(number)
84
+ return tuple(sorted(selected))
85
+
86
+
87
+ def _check_selected_entry(
88
+ stage: int, declaration: Mapping[str, Any], entry: Mapping[str, Any] | None,
89
+ declared_paths: Mapping[int, str], actual_paths: Mapping[int, str],
90
+ ) -> None:
91
+ if "script" not in declaration:
92
+ return
93
+ if entry is None:
94
+ raise ValueError(f"conformance stage {stage} has no matching manifest entry")
95
+ errors = conformance_entry_mismatches(
96
+ actual_script=actual_paths[stage], declared_script=declared_paths[stage],
97
+ actual_requires=entry.get("requires"),
98
+ declared_requires=frozenset(declaration["requires"]),
99
+ )
100
+ if errors:
101
+ raise ValueError(f"conformance stage {stage} {errors[0]}")
102
+
103
+
104
+ def _read_conformance_manifest(
105
+ project: Path, relative: str, declared_stages: set[int],
106
+ ) -> tuple[dict[int, dict[str, Any]], tuple[str, str] | None]:
107
+ path = safe_qa_path(project, relative)
108
+ if not path.exists():
109
+ return {}, None
110
+ stored = load_owned_object_snapshot(
111
+ existing_qa_file(project, relative),
112
+ artifact="verification conformance manifest",
113
+ validate_cross_fields=validate_conformance_manifest,
114
+ )
115
+ return (
116
+ _entries_by_stage(stored.value, declared_stages),
117
+ (relative, content_digest(stored.raw_bytes)),
118
+ )
119
+
120
+
121
+ def capture_generation_conformance(
122
+ project: Path, ref: RunRef, plan: FrozenVerificationPlan,
123
+ changed_artifact_paths: frozenset[str], conformance_baseline: Mapping[int, str],
124
+ ) -> GenerationConformance:
125
+ declarations = {row["stage"]: row for row in plan["conformance"]}
126
+ if any(type(stage) is not int or stage not in declarations
127
+ for stage in conformance_baseline):
128
+ raise ValueError("conformance baseline has an invalid or undeclared stage")
129
+ baseline_paths = {
130
+ stage: _project_script_path(project, ref.task_root, script)
131
+ for stage, script in conformance_baseline.items()
132
+ }
133
+ declared_paths = {
134
+ stage: _project_script_path(project, ref.task_root, row["script"])
135
+ for stage, row in declarations.items() if "script" in row
136
+ }
137
+ relative_manifest = (ref.task_root / "qa/conformance-manifest.json").relative_to(
138
+ project,
139
+ ).as_posix()
140
+ entries, sealed_manifest = _read_conformance_manifest(
141
+ project, relative_manifest, set(declarations),
142
+ )
143
+ actual_paths = {
144
+ stage: _project_script_path(project, ref.task_root, row["script"])
145
+ for stage, row in entries.items()
146
+ }
147
+ stages = _selected_stages(
148
+ ref, declarations, declared_paths, actual_paths, baseline_paths,
149
+ changed_artifact_paths,
150
+ )
151
+ artifacts = {relative_manifest} if sealed_manifest is not None else set()
152
+ for stage in stages:
153
+ if (baseline_paths.get(stage) in changed_artifact_paths
154
+ and stage not in entries):
155
+ raise ValueError(f"changed conformance stage {stage} has no actual entry")
156
+ _check_selected_entry(
157
+ stage, declarations[stage], entries.get(stage),
158
+ declared_paths, actual_paths,
159
+ )
160
+ if stage in actual_paths:
161
+ existing_qa_file(project, actual_paths[stage])
162
+ artifacts.add(actual_paths[stage])
163
+ return GenerationConformance(stages, frozenset(artifacts), sealed_manifest)