okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/report_narrative.py

@@ -0,0 +1,351 @@
+"""보고서 작성자 전담 Markdown 서사의 손실 없는 읽기·쓰기 계약."""
+from __future__ import annotations
+
+import json
+import re
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Mapping
+
+from .final_report_schema import validate
+from .report_markdown import SchemaIndex, humanise, label_key
+from .json_boundary import load_owned_object
+
+
+TITLE = "# OKSTRA Report Narrative"
+EMPTY_MARKER = "_none_"
+_FIELD_RE = re.compile(r"^(?P<indent> *)- \*\*(?P<label>.+)\*\*$")
+_ITEM_RE = re.compile(r"^(?P<indent> *)- Item (?P<position>[1-9]\d*)$")
+_VALUE_RE = re.compile(r"^(?P<indent> *)> ?(?P<value>.*)$")
+_NESTED_FORBIDDEN = frozenset(
+    {
+        "implementationPlanning.designPreparation",
+        "implementationPlanning.planBodyVerification",
+    }
+)
+
+
+class NarrativeContractError(ValueError):
+    """서사 입력이 보고서 작성자 소유권이나 Markdown 문법을 위반했다."""
+
+
+class _Node:
+    def __init__(self, kind: str, label: str, level: int) -> None:
+        self.kind = kind
+        self.label = label
+        self.level = level
+        self.values: list[str] = []
+        self.children: list[_Node] = []
+
+
+def _narrative_schema_path() -> Path:
+    return Path(__file__).resolve().parents[2] / "schemas" / "report-narrative-v3.0.schema.json"
+
+
+def _narrative_schema() -> dict[str, Any]:
+    return load_owned_object(_narrative_schema_path(), artifact="report narrative schema")
+
+
+def _allowed_top_level() -> frozenset[str]:
+    return frozenset(_narrative_schema().get("properties", {}))
+
+
+def writer_owned_data(data: Mapping[str, Any]) -> dict[str, Any]:
+    """완성 리포트에서 보고서 작성자 소유 필드만 복사한다."""
+    owned = {
+        key: deepcopy(value)
+        for key, value in data.items()
+        if key in _allowed_top_level()
+    }
+    planning = owned.get("implementationPlanning")
+    if isinstance(planning, dict):
+        planning.pop("designPreparation", None)
+        planning.pop("planBodyVerification", None)
+        for stage in planning.get("stages", ()):
+            if isinstance(stage, dict):
+                stage.pop("designSurfaceCoverage", None)
+    return owned
+
+
+def _schema_branches(node: Any, index: SchemaIndex) -> list[dict[str, Any]]:
+    resolved = index.resolve(node)
+    branches = [resolved]
+    for keyword in ("allOf", "oneOf", "anyOf"):
+        branches.extend(index.resolve(branch) for branch in resolved.get(keyword, ()))
+    return branches
+
+
+def _node_types(node: Any, index: SchemaIndex) -> set[str]:
+    result: set[str] = set()
+    for branch in _schema_branches(node, index):
+        value = branch.get("type")
+        if isinstance(value, str):
+            result.add(value)
+        elif isinstance(value, list):
+            result.update(item for item in value if isinstance(item, str))
+        if "properties" in branch:
+            result.add("object")
+        if "items" in branch:
+            result.add("array")
+        constant = branch.get("const")
+        if isinstance(constant, bool):
+            result.add("boolean")
+        elif isinstance(constant, int):
+            result.add("integer")
+        elif isinstance(constant, float):
+            result.add("number")
+        elif isinstance(constant, str):
+            result.add("string")
+        for item in branch.get("enum", ()):
+            if isinstance(item, bool):
+                result.add("boolean")
+            elif isinstance(item, int):
+                result.add("integer")
+            elif isinstance(item, float):
+                result.add("number")
+            elif isinstance(item, str):
+                result.add("string")
+    return result
+
+
+def _scalar_lines(value: Any) -> list[str]:
+    if value is None:
+        return [EMPTY_MARKER]
+    if isinstance(value, bool):
+        return [str(value).lower()]
+    if isinstance(value, (int, float)):
+        return [str(value)]
+    return str(value).split("\n")
+
+
+def _render_value(
+    value: Any, node: Any, index: SchemaIndex, level: int,
+) -> list[str]:
+    prefix = "  " * level
+    if isinstance(value, Mapping):
+        if not value:
+            return [f"{prefix}> {EMPTY_MARKER}"]
+        return _render_fields(value, node, index, level)
+    if isinstance(value, list):
+        if not value:
+            return [f"{prefix}> {EMPTY_MARKER}"]
+        lines: list[str] = []
+        for position, item in enumerate(value, start=1):
+            lines.append(f"{prefix}- Item {position}")
+            lines.extend(_render_value(item, index.item(node), index, level + 1))
+        return lines
+    return [f"{prefix}> {line}" for line in _scalar_lines(value)]
+
+
+def _render_fields(
+    value: Mapping[str, Any], node: Any, index: SchemaIndex, level: int,
+) -> list[str]:
+    order = index.key_order(node)
+    keys = [key for key in order if key in value]
+    keys.extend(key for key in value if key not in keys)
+    lines: list[str] = []
+    prefix = "  " * level
+    for key in keys:
+        lines.append(f"{prefix}- **{humanise(key)}**")
+        lines.extend(_render_value(value[key], index.child(node, key), index, level + 1))
+    return lines
+
+
+def render_narrative(data: Mapping[str, Any], schema: Mapping[str, Any]) -> str:
+    """작성자 소유 자료를 계층형 Markdown 목록으로 렌더한다."""
+    unknown = sorted(set(data) - _allowed_top_level())
+    if unknown:
+        raise NarrativeContractError(
+            f"owner=report-writer cannot author fields: {unknown}"
+        )
+    index = SchemaIndex(schema)
+    lines = [TITLE, ""]
+    lines.extend(_render_fields(data, schema, index, 0))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _line_level(indent: str, line_number: int) -> int:
+    if len(indent) % 2:
+        raise NarrativeContractError(
+            f"line {line_number}: indentation must use pairs of spaces"
+        )
+    return len(indent) // 2
+
+
+def _parse_tree(markdown: str) -> _Node:
+    lines = markdown.splitlines()
+    if not lines or lines[0].strip() != TITLE:
+        raise NarrativeContractError(f"narrative must start with `{TITLE}`")
+    root = _Node("root", "", -1)
+    stack = [root]
+    for number, line in enumerate(lines[1:], start=2):
+        if not line.strip():
+            continue
+        field = _FIELD_RE.match(line)
+        item = _ITEM_RE.match(line)
+        value = _VALUE_RE.match(line)
+        if field or item:
+            match = field or item
+            level = _line_level(match.group("indent"), number)
+            _append_node(stack, field, item, level, number)
+        elif value:
+            level = _line_level(value.group("indent"), number)
+            _append_value(stack, value.group("value"), level, number)
+        else:
+            raise NarrativeContractError(
+                f"line {number}: unsupported Markdown syntax `{line.strip()}` — "
+                "a narrative line is only `- **Field Name**`, `- Item <N>`, or "
+                "`> value`. Headings, tables at column 0, code fences, bare "
+                "paragraphs, JSON and YAML are rejected; put such text inside a "
+                "`> ` value line instead"
+            )
+    return root
+
+
+def _append_node(stack: list[_Node], field: Any, item: Any, level: int, number: int) -> None:
+    while stack[-1].level >= level:
+        stack.pop()
+    if stack[-1].level != level - 1:
+        raise NarrativeContractError(f"line {number}: skipped a nesting level")
+    node = _Node(
+        "field" if field else "item",
+        field.group("label") if field else item.group("position"),
+        level,
+    )
+    stack[-1].children.append(node)
+    stack.append(node)
+
+
+def _append_value(stack: list[_Node], value: str, level: int, number: int) -> None:
+    if stack[-1].level != level - 1:
+        raise NarrativeContractError(f"line {number}: value is outside its field")
+    if stack[-1].children:
+        raise NarrativeContractError(f"line {number}: field mixes values and children")
+    stack[-1].values.append(value)
+
+
+def _allowed_labels(node: Any, index: SchemaIndex, path: str) -> list[str]:
+    """이 위치에서 저작자가 쓸 수 있는 사람이 읽는 필드 표기."""
+    keys = index.key_order(node)
+    if not path:
+        keys = [key for key in keys if key in _allowed_top_level()]
+    # 파서가 뒤에서 거부할 필드를 여기서 권하면 안내가 다음 거부를 만든다.
+    keys = [key for key in keys if f"{path}.{key}".lstrip(".") not in _NESTED_FORBIDDEN]
+    return sorted(humanise(key) for key in keys)
+
+
+def _field_key(label: str, node: Any, index: SchemaIndex, path: str) -> str:
+    candidates: dict[str, list[str]] = {}
+    for key in index.key_order(node):
+        candidates.setdefault(label_key(humanise(key)), []).append(key)
+    matches = candidates.get(label_key(label), [])
+    if not matches:
+        matches = index.keys_for_label(label)
+    display_path = f"{path}.{label}" if path else label
+    # 거부만 알리면 다음 시도도 추측이 된다. 이 위치에서 허용되는 표기를
+    # 함께 실어, 재작성이 목록 대조로 끝나게 한다.
+    if not matches:
+        allowed = _allowed_labels(node, index, path)
+        listing = ", ".join(f"`{item}`" for item in allowed) or "(none)"
+        raise NarrativeContractError(
+            f"owner=report-writer field `{display_path}` is not an allowed unique "
+            f"field; allowed at this position: {listing}"
+        )
+    if len(matches) > 1:
+        collisions = ", ".join(f"`{key}`" for key in matches)
+        raise NarrativeContractError(
+            f"owner=report-writer field `{display_path}` is not an allowed unique "
+            f"field; the label matches more than one schema key: {collisions}"
+        )
+    return matches[0]
+
+
+def _parse_scalar(values: list[str], node: Any, index: SchemaIndex, path: str) -> Any:
+    types = _node_types(node, index)
+    text = "\n".join(values)
+    if text == EMPTY_MARKER and "null" in types:
+        return None
+    if "boolean" in types and text in {"true", "false"}:
+        return text == "true"
+    if "integer" in types:
+        try:
+            return int(text)
+        except ValueError as exc:
+            raise NarrativeContractError(f"{path}: expected integer") from exc
+    if "number" in types:
+        try:
+            return float(text)
+        except ValueError as exc:
+            raise NarrativeContractError(f"{path}: expected number") from exc
+    return text
+
+
+def _parse_value(node: _Node, schema_node: Any, index: SchemaIndex, path: str) -> Any:
+    types = _node_types(schema_node, index)
+    if node.values:
+        if node.values == [EMPTY_MARKER] and "null" in types:
+            return None
+        if node.values == [EMPTY_MARKER] and "object" in types:
+            return {}
+        if node.values == [EMPTY_MARKER] and "array" in types:
+            return []
+        return _parse_scalar(node.values, schema_node, index, path)
+    if "array" in types or all(child.kind == "item" for child in node.children):
+        return _parse_array(node, schema_node, index, path)
+    return _parse_object(node, schema_node, index, path)
+
+
+def _parse_array(node: _Node, schema_node: Any, index: SchemaIndex, path: str) -> list[Any]:
+    if any(child.kind != "item" for child in node.children):
+        raise NarrativeContractError(f"{path}: array requires Item rows")
+    positions = [int(child.label) for child in node.children]
+    if positions != list(range(1, len(positions) + 1)):
+        raise NarrativeContractError(f"{path}: Item numbers must be 1..N")
+    item_schema = index.item(schema_node)
+    return [
+        _parse_value(child, item_schema, index, f"{path}[{position - 1}]")
+        for position, child in zip(positions, node.children, strict=True)
+    ]
+
+
+def _parse_object(node: _Node, schema_node: Any, index: SchemaIndex, path: str) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for child in node.children:
+        if child.kind != "field":
+            raise NarrativeContractError(f"{path}: object requires named fields")
+        key = _field_key(child.label, schema_node, index, path)
+        child_path = f"{path}.{key}" if path else key
+        if child_path in _NESTED_FORBIDDEN:
+            raise NarrativeContractError(
+                f"owner=report-writer cannot author `{path}.{child.label}`"
+            )
+        if key in result:
+            raise NarrativeContractError(f"duplicate field: {child_path}")
+        child_schema = index.child(schema_node, key)
+        if not _node_types(child_schema, index):
+            child_schema = index.schema_for_key(key)
+        result[key] = _parse_value(
+            child, child_schema, index, child_path
+        )
+    return result
+
+
+def parse_narrative(markdown: str, schema: Mapping[str, Any]) -> dict[str, Any]:
+    """Markdown을 작성자 소유 자료로 읽고 소유권 표면을 검증한다."""
+    root = _parse_tree(markdown)
+    index = SchemaIndex(schema)
+    result = _parse_object(root, schema, index, "")
+    unknown = sorted(set(result) - _allowed_top_level())
+    if unknown:
+        labels = [humanise(key) for key in unknown]
+        owned = ", ".join(
+            f"`{humanise(key)}`" for key in sorted(_allowed_top_level())
+        )
+        raise NarrativeContractError(
+            f"owner=report-writer cannot author fields: {labels}; "
+            f"writer-owned top-level fields: {owned}"
+        )
+    errors = validate(result, _narrative_schema())
+    if errors:
+        raise NarrativeContractError("; ".join(errors))
+    return result

