PTSIP 0.3.1__py3-none-any.whl

ptsip/build_resolution.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+import xml.etree.ElementTree as ET
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .validation.components import ComponentPartition, partition_components
+
+
+_REQUIREMENT_NAME_RE = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9_.-]*)")
+
+
+@dataclass(frozen=True)
+class ManifestEvidence:
+    component_id: str
+    classification: str
+    path: str
+    kind: str
+    direct_dependencies: tuple[str, ...]
+    complete: bool
+    issue: str | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class BuildResolutionResult:
+    status: str
+    reason: str | None
+    manifests: tuple[ManifestEvidence, ...]
+    blocking_gaps: tuple[dict[str, object], ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "status": self.status,
+            "reason": self.reason,
+            "manifests": [item.as_dict() for item in self.manifests],
+            "blocking_gaps": list(self.blocking_gaps),
+        }
+
+
+def _normalize_requirement(value: str) -> str | None:
+    match = _REQUIREMENT_NAME_RE.match(value)
+    return match.group(1) if match else None
+
+
+def _parse_pyproject(path: Path) -> tuple[tuple[str, ...], str | None]:
+    try:
+        payload = tomllib.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError) as exc:
+        return (), str(exc)
+    project = payload.get("project", {}) if isinstance(payload, dict) else {}
+    if not isinstance(project, dict):
+        return (), None
+    values: list[str] = []
+    groups: list[object] = [project.get("dependencies", [])]
+    optional = project.get("optional-dependencies", {})
+    if isinstance(optional, dict):
+        groups.extend(optional.values())
+    for group in groups:
+        if not isinstance(group, list):
+            continue
+        for item in group:
+            if isinstance(item, str):
+                name = _normalize_requirement(item)
+                if name:
+                    values.append(name)
+    return tuple(sorted(set(values))), None
+
+
+def _parse_requirements(path: Path) -> tuple[tuple[str, ...], str | None]:
+    try:
+        lines = path.read_text(encoding="utf-8-sig").splitlines()
+    except (OSError, UnicodeError) as exc:
+        return (), str(exc)
+    values: list[str] = []
+    unresolved_includes: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith(("-r", "--requirement", "-c", "--constraint")):
+            unresolved_includes.append(stripped)
+            continue
+        if stripped.startswith(("-e", "--editable")):
+            unresolved_includes.append(stripped)
+            continue
+        name = _normalize_requirement(stripped)
+        if name:
+            values.append(name)
+    issue = None
+    if unresolved_includes:
+        issue = "Nested/editable requirement declarations require additional resolution: " + ", ".join(unresolved_includes[:10])
+    return tuple(sorted(set(values))), issue
+
+
+def _parse_package_json(path: Path) -> tuple[tuple[str, ...], str | None]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        return (), str(exc)
+    if not isinstance(payload, dict):
+        return (), "package.json root is not an object"
+    values: set[str] = set()
+    for section in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
+        group = payload.get(section, {})
+        if isinstance(group, dict):
+            values.update(str(name) for name in group if isinstance(name, str))
+    return tuple(sorted(values)), None
+
+
+def _parse_csproj(path: Path) -> tuple[tuple[str, ...], str | None]:
+    try:
+        tree = ET.parse(path)
+    except (OSError, ET.ParseError) as exc:
+        return (), str(exc)
+    values: set[str] = set()
+    for element in tree.iter():
+        if element.tag.endswith("PackageReference"):
+            include = element.attrib.get("Include") or element.attrib.get("Update")
+            if include:
+                values.add(include)
+        elif element.tag.endswith("ProjectReference"):
+            include = element.attrib.get("Include")
+            if include:
+                values.add(include.replace("\\", "/"))
+    return tuple(sorted(values)), None
+
+
+def _parse_go_mod(path: Path) -> tuple[tuple[str, ...], str | None]:
+    try:
+        lines = path.read_text(encoding="utf-8-sig").splitlines()
+    except (OSError, UnicodeError) as exc:
+        return (), str(exc)
+    values: set[str] = set()
+    in_require = False
+    for line in lines:
+        stripped = line.split("//", 1)[0].strip()
+        if not stripped:
+            continue
+        if stripped == "require (":
+            in_require = True
+            continue
+        if in_require and stripped == ")":
+            in_require = False
+            continue
+        if stripped.startswith("require "):
+            fields = stripped[len("require ") :].split()
+            if fields:
+                values.add(fields[0])
+        elif in_require:
+            fields = stripped.split()
+            if fields:
+                values.add(fields[0])
+    return tuple(sorted(values)), None
+
+
+def _parse_manifest(path: Path) -> tuple[str, tuple[str, ...], str | None]:
+    name = path.name.lower()
+    suffix = path.suffix.lower()
+    if name == "pyproject.toml":
+        deps, issue = _parse_pyproject(path)
+        return "python-pyproject", deps, issue
+    if name.startswith("requirements") and suffix in {".txt", ".in"}:
+        deps, issue = _parse_requirements(path)
+        return "python-requirements", deps, issue
+    if name == "package.json":
+        deps, issue = _parse_package_json(path)
+        return "npm-package", deps, issue
+    if suffix == ".csproj":
+        deps, issue = _parse_csproj(path)
+        return "dotnet-project", deps, issue
+    if name == "go.mod":
+        deps, issue = _parse_go_mod(path)
+        return "go-module", deps, issue
+    return "unsupported", (), "Unsupported build/dependency manifest type"
+
+
+def _gap(component_id: str, message: str, evidence_id: str) -> dict[str, object]:
+    return {
+        "id": f"build-resolution:{component_id}:{evidence_id}",
+        "blocking": True,
+        "rule_ids": ["PTSIP-BLD-001", "PTSIP-EVD-003"],
+        "evidence_ids": [f"build-resolution:{component_id}:{evidence_id}"],
+        "message": message,
+    }
+
+
+def _normalize_manifest_path(raw: str) -> str:
+    normalized = raw.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    return normalized
+
+
+def evaluate_independent_build_resolution(
+    repository_root: str | Path,
+    components: list[dict[str, object]],
+    partition: ComponentPartition | None = None,
+) -> BuildResolutionResult:
+    root = Path(repository_root).resolve()
+    partition = partition or partition_components(root, components)
+    owners = {assignment.path: assignment.component_id for assignment in partition.assignments}
+    classifications = {
+        str(component.get("id")): str(component.get("classification"))
+        for component in components
+        if component.get("id") and component.get("classification")
+    }
+    conflicted_paths = {conflict.path for conflict in partition.conflicts}
+    manifests: list[ManifestEvidence] = []
+    gaps: list[dict[str, object]] = []
+    manifest_users: dict[str, list[tuple[str, str]]] = {}
+
+    relevant_components = [
+        item for item in components if str(item.get("classification")) in {"PRODUCT", "TOOLCHAIN"}
+    ]
+    if not relevant_components:
+        return BuildResolutionResult("BLOCKED", "NO_PRODUCT_OR_TOOLCHAIN_COMPONENTS", (), (_gap("<profile>", "No PRODUCT or TOOLCHAIN components are available for build-resolution evaluation.", "no-components"),))
+
+    for component in relevant_components:
+        component_id = str(component.get("id", ""))
+        classification = str(component.get("classification", ""))
+        declared = component.get("manifests", [])
+        manifest_paths = [str(item) for item in declared] if isinstance(declared, list) else []
+        if not manifest_paths:
+            gaps.append(
+                _gap(
+                    component_id,
+                    "Component does not declare a dependency/build manifest, so its direct dependency set cannot be determined independently.",
+                    "manifest-missing",
+                )
+            )
+            continue
+
+        usable = 0
+        for raw in manifest_paths:
+            normalized = _normalize_manifest_path(raw)
+            candidate = (root / normalized).resolve()
+            try:
+                inside = candidate.is_relative_to(root)
+            except (OSError, ValueError):
+                inside = False
+            if not inside or not candidate.is_file():
+                gaps.append(_gap(component_id, f"Declared manifest {raw!r} does not resolve to a repository file.", f"manifest-unresolved:{normalized}"))
+                continue
+            relative_path = candidate.relative_to(root).as_posix()
+            manifest_owner = owners.get(relative_path)
+            ownership_issue: str | None = None
+            if relative_path in conflicted_paths:
+                ownership_issue = "manifest ownership is conflicted across component selectors"
+            elif manifest_owner is None:
+                ownership_issue = "manifest is outside declared component ownership"
+            elif manifest_owner != component_id:
+                owner_plane = classifications.get(manifest_owner, "UNKNOWN")
+                ownership_issue = (
+                    f"manifest is owned by component {manifest_owner!r} ({owner_plane}), not declaring component "
+                    f"{component_id!r} ({classification})"
+                )
+            kind, dependencies, issue = _parse_manifest(candidate)
+            combined_issue = "; ".join(item for item in (ownership_issue, issue) if item) or None
+            evidence = ManifestEvidence(
+                component_id=component_id,
+                classification=classification,
+                path=relative_path,
+                kind=kind,
+                direct_dependencies=dependencies,
+                complete=combined_issue is None,
+                issue=combined_issue,
+            )
+            manifests.append(evidence)
+            manifest_users.setdefault(evidence.path, []).append((component_id, classification))
+            if combined_issue is not None:
+                gaps.append(_gap(component_id, f"Manifest {evidence.path!r} is not usable as independent build evidence: {combined_issue}", f"manifest-incomplete:{evidence.path}"))
+            else:
+                usable += 1
+        if usable == 0 and manifest_paths:
+            gaps.append(_gap(component_id, "No declared manifest produced a complete direct-dependency set.", "no-complete-manifest"))
+
+    for path, users in sorted(manifest_users.items()):
+        planes = {classification for _, classification in users}
+        if len(planes) <= 1:
+            continue
+        components_text = ", ".join(sorted(component_id for component_id, _ in users))
+        gaps.append(
+            _gap(
+                components_text.replace(", ", "+"),
+                f"The same manifest {path!r} is declared by PRODUCT and TOOLCHAIN components ({components_text}); this evidence does not prove independently determinable direct dependency sets.",
+                f"shared-cross-plane-manifest:{path}",
+            )
+        )
+
+    status = "RAN" if not gaps else "BLOCKED"
+    reason = None if not gaps else "BUILD_RESOLUTION_EVIDENCE_INCOMPLETE"
+    return BuildResolutionResult(status, reason, tuple(manifests), tuple(gaps))

