okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/ports/worker_dispatch.py

@@ -15,7 +15,8 @@ class WorkerDispatchRequest:
     workspace_root: Path | None = None
     okstra_bin: Path | None = None
     requested_workers: tuple[str, ...] = ()
-    idle_timeout_seconds: int = 600
+    # 기본은 "정하지 않음" 이다. 그래야 엔트리포인트가 역할의 예산을 쓴다.
+    idle_timeout_seconds: int | None = None
     dispatch_kind: str = "initial"
     jobs_file: Path | None = None
 

package/runtime/python/okstra_ctl/pr_template.py

@@ -21,6 +21,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from okstra_project.dirs import okstra_home, project_json_path
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 _DEFAULT_FILENAME = "pr-body.template.md"
 
@@ -49,8 +50,8 @@ def _read_json_field(path: Path, field: str) -> str:
     if not path.is_file():
         return ""
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        data = load_owned_object(path, artifact="PR template configuration")
+    except JsonBoundaryError:
         return ""
     if not isinstance(data, dict):
         return ""

package/runtime/python/okstra_ctl/project_meta.py

@@ -1,11 +1,11 @@
 """프로젝트 meta.json 업서트."""
 from __future__ import annotations
 
-import json
-import os
 from pathlib import Path
 from typing import Optional
 
+from .json_boundary import load_owned_object, write_owned_object_atomic
+
 
 def _project_meta_path(home: Path, project_id: str) -> Path:
     return home / "projects" / project_id / "meta.json"
@@ -16,7 +16,7 @@ def load_project_meta(home: Path, project_id: str) -> Optional[dict]:
     p = _project_meta_path(home, project_id)
     if not p.is_file():
         return None
