okstra 0.179.2 → 0.180.0

package/runtime/python/okstra_ctl/report_finalize.py

@@ -1,10 +1,11 @@
 """Phase 7 report post-processing — the single reference point.
 
-Phase 7 turns a Phase 6 final-report data.json into shippable artifacts through
-six ordered steps: activity projection, English-SSOT verification, usage
-substitution, html view rendering, follow-up task spawning, and run validation.
-The order is load-bearing — rendering before substitution ships `--` token
-cells, and validating before rendering trips the report-views contract.
+Contract 3.0 collects usage into team state, assembles the role-owned inputs
+into final-report data.json once, then verifies and renders that published
+record. Contract 2.0 keeps its historical in-place projection sequence for
+read-only compatibility. The order is load-bearing: rendering before assembly
+or usage collection publishes stale derived views, and validating before
+rendering trips the report-views contract.
 
 `token-usage` is the one step whose failure does not stop the sequence, which
 deliberately accepts that first state: its input is the lead session log, so a
@@ -39,6 +40,7 @@ from typing import Any, Callable, Mapping, Sequence
 
 from .agent_activity import ActivityProjectionError, project_agent_activity
 from .report_contract import apply_execution_roles
+from .report_assembly import ReportAssemblyError, assemble_report
 from .dispatch_state import DispatchError, link_agent_dispatch_result
 from .final_report_paths import final_report_data_path, final_report_markdown_path
 from .paths import task_dir, task_manifest_file
@@ -74,6 +76,16 @@ STEP_ORDER = (
     STEP_TEARDOWN_STAGES,
 )
 
+V3_STEP_ORDER = (
+    STEP_TOKEN_USAGE,
+    STEP_PROJECT_ACTIVITY,
+    STEP_CHECK_SOURCE,
+    STEP_RENDER_VIEWS,
+    STEP_SPAWN_FOLLOWUPS,
+    STEP_VALIDATE_RUN,
+    STEP_TEARDOWN_STAGES,
+)
+
 
 class FinalizeError(Exception):
     """Raised when the Phase 7 sequence cannot be assembled."""
@@ -226,6 +238,7 @@ class FinalizeContext:
     task_id: str
     seq: str
     final_status_path: Path | None
+    report_contract_version: str = "2.0"
 
     @property
     def markdown_path(self) -> Path:
@@ -257,13 +270,16 @@ class FinalizeContext:
             final_status_path=resolve_optional_path(
                 project_root, manifest.get("finalStatusPath")
             ),
+            report_contract_version=str(
+                manifest.get("reportContractVersion") or "2.0"
+            ),
         )
 
 
 def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
     """Assemble the ordered Phase 7 argv list. Order is contractual."""
     markdown_path = ctx.markdown_path
-    return [
+    commands = [
         (
             STEP_PROJECT_ACTIVITY,
             [
@@ -344,6 +360,16 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
             ["<in-process>", "teardown-stages", str(ctx.data_path)],
         ),
     ]
+    if ctx.report_contract_version != "3.0":
+        return commands
+    by_name = dict(commands)
+    usage = by_name[STEP_TOKEN_USAGE]
+    marker = usage.index("--substitute-data")
+    by_name[STEP_TOKEN_USAGE] = usage[:marker]
+    by_name[STEP_PROJECT_ACTIVITY] = [
+        "<in-process>", "report-assembly", str(ctx.manifest_path), str(ctx.data_path)
+    ]
+    return [(name, by_name[name]) for name in V3_STEP_ORDER]
 
 
 def _teardown_stage_worktrees(
@@ -441,14 +467,16 @@ def run_finalize(
     steps: list[dict[str, Any]] = []
     deferred = ""
     try:
-        write_execution_roles(ctx)
+        if ctx.report_contract_version != "3.0":
+            write_execution_roles(ctx)
         commands = build_commands(ctx)
     except FinalizeError as exc:
         return {"ok": False, "reason": str(exc), "steps": steps}
 
     if only:
         selected = set(only)
-        unknown = sorted(selected - set(STEP_ORDER))
+        contract_order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
+        unknown = sorted(selected - set(contract_order))
         if unknown:
             return {
                 "ok": False,
@@ -462,12 +490,17 @@ def run_finalize(
             before_step(name)
         if name == STEP_PROJECT_ACTIVITY:
             try:
-                rows = project_agent_activity(
-                    ctx.project_root,
-                    ctx.manifest_path,
-                    ctx.data_path,
-                )
-            except ActivityProjectionError as exc:
+                if ctx.report_contract_version == "3.0":
+                    assembled = assemble_report(ctx.project_root, ctx.manifest_path)
+                    count = len(assembled.get("agentActivity") or [])
+                else:
+                    rows = project_agent_activity(
+                        ctx.project_root,
+                        ctx.manifest_path,
+                        ctx.data_path,
+                    )
+                    count = len(rows)
+            except (ActivityProjectionError, ReportAssemblyError) as exc:
                 result = subprocess.CompletedProcess(
                     command,
                     1,
@@ -478,7 +511,7 @@ def run_finalize(
                 result = subprocess.CompletedProcess(
                     command,
                     0,
-                    json.dumps({"count": len(rows)}),
+                    json.dumps({"count": count}),
                     "",
                 )
         else:
@@ -633,7 +666,9 @@ def _parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _step_summary_lines(result: Mapping[str, Any]) -> list[str]:
+def _step_summary_lines(
+    result: Mapping[str, Any], order: Sequence[str] = STEP_ORDER,
+) -> list[str]:
     """One human-readable line per step, so the outcome is legible without
     parsing the JSON payload."""
     lines = []
@@ -641,13 +676,15 @@ def _step_summary_lines(result: Mapping[str, Any]) -> list[str]:
         code = step.get("exitCode")
         mark = "ok  " if code == 0 else "FAIL"
         lines.append(f"  [{mark}] {step.get('name')} (exit {code})")
-    for name in STEP_ORDER:
+    for name in order:
         if not any(s.get("name") == name for s in (result.get("steps") or [])):
             lines.append(f"  [skip] {name}")
     return lines
 
 
-def _recovery_step_names(result: Mapping[str, Any]) -> list[str]:
+def _recovery_step_names(
+    result: Mapping[str, Any], order: Sequence[str] = STEP_ORDER,
+) -> list[str]:
     """The steps a retry has to re-run: every step from the earliest failure on.
 
     Naming only the failed steps would prescribe half a recovery. `token-usage`