package/runtime/python/okstra_ctl/report_projections.py

@@ -0,0 +1,265 @@
+"""역할별 실행 입력을 최종 리포트 조각으로 바꾸는 순수 투영."""
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from typing import Any, Mapping, Sequence
+
+from .design_surfaces import DesignSurfaceTrigger, detect_design_surfaces
+from .report_contract import execution_roles_from_manifest
+
+
+class ReportProjectionError(ValueError):
+    """소유자 입력을 정본 조각으로 투영할 수 없다."""
+
+
+_AGENT_LABELS = {
+    "claude": "Claude Code",
+    "claude-code": "Claude Code",
+    "codex": "Codex",
+    "antigravity": "Antigravity",
+    "grok": "Grok",
+    "kimi": "Kimi",
+}
+_STATUS = {
+    "done": "completed",
+    "passed": "completed",
+    "failed": "error",
+    "blocked": "error",
+    "pending": "not-run",
+    "prepared": "not-run",
+}
+
+
+def _text(value: object, fallback: str) -> str:
+    text = str(value or "").strip()
+    return text or fallback
+
+
+def _status(value: object) -> str:
+    text = str(value or "not-run").strip().lower()
+    return _STATUS.get(text, text if text in {
+        "completed", "error", "timeout", "not-run", "synthesis-only"
+    } else "not-run")
+
+
+def _agent_label(row: Mapping[str, Any]) -> str:
+    value = _text(row.get("agent") or row.get("provider"), "codex")
+    return _AGENT_LABELS.get(value.lower(), value)
+
+
+def _execution_row(row: Mapping[str, Any], *, lead: bool = False) -> dict[str, Any]:
+    role = _text(row.get("role"), "Okstra lead" if lead else "Worker")
+    result = {
+        "agent": _agent_label(row),
+        "role": role,
+        "model": _text(row.get("model") or row.get("modelExecutionValue"), "unknown"),
+        "status": _status(row.get("status")),
+        "summary": _text(
+            row.get("summary") or row.get("reason"),
+            "Run coordination recorded by team state." if lead
+            else "Worker execution recorded by team state.",
+        ),
+    }
+    _populate_usage(result, row.get("usage") or {})
+    return result
+
+
+def _populate_usage(row: dict[str, Any], usage: object) -> None:
+    source = usage if isinstance(usage, Mapping) else {}
+    mapping = {
+        "totalTokens": "totalTokens",
+        "cacheReadTokens": "cacheReadTokens",
+        "billableEquivalentTokens": "billableTokens",
+        "estimatedCostUsd": "costUsd",
+        "cliTotalTokens": "cliTotalTokens",
+        "cliEstimatedCostUsd": "cliCostUsd",
+        "durationMs": "durationMs",
+    }
+    for source_key, target_key in mapping.items():
+        if source_key in source and source.get("source") != "unavailable":
+            row[target_key] = source[source_key]
+
+
+def project_execution(
+    manifest: Mapping[str, Any], team_state: Mapping[str, Any],
+) -> dict[str, Any]:
+    """실행 역할과 상태를 매니페스트·팀 상태에서만 만든다."""
+    lead = team_state.get("lead")
+    lead_row = lead if isinstance(lead, Mapping) else {
+        "agent": manifest.get("leadRuntime") or manifest.get("leadProvider"),
+        "model": manifest.get("leadModel") or "unknown",
+        "status": "completed",
+        "role": "Okstra lead",
+    }
+    workers = team_state.get("workers")
+    worker_rows = workers if isinstance(workers, list) else []
+    result: dict[str, Any] = {
+        "executionStatus": [
+            _execution_row(lead_row, lead=True),
+            *[
+                _execution_row(row)
+                for row in worker_rows
+                if isinstance(row, Mapping)
+            ],
+        ]
+    }
+    roles = execution_roles_from_manifest(dict(manifest))
+    if roles:
+        result.update(executionIdentityVersion=2, executionRoles=roles)
+    return result
+
+
+def _usage_row(summary: Mapping[str, Any], prefix: str, cost: object) -> dict[str, Any]:
+    return {
+        "totalTokens": summary.get(f"{prefix}TotalTokens"),
+        "cacheReadTokens": summary.get(f"{prefix}CacheReadTokens"),
+        "billableTokens": summary.get(f"{prefix}BillableEquivalentTokens"),
+        "costUsd": cost,
+    }
+
+
+def _worker_details(team_state: Mapping[str, Any]) -> list[dict[str, Any]]:
+    result = []
+    for worker in team_state.get("workers") or []:
+        if not isinstance(worker, Mapping):
+            continue
+        usage = worker.get("usage") if isinstance(worker.get("usage"), Mapping) else {}
+        row = {"label": _text(worker.get("role") or worker.get("workerId"), "Worker")}
+        _populate_usage(row, usage)
+        for key in ("totalTokens", "cacheReadTokens", "billableTokens", "costUsd", "cliTotalTokens", "cliCostUsd"):
+            row.setdefault(key, None)
+        result.append(row)
+    return result
+
+
+def project_token_usage(team_state: Mapping[str, Any]) -> dict[str, Any]:
+    """팀 상태의 사용량 합계를 리포트 표 구조로 반환한다."""
+    summary = team_state.get("usageSummary")
+    summary = summary if isinstance(summary, Mapping) else {}
+    costs = summary.get("estimatedCostUsd")
+    costs = costs if isinstance(costs, Mapping) else {}
+    lead_cost = costs.get("lead")
+    worker_cost = costs.get("claudeWorkers")
+    return {
+        "lead": _usage_row(summary, "lead", lead_cost),
+        "worker": _usage_row(summary, "worker", worker_cost),
+        "grand": _usage_row(
+            summary,
+            "grand",
+            None if lead_cost is None or worker_cost is None else lead_cost + worker_cost,
+        ),
+        "workerDetails": _worker_details(team_state),
+        "cli": {"costUsd": costs.get("cliWorkers")},
+    }
+
+
+def _trigger_rows(trigger: DesignSurfaceTrigger) -> list[dict[str, Any]]:
+    return [
+        {"step": item.step, "field": item.field, "match": item.match}
+        for item in trigger.evidence
+    ]
+
+
+def project_design(
+    planning: Mapping[str, Any], detector_snapshot: Mapping[str, Any],
+) -> dict[str, Any]:
+    """탐지 결과가 실제 계획 표면과 일치할 때만 설계 블록을 반환한다."""
+    triggers = detect_design_surfaces(planning)
+    expected = {(row.stage, row.kind): _trigger_rows(row) for row in triggers}
+    coverage = detector_snapshot.get("stageCoverage")
+    coverage = coverage if isinstance(coverage, list) else []
+    actual: dict[tuple[int, str], list[dict[str, Any]]] = {}
+    for stage in coverage:
+        if not isinstance(stage, Mapping):
+            raise ReportProjectionError("owner=design-surface-detector invalid stageCoverage row")
+        for row in stage.get("rows") or []:
+            if isinstance(row, Mapping):
+                actual[(int(stage.get("stage") or 0), str(row.get("kind") or ""))] = list(row.get("triggerEvidence") or [])
+    if expected != actual:
+        raise ReportProjectionError("owner=design-surface-detector trigger coverage mismatch")
+    preparation = detector_snapshot.get("designPreparation")
+    if not isinstance(preparation, Mapping):
+        raise ReportProjectionError("owner=design-surface-detector missing designPreparation")
+    return {
+        "designPreparation": deepcopy(dict(preparation)),
+        "stageCoverage": deepcopy(coverage),
+    }
+
+
+def _round_history(state: Mapping[str, Any]) -> dict[str, Any]:
+    if not (state.get("config") or {}).get("enabled", True):
+        return {"disabled": True}
+    rows = []
+    for row in state.get("roundHistory") or []:
+        if not isinstance(row, Mapping):
+            continue
+        rows.append({
+            "round": row.get("round", 0),
+            "inputQueueSize": row.get("inputQueueSize", 0),
+            "resolvedCount": row.get("resolvedCount", 0),
+            "carriedForwardCount": row.get("carriedForwardCount", 0),
+            "dispatches": json.dumps(row.get("dispatches") or [], ensure_ascii=False),
+            "skippedWorkers": json.dumps(row.get("skippedWorkers") or [], ensure_ascii=False),
+        })
+    return {"rounds": rows, "round2SkippedReason": state.get("round2SkippedReason", "not-skipped")}
+
+
+def _source_items(finding: Mapping[str, Any]) -> list[str]:
+    finding_id = _text(finding.get("findingId"), "unknown")
+    workers = finding.get("consensusWorkers") or [finding.get("originWorker")]
+    return [f"{_text(worker, 'worker').removesuffix('-worker')}:{finding_id}" for worker in workers]
+
+
+def project_convergence(state: Mapping[str, Any]) -> dict[str, Any]:
+    """수렴 상태에서 독자용 합의·이견과 공개 근거만 승격한다."""
+    consensus = []
+    differences = []
+    promoted = []
+    for finding in state.get("findings") or []:
+        if not isinstance(finding, Mapping):
+            continue
+        evidence = _text(finding.get("originEvidence"), "")
+        ticket_ids = finding.get("ticketIds") or ["unknown"]
+        ticket_id = _text(ticket_ids[0] if ticket_ids else "unknown", "unknown")
+        if finding.get("classification") in {"full-consensus", "partial-consensus"}:
+            row = {
+                "id": f"C-{len(consensus) + 1:03d}",
+                "ticketId": ticket_id,
+                "statement": _text(finding.get("summary"), "Converged finding"),
+                "sourceItems": _source_items(finding),
+                "evidence": evidence or "convergence state",
+            }
+            consensus.append(row)
+            if evidence and ("/" in evidence or ":" in evidence):
+                promoted.append({
+                    "findingId": finding.get("findingId"),
+                    "ticketId": ticket_id,
+                    "evidence": evidence,
+                    "sourceItems": row["sourceItems"],
+                })
+        else:
+            positions = []
+            for worker in [finding.get("originWorker"), *(finding.get("dissentingWorkers") or [])]:
+                if worker:
+                    positions.append({
+                        "worker": str(worker),
+                        "itemId": _text(finding.get("findingId"), ""),
+                        "position": "origin" if worker == finding.get("originWorker") else "dissent",
+                    })
+            differences.append({
+                "id": f"D-{len(differences) + 1:03d}",
+                "ticketId": ticket_id,
+                "disagreement": _text(finding.get("summary"), "Unresolved difference"),
+                "workersPosition": positions or [{"worker": "unknown", "itemId": "", "position": "unresolved"}],
+                "evidence": evidence or "convergence state",
+            })
+    result = {
+        "crossVerification": {
+            "roundHistory": _round_history(state),
+            "consensus": consensus,
+            "differences": differences,
+        },
+        "promotedEvidence": promoted,
+    }
+    return result