okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_ctl/json_boundary.py

@@ -0,0 +1,366 @@
+"""Strict JSON boundaries for okstra-owned artifacts."""
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+import tempfile
+from typing import Any
+
+from .final_report_schema import SchemaError, validate as validate_schema
+
+
+class JsonBoundaryError(ValueError):
+    """An owned JSON artifact could not satisfy its persistence contract."""
+
+    def __init__(self, path: Path, artifact: str, reason: str) -> None:
+        self.path = path
+        self.artifact = artifact
+        self.reason = reason
+        super().__init__(f"{artifact}: {reason}: {path}")
+
+
+_EXTERNAL_SOURCE_SEAL = object()
+
+
+@dataclass(frozen=True, init=False)
+class ExternalJsonSource:
+    """검증된 외부 생산자가 소유한 JSON 입력 경로다."""
+
+    path: Path
+    producer: str
+
+    def __init__(self, path: Path, producer: str, seal: object = None) -> None:
+        if seal is not _EXTERNAL_SOURCE_SEAL:
+            raise TypeError("ExternalJsonSource is sealed")
+        object.__setattr__(self, "path", path)
+        object.__setattr__(self, "producer", producer)
+
+
+@dataclass(frozen=True)
+class OwnedJsonSnapshot:
+    """한 번 읽은 원시 바이트와 그 바이트에서 검증한 객체다."""
+
+    value: dict[str, Any]
+    raw_bytes: bytes
+
+
+def _issue_external_source(path: Path, producer: str) -> ExternalJsonSource:
+    if not isinstance(path, Path):
+        raise TypeError("external JSON source requires Path")
+    return ExternalJsonSource(path, producer, _EXTERNAL_SOURCE_SEAL)
+
+
+def _is_okstra_owned_path(path: Path) -> bool:
+    lexical = Path(os.path.abspath(path))
+    resolved = path.resolve(strict=False)
+    return ".okstra" in lexical.parts or ".okstra" in resolved.parts
+
+
+def external_user_json_source(path: Path) -> ExternalJsonSource:
+    """사용자 제공 JSON이 Okstra 소유 트리 밖에 있을 때만 승인한다."""
+    if _is_okstra_owned_path(path):
+        raise JsonBoundaryError(path, "external JSON", "Okstra-owned path")
+    return _issue_external_source(path, "user")
+
+
+def external_worker_json_source(
+    path: Path, *, trusted_root: Path, lane_root: Path
+) -> ExternalJsonSource:
+    """신뢰 루트 아래의 정확한 worker 결과 lane만 승인한다."""
+    lexical_root = Path(os.path.abspath(trusted_root))
+    lexical_lane = Path(os.path.abspath(lane_root))
+    lexical_path = Path(os.path.abspath(path))
+    try:
+        lane_parts = lexical_lane.relative_to(lexical_root).parts
+    except ValueError:
+        lane_parts = ()
+    is_worker_lane = (
+        len(lane_parts) in {7, 8}
+        and lane_parts[:2] == (".okstra", "tasks")
+        and lane_parts[4] == "runs"
+        and lane_parts[-1] == "worker-results"
+        and (len(lane_parts) == 7 or lane_parts[6].startswith("stage-"))
+    )
+    if not is_worker_lane or lexical_path.parent != lexical_lane:
+        raise JsonBoundaryError(
+            path, "worker JSON", "outside worker result lanes"
+        )
+    try:
+        lexical_lane.relative_to(lexical_root)
+        lexical_path.relative_to(lexical_lane)
+        resolved_lane = lane_root.resolve(strict=False)
+        resolved_lane.relative_to(trusted_root.resolve(strict=False))
+        path.resolve(strict=False).relative_to(resolved_lane)
+    except ValueError as exc:
+        raise JsonBoundaryError(
+            path, "worker JSON", "outside worker result lanes"
+        ) from exc
+    if _has_symlink_component(lexical_lane, lexical_root) or _has_symlink_component(
+        lexical_path, lexical_lane
+    ):
+        raise JsonBoundaryError(path, "worker JSON", "outside worker result lanes")
+    return _issue_external_source(path, "worker")
+
+
+def external_invocation_json_source(
+    path: Path, *, project_root: Path, purpose: str
+) -> ExternalJsonSource:
+    """정확한 standalone purpose lane의 직접 결과만 승인한다."""
+    if not purpose or any(char not in "abcdefghijklmnopqrstuvwxyz0123456789-" for char in purpose):
+        raise JsonBoundaryError(path, "invocation JSON", "outside invocation result lane")
+    lane = project_root / ".okstra" / "agent-invocations" / purpose
+    lexical_path = Path(os.path.abspath(path))
+    lexical_lane = Path(os.path.abspath(lane))
+    lexical_root = Path(os.path.abspath(project_root))
+    if lexical_path.parent != lexical_lane or path.is_symlink():
+        raise JsonBoundaryError(path, "invocation JSON", "outside invocation result lane")
+    try:
+        lane.resolve(strict=False).relative_to(project_root.resolve(strict=False))
+        path.resolve(strict=False).relative_to(lane.resolve(strict=False))
+    except ValueError as exc:
+        raise JsonBoundaryError(
+            path, "invocation JSON", "outside invocation result lane"
+        ) from exc
+    if _has_symlink_component(lexical_lane, lexical_root):
+        raise JsonBoundaryError(path, "invocation JSON", "outside invocation result lane")
+    return _issue_external_source(path, "standalone worker")
+
+
+def _has_symlink_component(path: Path, root: Path) -> bool:
+    current = path
+    while current != root:
+        if current.is_symlink():
+            return True
+        if current.parent == current:
+            return True
+        current = current.parent
+    return root.is_symlink()
+
+
+def external_claude_global_json_source(
+    path: Path, home_dir: Path
+) -> ExternalJsonSource:
+    """호스트 어댑터가 지정한 home의 전역 Claude 설정만 승인한다."""
+    expected = home_dir / ".claude.json"
+    if Path(os.path.abspath(path)) != Path(os.path.abspath(expected)) or path.is_symlink():
+        raise JsonBoundaryError(path, "Claude JSON", "outside fixed adapter path")
+    return _issue_external_source(path, "Claude Code")
+
+
+def external_claude_team_json_source(path: Path) -> ExternalJsonSource:
+    """현재 사용자의 Claude team roster 설정만 승인한다."""
+    root = Path.home() / ".claude" / "teams"
+    try:
+        Path(os.path.abspath(path)).relative_to(Path(os.path.abspath(root)))
+        path.resolve(strict=False).relative_to(root.resolve(strict=False))
+    except ValueError as exc:
+        raise JsonBoundaryError(path, "Claude JSON", "outside Claude team root") from exc
+    if path.name != "config.json" or path.is_symlink():
+        raise JsonBoundaryError(path, "Claude JSON", "outside Claude team root")
+    return _issue_external_source(path, "Claude Code")
+
+
+def external_tool_json_source(path: Path, workspace_root: Path) -> ExternalJsonSource:
+    """외부 도구가 workspace의 비-Okstra 경로에 쓴 보고서만 승인한다."""
+    try:
+        path.resolve(strict=False).relative_to(workspace_root.resolve(strict=False))
+    except ValueError as exc:
+        raise JsonBoundaryError(path, "tool JSON", "outside tool workspace") from exc
+    if _is_okstra_owned_path(path):
+        raise JsonBoundaryError(path, "tool JSON", "Okstra-owned path")
+    return _issue_external_source(path, "external tool")
+
+
+def external_error_sidecar_source(path: Path) -> ExternalJsonSource:
+    """worker-results lane 또는 Okstra 밖 레거시 sidecar만 승인한다."""
+    if _is_okstra_owned_path(path):
+        raise JsonBoundaryError(
+            path, "worker error sidecar", "trusted worker lane is required"
+        )
+    return _issue_external_source(path, "legacy automation")
+
+
+class _NonstandardJsonConstant(ValueError):
+    """Raised by ``json.loads`` when a non-standard numeric token appears."""
+
+
+def load_owned_object(
+    path: Path,
+    *,
+    artifact: str,
+    schema: Mapping[str, Any] | None = None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
+) -> dict[str, Any]:
+    """Load and validate one okstra-owned JSON object."""
+    return load_owned_object_snapshot(
+        path,
+        artifact=artifact,
+        schema=schema,
+        validate_cross_fields=validate_cross_fields,
+    ).value
+
+
+def load_owned_object_snapshot(
+    path: Path,
+    *,
+    artifact: str,
+    schema: Mapping[str, Any] | None = None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
+) -> OwnedJsonSnapshot:
+    """한 번 읽은 바이트에서 객체를 파싱·검증해 함께 반환한다."""
+    try:
+        raw_bytes = path.read_bytes()
+        value = json.loads(
+            raw_bytes.decode("utf-8"),
+            parse_constant=_reject_nonstandard_json_constant,
+        )
+    except FileNotFoundError as exc:
+        raise JsonBoundaryError(path, artifact, "missing") from exc
+    except UnicodeDecodeError as exc:
+        raise JsonBoundaryError(path, artifact, "invalid JSON encoding") from exc
+    except _NonstandardJsonConstant as exc:
+        raise JsonBoundaryError(path, artifact, str(exc)) from exc
+    except json.JSONDecodeError as exc:
+        raise JsonBoundaryError(path, artifact, "invalid JSON") from exc
+    except OSError as exc:
+        raise JsonBoundaryError(path, artifact, f"I/O error while reading ({exc})") from exc
+    return OwnedJsonSnapshot(
+        value=_validate_owned(
+            value,
+            path=path,
+            artifact=artifact,
+            schema=schema,
+            validate_cross_fields=validate_cross_fields,
+        ),
+        raw_bytes=raw_bytes,
+    )
+
+
+def load_external_json(
+    source: ExternalJsonSource,
+    *,
+    artifact: str,
+    object_pairs_hook: Callable[[list[tuple[str, Any]]], Any] | None = None,
+) -> Any:
+    """Load external JSON without applying an owned-artifact contract."""
+    if not isinstance(source, ExternalJsonSource):
+        raise TypeError("load_external_json requires ExternalJsonSource")
+    path = source.path
+    try:
+        return json.loads(
+            path.read_text(encoding="utf-8"),
+            object_pairs_hook=object_pairs_hook,
+        )
+    except FileNotFoundError as exc:
+        raise JsonBoundaryError(path, artifact, "missing") from exc
+    except UnicodeDecodeError as exc:
+        raise JsonBoundaryError(path, artifact, "invalid JSON encoding") from exc
+    except json.JSONDecodeError as exc:
+        raise JsonBoundaryError(path, artifact, "invalid JSON") from exc
+    except OSError as exc:
+        raise JsonBoundaryError(path, artifact, f"I/O error while reading ({exc})") from exc
+
+
+def write_owned_object_atomic(
+    path: Path,
+    payload: Mapping[str, Any],
+    *,
+    artifact: str,
+    schema: Mapping[str, Any] | None = None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
+) -> None:
+    """Validate a payload before atomically replacing an owned artifact."""
+    serialized = serialize_owned_object(
+        path,
+        payload,
+        artifact=artifact,
+        schema=schema,
+        validate_cross_fields=validate_cross_fields,
+    )
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, raw_temp = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    except OSError as exc:
+        raise JsonBoundaryError(path, artifact, f"I/O error while preparing write ({exc})") from exc
+    temporary = Path(raw_temp)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(serialized)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except (TypeError, ValueError) as exc:
+        raise JsonBoundaryError(path, artifact, f"JSON serialization failed ({exc})") from exc
+    except OSError as exc:
+        raise JsonBoundaryError(path, artifact, f"I/O error while writing ({exc})") from exc
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def serialize_owned_object(
+    path: Path,
+    payload: Mapping[str, Any],
+    *,
+    artifact: str,
+    schema: Mapping[str, Any] | None = None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None = None,
+) -> str:
+    """전용 게시 프로토콜이 사용할 검증된 canonical 객체 문자열이다."""
+    owned = _validate_owned(
+        payload, path=path, artifact=artifact, schema=schema,
+        validate_cross_fields=validate_cross_fields,
+    )
+    try:
+        return json.dumps(
+            owned, ensure_ascii=False, indent=2, allow_nan=False
+        ) + "\n"
+    except (TypeError, ValueError) as exc:
+        raise JsonBoundaryError(
+            path, artifact, f"JSON serialization failed ({exc})"
+        ) from exc
+
+
+def mutate_owned_object_atomic(
+    path: Path,
+    mutation: Callable[[dict[str, Any]], dict[str, Any]],
+    **contract: Any,
+) -> dict[str, Any]:
+    """Load, mutate, validate, and atomically replace one owned object."""
+    payload = load_owned_object(path, **contract)
+    updated = mutation(dict(payload))
+    write_owned_object_atomic(path, updated, **contract)
+    return updated
+
+
+def _reject_nonstandard_json_constant(constant: str) -> None:
+    raise _NonstandardJsonConstant(f"non-standard JSON constant: {constant}")
+
+
+def _validate_owned(
+    value: object,
+    *,
+    path: Path,
+    artifact: str,
+    schema: Mapping[str, Any] | None,
+    validate_cross_fields: Callable[[dict[str, Any]], object] | None,
+) -> dict[str, Any]:
+    if not isinstance(value, Mapping):
+        raise JsonBoundaryError(path, artifact, "top-level JSON value must be an object")
+    owned = dict(value)
+    if schema is not None:
+        try:
+            schema_errors = validate_schema(owned, dict(schema))
+        except SchemaError as exc:
+            raise JsonBoundaryError(path, artifact, f"invalid schema ({exc})") from exc
+        if schema_errors:
+            raise JsonBoundaryError(path, artifact, f"schema validation failed ({schema_errors[0]})")
+    if validate_cross_fields is not None:
+        errors = validate_cross_fields(owned)
+        if isinstance(errors, str):
+            errors = [errors]
+        if errors:
+            raise JsonBoundaryError(path, artifact, f"cross-field validation failed ({next(iter(errors))})")
+    return owned