@@ -664,9 +701,9 @@ def _recovery_step_names(result: Mapping[str, Any]) -> list[str]:
         for step in (result.get("steps") or [])
         if step.get("exitCode") != 0
     }
-    for index, name in enumerate(STEP_ORDER):
+    for index, name in enumerate(order):
         if name in failed:
-            return list(STEP_ORDER[index:])
+            return list(order[index:])
     return []
 
 
@@ -682,13 +719,14 @@ def main(argv: Sequence[str] | None = None) -> int:
     # sequence because the token-usage step below reads `leadSessionIds`.
     observe_lead_session(ctx.project_root, ctx.team_state_path)
     result = run_finalize(ctx, only=args.only or None)
+    order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
     print(json.dumps(result, indent=2, ensure_ascii=False))
     print("finalize steps:", file=sys.stderr)
-    for line in _step_summary_lines(result):
+    for line in _step_summary_lines(result, order):
         print(line, file=sys.stderr)
     if not result["ok"]:
         print(f"error: {result['reason']}", file=sys.stderr)
-        recovery = _recovery_step_names(result)
+        recovery = _recovery_step_names(result, order)
         if recovery:
             flags = " ".join(f"--only {name}" for name in recovery)
             print(

package/runtime/python/okstra_ctl/report_inputs.py

@@ -0,0 +1,72 @@
+"""리포트 계약 3.0의 역할별 입력 경로와 단일 소유자 레지스트리."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+
+REPORT_CONTRACT_V3 = "3.0"
+
+
+class ReportInputError(ValueError):
+    """3.0 입력 경로나 소유자가 매니페스트에서 해소되지 않았다."""
+
+
+@dataclass(frozen=True)
+class ReportInputPath:
+    key: str
+    owner: str
+    path: Path
+
+
+_INPUT_FIELDS = (
+    ("narrative", "report-writer", "reportNarrativePath"),
+    ("approval-decisions", "lead", "approvalDecisionsPath"),
+    ("agent-activity", "activity-ledger", "leadEventsPath"),
+    ("execution-status", "team-state", "teamStatePath"),
+    ("convergence", "convergence", "convergenceStatePath"),
+)
+
+_PLANNING_INPUT_FIELDS = (
+    ("design-preparation", "design-surface-detector", "designPreparationPath"),
+    ("plan-body-verification", "convergence", "planBodyVerificationPath"),
+)
+
+
+def uses_report_contract_v3(manifest: Mapping[str, Any]) -> bool:
+    return str(manifest.get("reportContractVersion") or "").strip() == REPORT_CONTRACT_V3
+
+
+def _project_path(project_root: Path, value: object, field: str) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise ReportInputError(f"report contract 3.0 requires {field}")
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def report_narrative_path(
+    project_root: Path, manifest: Mapping[str, Any],
+) -> Path:
+    if not uses_report_contract_v3(manifest):
+        raise ReportInputError("report narrative path belongs to report contract 3.0")
+    return _project_path(project_root, manifest.get("reportNarrativePath"), "reportNarrativePath")
+
+
+def report_input_paths(
+    project_root: Path, manifest: Mapping[str, Any],
+) -> tuple[ReportInputPath, ...]:
+    if not uses_report_contract_v3(manifest):
+        raise ReportInputError("role-owned report inputs require report contract 3.0")
+    fields = _INPUT_FIELDS + (
+        _PLANNING_INPUT_FIELDS
+        if manifest.get("taskType") == "implementation-planning"
+        else ()
+    )
+    rows = tuple(
+        ReportInputPath(key, owner, _project_path(project_root, manifest.get(field), field))
+        for key, owner, field in fields
+    )
+    if len({row.key for row in rows}) != len(rows):
+        raise ReportInputError("report input keys must be unique")
+    return rows

package/runtime/python/okstra_ctl/report_markdown.py

@@ -105,6 +105,7 @@ class SchemaIndex:
 
     def __init__(self, schema: Any) -> None:
         self._defs = schema.get("$defs", {}) if isinstance(schema, dict) else {}
+        self._schema = schema if isinstance(schema, dict) else {}
 
     def resolve(self, node: Any) -> dict:
         seen: set[str] = set()
@@ -118,10 +119,21 @@ class SchemaIndex:
 
     def _branches(self, node: Any) -> list[dict]:
         resolved = self.resolve(node)
-        branches = [resolved]
-        for keyword in ("allOf", "oneOf", "anyOf"):
-            for branch in resolved.get(keyword) or ():
-                branches.append(self.resolve(branch))
+        branches: list[dict] = []
+        pending = [resolved]
+        seen: set[int] = set()
+        while pending:
+            branch = pending.pop(0)
+            identity = id(branch)
+            if identity in seen:
+                continue
+            seen.add(identity)
+            branches.append(branch)
+            for keyword in ("allOf", "oneOf", "anyOf"):
+                pending.extend(
+                    self.resolve(candidate)
+                    for candidate in branch.get(keyword) or ()
+                )
         return branches
 
     def key_order(self, node: Any) -> list[str]:
@@ -133,17 +145,66 @@ class SchemaIndex:
         return order
 
     def child(self, node: Any, key: str) -> dict:
+        candidates: list[dict] = []
         for branch in self._branches(node):
             candidate = (branch.get("properties") or {}).get(key)
             if candidate is not None:
-                return self.resolve(candidate)
-        return {}
+                candidates.append(self.resolve(candidate))
+        return max(candidates, key=_schema_detail, default={})
 
     def item(self, node: Any) -> dict:
+        candidates: list[dict] = []
         for branch in self._branches(node):
             if "items" in branch:
-                return self.resolve(branch["items"])
-        return {}
+                candidates.append(self.resolve(branch["items"]))
+        return max(candidates, key=_schema_detail, default={})
+
+    def keys_for_label(self, label: str) -> list[str]:
+        """전체 스키마에서 사람이 읽는 표기가 일치하는 고유 키 후보."""
+        found: set[str] = set()
+        pending: list[Any] = [self._schema]
+        seen: set[int] = set()
+        while pending:
+            node = pending.pop()
+            if isinstance(node, list):
+                pending.extend(node)
+                continue
+            if not isinstance(node, dict) or id(node) in seen:
+                continue
+            seen.add(id(node))
+            for key in (node.get("properties") or {}):
+                if humanise(key) == label:
+                    found.add(key)
+            pending.extend(node.values())
+        return sorted(found)
+
+    def schema_for_key(self, key: str) -> dict:
+        """전체 스키마에서 이 키를 가장 구체적으로 설명하는 후보."""
+        found: list[dict] = []
+        pending: list[Any] = [self._schema]
+        seen: set[int] = set()
+        while pending:
+            node = pending.pop()
+            if isinstance(node, list):
+                pending.extend(node)
+                continue
+            if not isinstance(node, dict) or id(node) in seen:
+                continue
+            seen.add(id(node))
+            candidate = (node.get("properties") or {}).get(key)
+            if isinstance(candidate, dict):
+                found.append(self.resolve(candidate))
+            pending.extend(node.values())
+        return max(found, key=_schema_detail, default={})
+
+
+def _schema_detail(node: dict) -> tuple[int, int]:
+    """구체적인 분기 스키마가 빈 호환 스키마보다 먼저 선택되게 한다."""
+    structural = sum(
+        1 for key in ("properties", "items", "required", "enum", "const", "type")
+        if key in node
+    )
+    return structural, len(str(node))
 
 
 def _is_scalar(value: Any) -> bool:

package/runtime/python/okstra_ctl/report_narrative.py

@@ -0,0 +1,319 @@
+"""보고서 작성자 전담 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
+
+
+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 json.loads(_narrative_schema_path().read_text(encoding="utf-8"))
+
+
+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")
+    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 _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(humanise(key), []).append(key)
+    matches = candidates.get(label, [])
+    if not matches:
+        matches = index.keys_for_label(label)
+    display_path = f"{path}.{label}" if path else label
+    if len(matches) != 1:
+        raise NarrativeContractError(
+            f"owner=report-writer field `{display_path}` is not an allowed unique field"
+        )
+    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]
+        raise NarrativeContractError(
+            f"owner=report-writer cannot author fields: {labels}"
+        )
+    errors = validate(result, _narrative_schema())
+    if errors:
+        raise NarrativeContractError("; ".join(errors))
+    return result