-    return json.loads(p.read_text())
+    return load_owned_object(p, artifact="project metadata")
 
 
 def upsert_project_meta(home: Path, project_id: str, *,
@@ -29,7 +29,7 @@ def upsert_project_meta(home: Path, project_id: str, *,
     target = _project_meta_path(home, project_id)
     target.parent.mkdir(parents=True, exist_ok=True)
     if target.is_file():
-        meta = json.loads(target.read_text())
+        meta = load_owned_object(target, artifact="project metadata")
     else:
         meta = {
             "projectId": project_id,
@@ -46,6 +46,4 @@ def upsert_project_meta(home: Path, project_id: str, *,
         meta["activeCount"] = int(meta.get("activeCount", 0)) + 1
     if finished:
         meta["activeCount"] = max(0, int(meta.get("activeCount", 0)) - 1)
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(meta, indent=2) + "\n")
-    os.replace(tmp, target)
+    write_owned_object_atomic(target, meta, artifact="project metadata")

package/runtime/python/okstra_ctl/recap.py

@@ -15,6 +15,8 @@ from okstra_ctl import next_phase
 from okstra_ctl.clarification_items import sidecar_answers, user_response_sidecars
 from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.incremental_scope import preview_link_availability_for_report
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+from okstra_ctl.jsonl import append_jsonl
 from okstra_ctl.paths import task_timeline_file
 from okstra_project import read_task_key
 from okstra_ctl.run_context import dir_flock
@@ -29,8 +31,8 @@ def _load_timeline(task_root: Path) -> list[dict]:
     if not path.is_file():
         return []
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except Exception:
+        data = load_owned_object(path, artifact="task timeline")
+    except (JsonBoundaryError, OSError):
         return []
     runs = data.get("runs", [])
     return runs if isinstance(runs, list) else []
@@ -150,8 +152,7 @@ def append_recap_entry(task_root, project_root, *, kind, mode, question,
     # 과 같은 append-only idiom — 데이터 fd 가 아닌 별도 .lock 파일을 잠가야
     # flush 가 락 안에서 끝난다).
     with dir_flock(recap_dir, ".recap-log.lock"):
-        with log_path.open("a", encoding="utf-8") as fh:
-            fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        append_jsonl(log_path, entry, ensure_ascii=False, compact=False)
     return {"logPath": project_rel(log_path, project_root), "entry": entry}
 
 

package/runtime/python/okstra_ctl/reconcile.py

@@ -1,17 +1,16 @@
 """reconciliation/normalization."""
 from __future__ import annotations
 
-import json
-import os
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
-from .jsonl import append_jsonl, rotate_recent_if_needed
+from .jsonl import append_jsonl, rewrite_jsonl, rotate_recent_if_needed
 from .locks import central_lock
 from .paths import resolve_under_root
 from .project_meta import upsert_project_meta
 from .run_index_row import read_run_index, slim_run_row
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 
 DEFAULT_ABORT_AFTER_SECONDS = 12 * 3600  # 12시간 무진척이면 aborted 로 간주
@@ -70,8 +69,8 @@ def _read_run_manifest_validation(project_root: Path, run_dir_rel: str,
     if not manifest.is_file():
         return "not-run"
     try:
-        data = json.loads(manifest.read_text())
-    except (OSError, json.JSONDecodeError):
+        data = load_owned_object(manifest, artifact="run manifest")
+    except JsonBoundaryError:
         return "not-run"
     validation = data.get("validation")
     if isinstance(validation, dict):
@@ -94,11 +93,7 @@ def _sync_project_index(home: Path, project_id: str, updated_rows: list) -> None
         src = by_id.get(er.get("runId"))
         if src:
             er.update({k: src[k] for k in ("status", "finishedAt", "validation")})
-    tmp = proj_index.with_suffix(".jsonl.tmp")
-    with tmp.open("w") as f:
-        for er in existing:
-            f.write(json.dumps(slim_run_row(er), separators=(",", ":")) + "\n")
-    os.replace(tmp, proj_index)
+    rewrite_jsonl(proj_index, [slim_run_row(row) for row in existing])
 
 
 def reconcile_active(home: Path, *,
@@ -116,6 +111,20 @@ def reconcile_active(home: Path, *,
                                         project=project)
 
 
+def _publish_promoted(
+    home: Path, active: Path, survivors: list[dict], promoted: list[dict]
+) -> None:
+    rewrite_jsonl(active, [slim_run_row(row) for row in survivors])
+    for row in promoted:
+        append_jsonl(home / "recent.jsonl", slim_run_row(row))
+        _sync_project_index(home, row["projectId"], [row])
+        upsert_project_meta(
+            home, row["projectId"], project_root=row["projectRoot"],
+            when=row["finishedAt"], finished=True,
+        )
+    rotate_recent_if_needed(home)
+
+
 def _reconcile_active_locked(home: Path, *,
                              abort_after_seconds: int,
                              project: Optional[str] = None) -> dict:
@@ -171,18 +180,7 @@ def _reconcile_active_locked(home: Path, *,
         summary["running"] += 1
     if not promoted:
         return summary
-    tmp = active.with_suffix(".jsonl.tmp")
-    with tmp.open("w") as f:
-        for row in survivors:
-            f.write(json.dumps(slim_run_row(row), separators=(",", ":")) + "\n")
-    os.replace(tmp, active)
-    for row in promoted:
-        append_jsonl(home / "recent.jsonl", slim_run_row(row))
-        _sync_project_index(home, row["projectId"], [row])
-        upsert_project_meta(home, row["projectId"],
-                            project_root=row["projectRoot"],
-                            when=row["finishedAt"], finished=True)
-    rotate_recent_if_needed(home)
+    _publish_promoted(home, active, survivors, promoted)
     return summary
 
 
@@ -225,11 +223,7 @@ def _reconcile_recent_locked(home: Path, *, project: Optional[str] = None) -> di
         summary["completed" if new_status == "completed" else "failed"] += 1
     if not updated_by_project:
         return summary
-    tmp = recent.with_suffix(".jsonl.tmp")
-    with tmp.open("w") as f:
-        for row in rows:
-            f.write(json.dumps(slim_run_row(row), separators=(",", ":")) + "\n")
-    os.replace(tmp, recent)
+    rewrite_jsonl(recent, [slim_run_row(row) for row in rows])
     for pid, urows in updated_by_project.items():
         _sync_project_index(home, pid, urows)
     return summary

package/runtime/python/okstra_ctl/registry/host_discovery.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from ..domain.host import HostAdapterContractError
+from ..json_boundary import JsonBoundaryError, load_owned_object
 
 
 @dataclass(frozen=True)
@@ -66,8 +67,8 @@ def _read_manifest(manifest_path: Path) -> HostManifest:
 
 def _read_json_object(manifest_path: Path) -> dict[str, object]:
     try:
-        raw = json.loads(manifest_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        raw = load_owned_object(manifest_path, artifact="host adapter manifest")
+    except JsonBoundaryError as exc:
         raise HostAdapterContractError(
             f"invalid host manifest: {manifest_path}"
         ) from exc

package/runtime/python/okstra_ctl/registry/provider_registry.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from okstra_project.dirs import okstra_home
 
 from ..domain.provider import ProviderSpec, UnknownProviderError
+from ..json_boundary import JsonBoundaryError, load_owned_object
 from .factory_loader import FactoryLoadError, load_relative_factory
 
 
@@ -121,8 +122,8 @@ def _manifest_paths(roots: Iterable[Path]) -> tuple[Path, ...]:
 
 def _read_manifest(manifest_path: Path) -> tuple[str, str]:
     try:
-        raw = json.loads(manifest_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        raw = load_owned_object(manifest_path, artifact="provider adapter manifest")
+    except JsonBoundaryError as exc:
         raise ProviderAdapterContractError(f"invalid provider manifest: {manifest_path}") from exc
     if not isinstance(raw, dict) or raw.get("schemaVersion") != 1:
         raise ProviderAdapterContractError(f"invalid provider manifest: {manifest_path}")

package/runtime/python/okstra_ctl/render.py

@@ -46,6 +46,8 @@ from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
 from .path_hints import compact_active_run_context, hydrate_run_context
 from .paths import task_timeline_file
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+from .report_contract import CURRENT_REPORT_SCHEMA_VERSION
 from .worker_artifacts import artifacts_from_context
 from .workflow import PHASE_SEQUENCE
 
@@ -73,7 +75,9 @@ def _load_ctx(ctx_arg: str) -> dict:
     s = ctx_arg.lstrip()
     if s.startswith("{"):
         return hydrate_run_context(json.loads(ctx_arg))
-    return hydrate_run_context(json.loads(Path(ctx_arg).read_text(encoding="utf-8")))
+    return hydrate_run_context(
+        load_owned_object(Path(ctx_arg), artifact="render context")
+    )
 
 
 def _write_text(path: Path, text: str) -> None:
@@ -82,7 +86,7 @@ def _write_text(path: Path, text: str) -> None:
 
 
 def _write_json(path: Path, payload: dict) -> None:
-    _write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
+    write_owned_object_atomic(path, payload, artifact="rendered runtime object")
 
 
 def _execution_identity(ctx: Mapping[str, object]) -> dict:
@@ -873,7 +877,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
     entries = []
     for manifest_path in sorted(tasks_root.rglob(TASK_MANIFEST_FILENAME)):
         try:
-            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+            manifest = load_owned_object(manifest_path, artifact="task manifest")
         except Exception:
             continue
         if not isinstance(manifest, dict):
@@ -891,7 +895,7 @@ def render_task_catalog_discovery(output_path: str, ctx: dict) -> None:
         latest_run = {}
         if timeline_file.is_file():
             try:
-                payload = json.loads(timeline_file.read_text(encoding="utf-8"))
+                payload = load_owned_object(timeline_file, artifact="task timeline")
             except Exception:
                 payload = {}
             runs = payload.get("runs", []) if isinstance(payload, dict) else []
@@ -981,7 +985,9 @@ def render_latest_task_discovery(output_path: str, ctx: dict) -> None:
     task_manifest = {}
     if task_manifest_path.exists():
         try:
-            task_manifest = json.loads(task_manifest_path.read_text(encoding="utf-8"))
+            task_manifest = load_owned_object(
+                task_manifest_path, artifact="task manifest"
+            )
         except Exception:
             task_manifest = {}
     workflow = (
@@ -1343,7 +1349,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     existing = {}
     if path.exists():
         try:
-            existing = json.loads(path.read_text(encoding="utf-8"))
+            existing = load_owned_object(path, artifact="task manifest")
         except Exception:
             existing = {}
     reviewers = _resolve_workers(ctx)
@@ -1645,21 +1651,23 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     existing_run_manifest = {}
     if run_manifest_exists:
         try:
-            loaded_run_manifest = json.loads(
-                run_manifest_file.read_text(encoding="utf-8")
+            loaded_run_manifest = load_owned_object(
+                run_manifest_file, artifact="run manifest"
             )
             existing_run_manifest = (
                 loaded_run_manifest
                 if isinstance(loaded_run_manifest, dict)
                 else {}
             )
-        except (OSError, json.JSONDecodeError):
+        except JsonBoundaryError:
             existing_run_manifest = {}
     task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}
     if task_manifest_path.exists():
         try:
-            task_manifest = json.loads(task_manifest_path.read_text(encoding="utf-8"))
+            task_manifest = load_owned_object(
+                task_manifest_path, artifact="task manifest"
+            )
         except Exception:
             task_manifest = {}
     reviewers = _resolve_workers(ctx)
@@ -1686,12 +1694,16 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     execution_identity = _execution_identity(ctx)
     payload = {
         "schemaVersion": execution_identity.get("schemaVersion", "1.0"),
+        "reportContractVersion": CURRENT_REPORT_SCHEMA_VERSION,
         "okstraVersion": ctx.get("OKSTRA_VERSION", ""),
         "projectId": ctx.get("PROJECT_ID", ""),
         "taskGroup": ctx.get("TASK_GROUP", ""),
         "taskId": ctx.get("TASK_ID", ""),
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        "runTimestamp": ctx.get("RUN_TIMESTAMP_ISO", ""),
+        "reportLanguage": ctx.get("REPORT_LANGUAGE", "en") or "en",
+        "leadModel": ctx.get("LEAD_MODEL", ""),
         # Every other path in this manifest is project-relative; this is the
         # anchor they resolve against. Convergence reads it to place run
         # artifacts, so a manifest without it cannot seed a round.
@@ -1763,6 +1775,10 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
         "workerPromptPathByWorkerId": worker_prompt_paths,
         "expectedReportRecordPath": ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
+        "reportNarrativePath": ctx.get("REPORT_WRITER_NARRATIVE_RELATIVE_PATH", ""),
+        "approvalDecisionsPath": ctx.get("APPROVAL_DECISIONS_RELATIVE_PATH", ""),
+        "designPreparationPath": ctx.get("DESIGN_PREPARATION_RELATIVE_PATH", ""),
+        "planBodyVerificationPath": ctx.get("PLAN_BODY_VERIFICATION_STATE_RELATIVE_PATH", ""),
         "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
@@ -1847,7 +1863,10 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         payload["analysisScopeConfirmation"] = scope_confirmation
     if ctx.get("FIX_CYCLE_ID"):
         payload["fixCycleId"] = ctx["FIX_CYCLE_ID"]
-    if ctx.get("TASK_TYPE") == "implementation-planning":
+    if (
+        CURRENT_REPORT_SCHEMA_VERSION == "3.0"
+        or ctx.get("TASK_TYPE") == "implementation-planning"
+    ):
         if not run_manifest_exists:
             payload["activityContractVersion"] = 1
         elif "activityContractVersion" in existing_run_manifest:
@@ -1864,6 +1883,27 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     payload.update(execution_identity)
     _guard_invocation_manifest_rewrite(existing_run_manifest, payload)
     _write_json(Path(run_manifest_path), payload)
+    if CURRENT_REPORT_SCHEMA_VERSION == "3.0":
+        _initialize_report_ledgers(ctx, payload)
+
+
+def _initialize_report_ledgers(ctx: Mapping[str, Any], manifest: Mapping[str, Any]) -> None:
+    approval_value = str(ctx.get("APPROVAL_DECISIONS_PATH") or "")
+    approval_path = Path(approval_value)
+    if approval_value and not approval_path.is_file():
+        _write_json(approval_path, {
+            "schemaVersion": "1.0",
+            "owner": "lead",
+            "taskKey": manifest.get("taskKey"),
+            "taskType": manifest.get("taskType"),
+            "runSeq": (manifest.get("runSequencesByCategory") or {}).get("manifests"),
+            "activeClarifications": [],
+            "carriedDecisions": [],
+        })
+    activity_value = str(ctx.get("LEAD_EVENTS_PATH") or "")
+    activity_path = Path(activity_value)
+    if activity_value and not activity_path.is_file():
+        _write_text(activity_path, "")
 
 
 _MODEL_ASSIGNMENT_KEYS = {
@@ -1904,8 +1944,18 @@ _IMMUTABLE_INVOCATION_KEYS = (
     "workerPromptPathByWorkerId",
     "workerResultsDirectoryPath",
     "expectedReportRecordPath",
+    "reportNarrativePath",
+    "approvalDecisionsPath",
+    "designPreparationPath",
+    "planBodyVerificationPath",
     "reportTemplatePath",
 )
+_V3_REPORT_PATH_KEYS = frozenset({
+    "reportNarrativePath",
+    "approvalDecisionsPath",
+    "designPreparationPath",
+    "planBodyVerificationPath",
+})
 
 
 def _guard_invocation_manifest_rewrite(
@@ -1951,6 +2001,10 @@ def _validate_invocation_manifest(payload: Mapping[str, object]) -> None:
         item
         for item in _IMMUTABLE_INVOCATION_KEYS[4:]
         if item != "workerPromptPathByWorkerId"
+        and (
+            item not in _V3_REPORT_PATH_KEYS
+            or payload.get("reportContractVersion") == "3.0"
+        )
     ):
         if not payload.get(key):
             raise ValueError(f"incomplete invocation manifest path: {key}")
@@ -2039,7 +2093,9 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
     task_manifest = {}
     if task_manifest_path.exists():
         try:
-            task_manifest = json.loads(task_manifest_path.read_text(encoding="utf-8"))
+            task_manifest = load_owned_object(
+                task_manifest_path, artifact="task manifest"
+            )
         except Exception:
             task_manifest = {}
     reviewers = _resolve_workers(ctx)
@@ -2048,7 +2104,7 @@ def render_timeline(timeline_path: str, ctx: dict) -> None:
     existing = {}
     if path.exists():
         try:
-            existing = json.loads(path.read_text(encoding="utf-8"))
+            existing = load_owned_object(path, artifact="task timeline")
         except Exception:
             existing = {}
     runs = existing.get("runs", [])
@@ -2143,7 +2199,9 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     task_manifest = {}
     if task_manifest_path.exists():
         try:
-            task_manifest = json.loads(task_manifest_path.read_text(encoding="utf-8"))
+            task_manifest = load_owned_object(
+                task_manifest_path, artifact="task manifest"
+            )
         except Exception:
             task_manifest = {}
     workflow = (
@@ -2338,8 +2396,8 @@ def build_available_mcp_servers_block(project_root: Path) -> str:
     """
     config_path = project_json_path(project_root)
     try:
-        raw = json.loads(config_path.read_text(encoding="utf-8"))
-    except (FileNotFoundError, json.JSONDecodeError):
+        raw = load_owned_object(config_path, artifact="project config")
+    except JsonBoundaryError:
         return _NO_MCP_SERVERS_LINE
     servers = raw.get("mcpServers") if isinstance(raw, dict) else None
     if not isinstance(servers, list) or not servers:

package/runtime/python/okstra_ctl/render_final_report.py

@@ -2,7 +2,7 @@
 
 The JSON SSOT lives next to the rendered markdown as
 ``final-report-<task-type>-<seq>.data.json``. Its ``schemaVersion`` selects the
-matching final-report schema. Report-writer-worker writes the data.json in
+matching final-report schema. Report assembly writes the data.json in
 Phase 6; this renderer + the matching Jinja2 template deterministically
 produce the canonical AI-facing markdown.
 
@@ -49,6 +49,7 @@ from okstra_ctl.final_report_schema import (
     load_schema_for_data,
     validate as schema_validate,
 )
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, to_cell_text
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
@@ -66,6 +67,7 @@ from okstra_ctl.usage_cells import format_duration_ms, format_int, format_usd
 
 TEMPLATE_BY_SCHEMA_VERSION = {
     "2.0": ("templates", "reports", "final-report-v2.template.md"),
+    "3.0": ("templates", "reports", "final-report-v2.template.md"),
 }
 DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION[CURRENT_REPORT_SCHEMA_VERSION]
 
@@ -601,8 +603,8 @@ def validate_report_language(data: dict) -> str:
     if candidate == "auto":
         raise FinalReportRenderError(
             "reportLanguage 'auto' must be resolved by the lead before "
-            "the renderer runs; the report-writer worker writes the "
-            "resolved 'en' or 'ko' into data.json.meta.reportLanguage."
+            "the renderer runs; report assembly copies the resolved 'en' or "
+            "'ko' from the run manifest into data.json.meta.reportLanguage."
         )
     if candidate not in SUPPORTED_LANGS:
         raise FinalReportRenderError(
@@ -757,9 +759,9 @@ def _with_excerpt_drift_hint(
 ) -> FinalReportRenderError:
     """Name the contract drift behind a schema failure, when that is the cause.
 
-    A long run straddles its own runtime upgrade: the report-writer authors
-    against the excerpt frozen into the bundle at prep time, while the renderer
-    validates against the installed schema. Without this the author sees only
+    A long run straddles its own runtime upgrade: the report-writer authors its
+    narrative against the excerpt frozen into the bundle at prep time, while
+    assembly and the renderer validate against the installed schema. Without this the author sees only
     `additional property ... not allowed` for a field the excerpt told it to
     write, and has no way to tell a real mistake from a stale bundle.
 
@@ -802,8 +804,8 @@ def render_to_file(
     if not data_path.is_file():
         raise FinalReportRenderError(f"data file not found: {data_path}")
     try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
+        data = load_owned_object(data_path, artifact="final report record")
+    except JsonBoundaryError as exc:
         raise FinalReportRenderError(f"invalid JSON in {data_path}: {exc}") from exc
 
     # 템플릿은 data.json 위치가 아니라 이 모듈(설치본은 ~/.okstra/lib/python,