package/runtime/python/okstra_ctl/json_registry.py

@@ -3,11 +3,15 @@ from __future__ import annotations
 
 import contextlib
 import fcntl
-import json
-import os
 from collections.abc import Callable, Iterator
 from pathlib import Path
 
+from .json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
+
 
 @contextlib.contextmanager
 def registry_lock(lock_path: Path) -> Iterator[None]:
@@ -26,18 +30,12 @@ def registry_lock(lock_path: Path) -> Iterator[None]:
 
 def load_registry_json(path: Path, default_factory: Callable[[], dict]) -> dict:
     """Load a registry dict, or a fresh default when absent/corrupt."""
-    if not path.exists():
-        return default_factory()
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        return load_owned_object(path, artifact="registry")
+    except JsonBoundaryError:
         return default_factory()
-    return data if isinstance(data, dict) else default_factory()
 
 
 def save_registry_json(path: Path, data: dict) -> None:
-    """Persist registry JSON via temp file + ``os.replace``."""
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = path.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    os.replace(tmp, path)
+    """Persist registry JSON through the owned-artifact boundary."""
+    write_owned_object_atomic(path, data, artifact="registry")

package/runtime/python/okstra_ctl/jsonl.py

@@ -8,14 +8,31 @@ from pathlib import Path
 from typing import Callable, List, Optional
 
 