ptsip/clarification/__init__.py

@@ -0,0 +1,6 @@
+"""Deterministic human clarification support for unresolved architectural intent."""
+
+from .generator import ClarificationAnalysis, analyze_clarifications
+from .i18n import SUPPORTED_LANGUAGES, resolve_language
+
+__all__ = ["ClarificationAnalysis", "SUPPORTED_LANGUAGES", "analyze_clarifications", "resolve_language"]

ptsip/clarification/generator.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from ..inspection.components import ComponentCandidate, discover_component_candidates
+from ..inspection.dependencies_030 import scan_dependency_edges
+from ..inspection.inventory import collect_inventory
+from ..repository.discover import RepositoryInfo, discover_repository
+from ..repository.snapshot import RepositorySnapshot, SnapshotComparison, capture_snapshot, compare_snapshots
+from ..validation.profile import find_profile
+from .generator_core import build_requests
+from .model import ClarificationRequest
+from .render import request_payload
+
+
+@dataclass(frozen=True)
+class ClarificationAnalysis:
+    repository: RepositoryInfo
+    before: RepositorySnapshot
+    after: RepositorySnapshot
+    comparison: SnapshotComparison
+    candidate_ids: tuple[str, ...]
+    requests: tuple[ClarificationRequest, ...]
+    profile_path: str | None
+    profile_parse_error: str | None
+
+    @property
+    def status(self) -> str:
+        if not self.comparison.stable:
+            return "INVALIDATED"
+        if self.requests:
+            return "CLARIFICATION_REQUIRED"
+        return "NO_CLARIFICATION_REQUIRED"
+
+    def as_dict(self, language: str) -> dict[str, object]:
+        return {
+            "format": "ptsip-clarification/v1",
+            "status": self.status,
+            "language": language,
+            "inference": {
+                "mode": "DETERMINISTIC_RULES_ONLY",
+                "llm_calls": 0,
+                "speculative_classification": False,
+            },
+            "repository": self.repository.as_dict(),
+            "snapshot": {
+                "before": self.before.as_dict(),
+                "after": self.after.as_dict(),
+                "comparison": self.comparison.as_dict(),
+            },
+            "profile": {
+                "path": self.profile_path,
+                "parse_error": self.profile_parse_error,
+            },
+            "component_candidate_count": len(self.candidate_ids),
+            "clarification_count": len(self.requests),
+            "requests": [request_payload(item, language) for item in self.requests],
+        }
+
+
+def _declared_components(root: Path) -> tuple[list[dict[str, object]], str | None, str | None]:
+    profile = find_profile(root)
+    if profile is None:
+        return [], None, None
+    try:
+        payload = yaml.safe_load(profile.read_text(encoding="utf-8"))
+    except Exception as exc:
+        return [], str(profile), str(exc)
+    if not isinstance(payload, dict):
+        return [], str(profile), "profile root is not a mapping"
+    raw = payload.get("components")
+    if not isinstance(raw, list):
+        return [], str(profile), None
+    components = [item for item in raw if isinstance(item, dict)]
+    return components, str(profile), None
+
+
+def analyze_clarifications(
+    path: str | Path = ".",
+    component_ids: list[str] | tuple[str, ...] | None = None,
+) -> ClarificationAnalysis:
+    repo = discover_repository(path)
+    root = Path(repo.root).resolve()
+    before = capture_snapshot(root)
+    inventory = collect_inventory(root)
+    dependencies = scan_dependency_edges(root)
+    all_candidates = discover_component_candidates(root, inventory, dependencies)
+    candidate_ids = tuple(item.id for item in all_candidates)
+
+    selected = set(component_ids or ())
+    if selected:
+        unknown = sorted(selected - set(candidate_ids))
+        if unknown:
+            raise ValueError("Unknown component candidate(s): " + ", ".join(unknown))
+        candidates: list[ComponentCandidate] = [item for item in all_candidates if item.id in selected]
+    else:
+        candidates = all_candidates
+
+    declared, profile_path, profile_error = _declared_components(root)
+    identity = (
+        repo.remote.repository
+        if repo.remote and repo.remote.provider == "github" and repo.remote.repository
+        else repo.root
+    )
+    requests = build_requests(identity, candidates, declared)
+    after = capture_snapshot(root)
+    comparison = compare_snapshots(before, after)
+    return ClarificationAnalysis(
+        repository=repo,
+        before=before,
+        after=after,
+        comparison=comparison,
+        candidate_ids=candidate_ids,
+        requests=requests,
+        profile_path=profile_path,
+        profile_parse_error=profile_error,
+    )

ptsip/clarification/generator_core.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import hashlib
+from typing import Iterable, Protocol
+
+from .model import FIELD_ORDER, REASON_BY_FIELD, ClarificationRequest
+
+
+class CandidateLike(Protocol):
+    id: str
+    include: tuple[str, ...]
+    anchors: tuple[str, ...]
+    evidence_ids: tuple[str, ...]
+
+
+def _normalize_selector(value: str) -> str:
+    text = value.replace("\\", "/").strip()
+    while text.startswith("./"):
+        text = text[2:]
+    return text.strip("/")
+
+
+def _selector_covers(declared: str, candidate: str) -> bool:
+    declared = _normalize_selector(declared)
+    candidate = _normalize_selector(candidate)
+    if declared == candidate:
+        return True
+    if declared.endswith("/**"):
+        base = declared[:-3].rstrip("/")
+        candidate_base = candidate[:-3].rstrip("/") if candidate.endswith("/**") else candidate
+        return candidate_base == base or candidate_base.startswith(base + "/")
+    return False
+
+
+def _covering_components(candidate: CandidateLike, components: list[dict[str, object]]) -> list[dict[str, object]]:
+    found: list[dict[str, object]] = []
+    for component in components:
+        selectors = [str(item) for item in component.get("include", [])]
+        if any(
+            _selector_covers(selector, candidate_selector)
+            for selector in selectors
+            for candidate_selector in candidate.include
+        ):
+            found.append(component)
+    return found
+
+
+def build_requests(
+    repository_identity: str,
+    candidates: Iterable[CandidateLike],
+    declared_components: list[dict[str, object]],
+) -> tuple[ClarificationRequest, ...]:
+    requests: list[ClarificationRequest] = []
+    for candidate in candidates:
+        covering = _covering_components(candidate, declared_components)
+        target_component_id = candidate.id
+        if len(covering) == 1:
+            declared = covering[0]
+            declared_id = str(declared.get("id", "")).strip()
+            if declared_id:
+                target_component_id = declared_id
+            missing_required = tuple(
+                field
+                for field in ("classification", "purpose")
+                if not str(declared.get(field, "")).strip()
+            )
+            if not missing_required:
+                continue
+            missing_fields = missing_required
+        else:
+            missing_fields = FIELD_ORDER
+        reasons = tuple(REASON_BY_FIELD[field] for field in missing_fields)
+        selector_identity = ",".join(sorted(_normalize_selector(item) for item in candidate.include))
+        digest = hashlib.sha256(
+            (
+                repository_identity
+                + "\0"
+                + candidate.id
+                + "\0"
+                + target_component_id
+                + "\0"
+                + selector_identity
+                + "\0"
+                + ",".join(missing_fields)
+            ).encode("utf-8")
+        ).hexdigest()[:16]
+        requests.append(
+            ClarificationRequest(
+                id=f"clr-{digest}",
+                component_id=target_component_id,
+                include=tuple(candidate.include),
+                anchors=tuple(candidate.anchors),
+                evidence_ids=tuple(candidate.evidence_ids),
+                missing_fields=tuple(missing_fields),
+                reason_codes=reasons,
+            )
+        )
+    return tuple(requests)