-def append_jsonl(path: Path, row: dict) -> None:
+def append_jsonl(
+    path: Path, row: dict, *, ensure_ascii: bool = True, compact: bool = True
+) -> None:
     """jsonl 파일 끝에 한 줄 append. 파일이 없으면 생성."""
     path.parent.mkdir(parents=True, exist_ok=True)
-    line = json.dumps(row, separators=(",", ":")) + "\n"
+    line = json.dumps(
+        row, separators=(",", ":") if compact else None,
+        ensure_ascii=ensure_ascii,
+    ) + "\n"
     with path.open("a") as f:
         f.write(line)
 
 
+def rewrite_jsonl(path: Path, rows: List[dict], *, ensure_ascii: bool = True) -> None:
+    """JSONL 행 전체를 임시 파일에 쓴 뒤 원자 교체한다."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    with temporary.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(
+                row, separators=(",", ":"), ensure_ascii=ensure_ascii
+            ) + "\n")
+    os.replace(temporary, path)
+
+
 def read_jsonl(path: Path) -> List[dict]:
     """jsonl 파일을 모두 읽어 dict 목록으로 반환. 파싱 실패 라인은 스킵."""
     if not path.is_file():

package/runtime/python/okstra_ctl/lead_events.py

@@ -2,7 +2,9 @@
 from __future__ import annotations
 
 import json
+import hashlib
 import re
+import uuid
 from contextlib import contextmanager
 from dataclasses import dataclass, field, replace
 from pathlib import Path
@@ -107,14 +109,44 @@ def _next_activity_id(events: list[LeadEvent]) -> str:
     return f"A-{max(numbers, default=0) + 1:03d}"
 
 
+def _activity_request_digest(details: Mapping[str, Any]) -> str:
+    payload = {
+        key: value for key, value in details.items()
+        if key not in {"activityId", "activityRequestDigest", "activityRequestRef", "activityVersion"}
+    }
+    encoded = json.dumps(_stable_json_value(payload), ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
 def append_activity_event(path: Path, event: LeadEvent) -> LeadEvent:
     """Assign the next activity ID and append the event under one lock."""
     if event.event_type != "activity":
         raise ValueError("activity append requires eventType=activity")
     with _event_log_lock(path):
         details = dict(event.details)
+        request_ref = details.get("activityRequestRef")
+        events = read_lead_events(path)
+        digest = _activity_request_digest(details)
+        if request_ref is not None:
+            if not isinstance(request_ref, str) or not request_ref:
+                raise ValueError("activityRequestRef must be a non-empty string")
+            for previous in events:
+                if (
+                    previous.event_type == event.event_type
+                    and previous.lead_runtime == event.lead_runtime
+                    and previous.task_key == event.task_key
+                    and previous.task_type == event.task_type
+                    and previous.run_seq == event.run_seq
+                    and previous.details.get("activityRequestRef") == request_ref
+                ):
+                    if previous.details.get("activityRequestDigest") != digest:
+                        raise ValueError("activity request reference has different payload")
+                    return previous
+            raise ValueError("unknown activity request reference")
+        details["activityRequestRef"] = f"activity-{uuid.uuid4().hex}"
+        details["activityRequestDigest"] = digest
         details["activityVersion"] = 1
-        details["activityId"] = _next_activity_id(read_lead_events(path))
+        details["activityId"] = _next_activity_id(events)
         stored = replace(event, details=details)
         _append_unlocked(path, stored)
     return stored

package/runtime/python/okstra_ctl/listing.py

@@ -1,13 +1,13 @@
 """list/format/show."""
 from __future__ import annotations
 
-import json
 import re as _re
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import List, Optional
 
 from .paths import resolve_under_root
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .reconcile import _parse_iso
 from .run_index_row import read_run_index
 
@@ -24,8 +24,8 @@ def list_projects(home: Path, *, only_active: bool = False,
         if not meta_file.is_file():
             continue
         try:
-            meta = json.loads(meta_file.read_text())
-        except (OSError, json.JSONDecodeError):
+            meta = load_owned_object(meta_file, artifact="project metadata")
+        except JsonBoundaryError:
             # 동시 쓰기/이전 크래시로 깨진 meta.json 하나가 전체 listing 을
             # 죽이지 않도록 해당 프로젝트만 건너뛴다(다른 JSON 리더와 동일 정책).
             continue

package/runtime/python/okstra_ctl/log_report.py

@@ -13,12 +13,18 @@ import json
 import sys
 from pathlib import Path
 
+from .fixed_text import line
+
 from okstra_project import resolve_project_root
+from okstra_ctl.json_boundary import load_owned_object
 
 
 def _project_id(project_root: Path) -> str:
     try:
-        return json.loads((project_root / ".okstra" / "project.json").read_text(encoding="utf-8")).get("projectId", "")
+        return load_owned_object(
+            project_root / ".okstra" / "project.json",
+            artifact="project configuration",
+        ).get("projectId", "")
     except (OSError, ValueError):
         return ""
 
@@ -120,6 +126,20 @@ def scan_logs(logs_root: Path, project_root: Path, top: int = 20) -> dict:
     }
 
 
+def render_result_text(result: dict) -> str:
+    parts = ["# Okstra Log Inventory\n\n", line("Project root", result.get("projectRoot")), line("Logs root", result.get("logsRoot"))]
+    totals = result.get("totals") if isinstance(result.get("totals"), dict) else {}
+    for key, label in (("fileCount", "File count"), ("totalBytes", "Total bytes"), ("taskCount", "Task count"), ("promptBytes", "Prompt bytes"), ("transcriptBytes", "Transcript bytes"), ("pairedFileCount", "Paired file count")):
+        parts.append(line(label, totals.get(key)))
+    for row in result.get("topLargest", []):
+        if isinstance(row, dict):
+            parts.extend(("\n## Log\n\n", line("Task key", row.get("taskKey")), line("Phase", row.get("phase")), line("Worker", row.get("worker")), line("Sequence", row.get("seq")), line("Size bytes", row.get("sizeBytes")), line("Modified epoch", row.get("mtimeEpoch")), line("Path", row.get("path"))))
+    for row in result.get("perTask", []):
+        if isinstance(row, dict):
+            parts.extend(("\n## Task total\n\n", line("Task key", row.get("taskKey")), line("File count", row.get("fileCount")), line("Total bytes", row.get("totalBytes")), line("Oldest epoch", row.get("oldestEpoch")), line("Newest epoch", row.get("newestEpoch"))))
+    return "".join(parts)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="okstra log-report",
@@ -128,12 +148,14 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--cwd", default=".")
     parser.add_argument("--top", type=int, default=20, help="topLargest entry count")
     parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    parser.add_argument("--text", action="store_true", help="emit fixed text fields")
     args = parser.parse_args(argv)
 
     project_root = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
     result = {"ok": True, "projectRoot": str(project_root)}
     result.update(scan_logs(project_root / ".okstra" / "tasks", project_root, top=args.top))
-    print(json.dumps(result, ensure_ascii=False, indent=2))
+    output = render_result_text(result) if args.text else json.dumps(result, ensure_ascii=False, indent=2)
+    print(output, end="" if args.text else "\n")
     return 0