ptsip/clarification/i18n.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import locale
+import os
+
+SUPPORTED_LANGUAGES = ("en", "ko")
+
+_TEXT = {
+    "en": {
+        "title": "[PTSIP clarification] Architecture decision for {component_id}",
+        "intro": "PTSIP stopped before speculative classification because the repository does not declare enough architectural intent for this component.",
+        "no_llm": "This clarification request is generated from fixed rules and templates. PTSIP does not call an LLM to create it.",
+        "classification": "Which PTSIP architectural classification does this component belong to?",
+        "purpose": "What is the primary purpose for which this component was created?",
+        "shipped": "Is this component distributed or shipped with the product?",
+        "runtime_required": "Is this component required by the product at runtime?",
+        "lifecycle_owner": "Which lifecycle owns versioning and releases for this component?",
+        "executable": "Does this component contain executable implementation rather than only a declarative contract?",
+        "reply": "Please reply using the following structured fields. Keep the invariant codes unchanged where applicable.",
+        "required": "Clarification required",
+        "none": "No clarification is required from the currently detected component candidates.",
+    },
+    "ko": {
+        "title": "[PTSIP 확인 요청] {component_id} 아키텍처 결정",
+        "intro": "PTSIP는 이 컴포넌트의 아키텍처 목적을 선언된 저장소 정보만으로 확인할 수 없어 추측성 분류를 중단했습니다.",
+        "no_llm": "이 확인 요청은 고정된 규칙과 템플릿으로 생성됩니다. PTSIP는 질문을 만들기 위해 LLM을 호출하지 않습니다.",
+        "classification": "이 컴포넌트의 PTSIP 아키텍처 분류는 무엇입니까?",
+        "purpose": "이 컴포넌트를 만든 주된 목적은 무엇입니까?",
+        "shipped": "이 컴포넌트는 제품과 함께 배포되거나 제품 패키지에 포함됩니까?",
+        "runtime_required": "제품 런타임에서 이 컴포넌트가 필요합니까?",
+        "lifecycle_owner": "이 컴포넌트의 버전 관리와 릴리스 생명주기는 누가 소유합니까?",
+        "executable": "이 컴포넌트는 선언형 계약만이 아니라 실행 가능한 구현을 포함합니까?",
+        "reply": "다음 구조화된 필드로 답변해 주세요. 해당되는 경우 영문 고정 코드는 변경하지 않는 것이 좋습니다.",
+        "required": "확인 필요",
+        "none": "현재 탐지된 컴포넌트 후보에는 추가 확인이 필요하지 않습니다.",
+    },
+}
+
+_OPTIONS = {
+    "classification": (
+        ("PRODUCT", {"en": "Product-owned component", "ko": "Product 소유 컴포넌트"}),
+        ("TOOLCHAIN", {"en": "Development Toolchain component", "ko": "개발 Toolchain 컴포넌트"}),
+        ("NEUTRAL_CONTRACT", {"en": "Neutral non-executable contract", "ko": "중립 비실행 계약"}),
+    ),
+    "shipped": (
+        ("YES", {"en": "Yes", "ko": "예"}),
+        ("NO", {"en": "No", "ko": "아니요"}),
+    ),
+    "runtime_required": (
+        ("YES", {"en": "Yes", "ko": "예"}),
+        ("NO", {"en": "No", "ko": "아니요"}),
+    ),
+    "lifecycle_owner": (
+        ("PRODUCT", {"en": "Product lifecycle", "ko": "Product 생명주기"}),
+        ("DEVELOPMENT_TOOLING", {"en": "Development tooling lifecycle", "ko": "개발 Tooling 생명주기"}),
+        ("INDEPENDENT", {"en": "Independently governed", "ko": "독립적으로 관리"}),
+    ),
+    "executable": (
+        ("YES", {"en": "Executable implementation is present", "ko": "실행 가능한 구현이 있음"}),
+        ("NO", {"en": "Declarative/non-executable only", "ko": "선언형/비실행 계약만 있음"}),
+    ),
+}
+
+
+def _normalize(value: str | None) -> str | None:
+    if not value:
+        return None
+    lowered = value.strip().replace("_", "-").casefold()
+    if lowered == "ko" or lowered.startswith("ko-"):
+        return "ko"
+    if lowered == "en" or lowered.startswith("en-"):
+        return "en"
+    return None
+
+
+def resolve_language(explicit: str | None = None) -> str:
+    if explicit is not None:
+        normalized = _normalize(explicit)
+        if normalized is None:
+            raise ValueError("Supported languages are: en, ko")
+        return normalized
+    configured = _normalize(os.environ.get("PTSIP_LANG"))
+    if configured:
+        return configured
+    try:
+        system_locale = locale.getlocale()[0]
+    except (ValueError, TypeError):
+        system_locale = None
+    return _normalize(system_locale) or "en"
+
+
+def text(language: str, key: str, **values: str) -> str:
+    return _TEXT[language][key].format(**values)
+
+
+def question(field: str, language: str) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "field": field,
+        "type": "free_text" if field == "purpose" else "single_select",
+        "prompt": text(language, field),
+    }
+    if field in _OPTIONS:
+        payload["options"] = [
+            {"value": code, "label": labels[language]} for code, labels in _OPTIONS[field]
+        ]
+    return payload

ptsip/clarification/model.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+from ..model import DecisionStatus
+
+
+FIELD_ORDER = ("classification", "purpose", "shipped", "runtime_required", "lifecycle_owner", "executable")
+REASON_BY_FIELD = {
+    "classification": "MISSING_CLASSIFICATION",
+    "purpose": "MISSING_PURPOSE",
+    "shipped": "MISSING_PACKAGING_RESPONSIBILITY",
+    "runtime_required": "MISSING_RUNTIME_ROLE",
+    "lifecycle_owner": "MISSING_LIFECYCLE_OWNER",
+    "executable": "MISSING_EXECUTABLE_ROLE",
+}
+
+
+@dataclass(frozen=True)
+class ClarificationRequest:
+    id: str
+    component_id: str
+    include: tuple[str, ...]
+    anchors: tuple[str, ...]
+    evidence_ids: tuple[str, ...]
+    missing_fields: tuple[str, ...]
+    reason_codes: tuple[str, ...]
+    status: DecisionStatus = DecisionStatus.INCOMPLETE
+
+    def as_dict(self) -> dict[str, object]:
+        payload = asdict(self)
+        payload["status"] = self.status.value
+        return payload