ltcai 9.8.0 → 9.9.0

package/latticeai/core/tool_governor.py

@@ -44,6 +44,63 @@ _ADDITIVE_TOOLS = frozenset({
     "knowledge_graph_ingest",
 })
 
+# ── Mutating-tool inventory (single source of truth) ─────────────────────
+# Every tool with a side effect is classified into exactly one category so a
+# CI check can prove nothing slips through ungoverned. Categories:
+#   new_artifact         — only ever creates new content (additive)
+#   existing_content_update — can rewrite content that already exists
+#   delete               — removes existing content
+#   external_side_effect — acts outside the Brain (shell, deploy, desktop, net)
+#   internal_state       — agent-internal bookkeeping, not user content
+NEW_ARTIFACT = "new_artifact"
+EXISTING_CONTENT_UPDATE = "existing_content_update"
+DELETE = "delete"
+EXTERNAL_SIDE_EFFECT = "external_side_effect"
+INTERNAL_STATE = "internal_state"
+
+MUTATING_TOOL_INVENTORY: Dict[str, str] = {
+    # text files — fully proposal-capable (staged + applied as reviewed)
+    "write_file": EXISTING_CONTENT_UPDATE,
+    "edit_file": EXISTING_CONTENT_UPDATE,
+    # binary/document creators — can overwrite an existing file, but their
+    # output cannot be staged as a text diff, so an overwrite is fail-closed.
+    "create_docx": EXISTING_CONTENT_UPDATE,
+    "create_xlsx": EXISTING_CONTENT_UPDATE,
+    "create_pptx": EXISTING_CONTENT_UPDATE,
+    "create_pdf": EXISTING_CONTENT_UPDATE,
+    # home-sandbox write — same story: overwrite is fail-closed until the
+    # proposal service learns to stage home-sandbox paths.
+    "local_write": EXISTING_CONTENT_UPDATE,
+    # additive-only writes
+    "create_web_project": NEW_ARTIFACT,
+    "knowledge_save": NEW_ARTIFACT,
+    "obsidian_save": NEW_ARTIFACT,
+    "knowledge_graph_ingest": NEW_ARTIFACT,
+    # agent-internal state
+    "todo_write": INTERNAL_STATE,
+    # deletions
+    "delete_file": DELETE,
+    "remove_file": DELETE,
+    "clear_history": DELETE,
+    # external side effects (approval-gated, never proposal-based)
+    "run_command": EXTERNAL_SIDE_EFFECT,
+    "build_project": EXTERNAL_SIDE_EFFECT,
+    "deploy_project": EXTERNAL_SIDE_EFFECT,
+    "computer_click": EXTERNAL_SIDE_EFFECT,
+    "computer_type": EXTERNAL_SIDE_EFFECT,
+    "computer_key": EXTERNAL_SIDE_EFFECT,
+    "computer_scroll": EXTERNAL_SIDE_EFFECT,
+    "computer_drag": EXTERNAL_SIDE_EFFECT,
+    "computer_move": EXTERNAL_SIDE_EFFECT,
+    "computer_open_app": EXTERNAL_SIDE_EFFECT,
+    "computer_open_url": EXTERNAL_SIDE_EFFECT,
+}
+
+# Tools whose existing-content update the ChangeProposalService can actually
+# stage AND apply as a reviewed proposal. A tool that is proposal_required but
+# NOT here is fail-closed (blocked) rather than silently applied.
+PROPOSAL_CAPABLE_TOOLS = frozenset({"write_file", "edit_file"})
+
 
 def classify_tool_call(
     name: str,
@@ -83,19 +140,53 @@ def classify_tool_call(
         change = CHANGE_ADDITIVE
         reason = "write tool without an existing target"
 
+    proposal_required = change in {CHANGE_MUTATION, CHANGE_DESTRUCTIVE}
+    proposal_supported = name in PROPOSAL_CAPABLE_TOOLS
+    # A change that must be reviewed as a proposal but that we cannot stage is
+    # fail-closed: callers must block it instead of applying it silently.
+    fail_closed = proposal_required and not proposal_supported
+
     return {
         "tool": name,
         "change_class": change,
-        "proposal_required": change in {CHANGE_MUTATION, CHANGE_DESTRUCTIVE},
+        "proposal_required": proposal_required,
+        "proposal_supported": proposal_supported,
+        "fail_closed": fail_closed,
         "reason": reason,
     }
 
 
+def assert_governance_coverage(tool_names: "Any") -> None:
+    """Raise if any side-effecting registry tool is not classified.
+
+    A new mutating tool added to the registry without an inventory entry makes
+    this raise, so CI fails closed instead of shipping an ungoverned mutator.
+    Read-only tools (risk ``read``) are intentionally exempt.
+    """
+    missing = [
+        name for name in tool_names
+        if name not in MUTATING_TOOL_INVENTORY
+    ]
+    if missing:
+        raise ValueError(
+            "ungoverned mutating tools (add to MUTATING_TOOL_INVENTORY): "
+            + ", ".join(sorted(missing))
+        )
+
+
 __all__ = [
     "CHANGE_READ",
     "CHANGE_ADDITIVE",
     "CHANGE_MUTATION",
     "CHANGE_DESTRUCTIVE",
     "CHANGE_EXEC",
+    "NEW_ARTIFACT",
+    "EXISTING_CONTENT_UPDATE",
+    "DELETE",
+    "EXTERNAL_SIDE_EFFECT",
+    "INTERNAL_STATE",
+    "MUTATING_TOOL_INVENTORY",
+    "PROPOSAL_CAPABLE_TOOLS",
     "classify_tool_call",
+    "assert_governance_coverage",
 ]

package/latticeai/core/workspace_os.py

@@ -49,7 +49,7 @@ __all__ = [
     "remove_skill_directory",
 ]
 
-WORKSPACE_OS_VERSION = "9.8.0"
+WORKSPACE_OS_VERSION = "9.9.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/services/architecture_readiness.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, List
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
 
-ARCHITECTURE_VERSION_TARGET = "9.8.0"
+ARCHITECTURE_VERSION_TARGET = "9.9.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/change_proposals.py

@@ -21,9 +21,13 @@ change audit log. The classification itself lives in
 from __future__ import annotations
 
 import difflib
+import hashlib
 import logging
+import os
+import tempfile
+import threading
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from latticeai.core.tool_governor import classify_tool_call
 
@@ -34,6 +38,55 @@ _MAX_DIFF_LINES = 400
 _SMALL_TIER_DIFF_LINES = 40
 
 
+class ProposalConflictError(ValueError):
+    """The target file changed (or the proposal was already resolved) between
+    staging and approval — applying now would silently destroy user edits.
+
+    Subclasses :class:`ValueError` deliberately: API surfaces that only know
+    ``except ValueError`` degrade to a 4xx instead of applying or crashing,
+    while conflict-aware surfaces catch this class first and answer **409**
+    with a rebase hint.
+    """
+
+    def __init__(
+        self,
+        *,
+        reason: str,
+        path: str,
+        kind: str,
+        base_sha256: str = "",
+        current_sha256: str = "",
+        rebase_hint: str = "",
+    ) -> None:
+        self.reason = reason
+        self.path = path
+        self.kind = kind
+        self.base_sha256 = base_sha256
+        self.current_sha256 = current_sha256
+        self.rebase_hint = rebase_hint or (
+            "제안 생성 이후 파일 상태가 바뀌었습니다. 이 제안을 거부하고 "
+            "현재 파일 내용을 기준으로 제안을 다시 생성하세요."
+        )
+        super().__init__(f"change proposal conflict ({reason}): {path}")
+
+    def to_detail(self) -> Dict[str, Any]:
+        """409 response body — no staged content, just what the UI needs."""
+        return {
+            "error": "change_proposal_conflict",
+            "conflict": True,
+            "reason": self.reason,
+            "path": self.path,
+            "kind": self.kind,
+            "base_sha256": self.base_sha256,
+            "current_sha256": self.current_sha256,
+            "rebase_hint": self.rebase_hint,
+        }
+
+
+def _sha256_text(content: str) -> str:
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
 def _unified_diff(before: str, after: str, path: str) -> List[str]:
     lines = list(
         difflib.unified_diff(
@@ -60,6 +113,11 @@ class ChangeProposalService:
         self._review_queue = review_queue
         self._resolve_path = resolve_path
         self._audit = audit or (lambda *a, **kw: None)
+        # One protected section for status-check → conflict-check → apply →
+        # transition. In-process serialization is the right weight here: the
+        # review queue lives in this process and the write itself is atomic
+        # (temp file + os.replace), so a cross-process file lock adds nothing.
+        self._apply_lock = threading.Lock()
 
     # ── classification / staging (agent-loop governor port) ─────────────
 
@@ -125,15 +183,24 @@ class ChangeProposalService:
             return False
 
     def _read_before(self, path: str) -> str:
+        return self._snapshot(path)[1]
+
+    def _snapshot(self, path: str) -> Tuple[bool, str]:
+        """(exists, content) of the target *as the proposal pipeline sees it*.
+
+        Both staging and the approve-time conflict check go through this one
+        normalization (truncate → utf-8 with replacement), so an unchanged
+        file always hashes identically at both points in time.
+        """
         try:
             target = self._resolve_path(path)
             if not target.is_file():
-                return ""
+                return False, ""
             raw = target.read_bytes()[:_MAX_STAGED_BYTES]
-            return raw.decode("utf-8", errors="replace")
+            return True, raw.decode("utf-8", errors="replace")
         except Exception:
             LOGGER.exception("change proposal read failed")
-            return ""
+            return False, ""
 
     def _staged_content(self, name: str, args: Dict[str, Any]) -> Optional[str]:
         if name == "write_file":
@@ -164,7 +231,7 @@ class ChangeProposalService:
         workspace_id: Optional[str] = None,
         context: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
-        before = self._read_before(path)
+        base_exists, before = self._snapshot(path)
         diff = _unified_diff(before, new_content, path)
         tier = "small" if len(diff) <= _SMALL_TIER_DIFF_LINES else "large"
         provenance: Dict[str, Any] = {"proposed_by": proposed_by, "reason": reason}
@@ -183,6 +250,11 @@ class ChangeProposalService:
                 "tier": tier,
                 "before_bytes": len(before.encode("utf-8")),
                 "after_bytes": len(new_content.encode("utf-8")),
+                # Base snapshot for the approve-time conflict check: an empty
+                # base_sha256 with base_exists=False means "proposed against a
+                # missing file", never "hash of the empty string".
+                "base_exists": base_exists,
+                "base_sha256": _sha256_text(before) if base_exists else "",
             },
             provenance=provenance,
             user_email=user_email,
@@ -203,7 +275,7 @@ class ChangeProposalService:
         user_email: Optional[str] = None,
         workspace_id: Optional[str] = None,
     ) -> Dict[str, Any]:
-        before = self._read_before(path)
+        base_exists, before = self._snapshot(path)
         item = self._review_queue.create(
             title=f"파일 삭제 제안: {path}",
             summary=reason or "기존 파일을 삭제하는 작업이라 검토 후 적용됩니다.",
@@ -215,6 +287,8 @@ class ChangeProposalService:
                 "tier": "large",
                 "before_bytes": len(before.encode("utf-8")),
                 "after_bytes": 0,
+                "base_exists": base_exists,
+                "base_sha256": _sha256_text(before) if base_exists else "",
             },
             provenance={"proposed_by": proposed_by, "reason": reason},
             user_email=user_email,
@@ -274,28 +348,96 @@ class ChangeProposalService:
         self, item_id: str, *, user_email: Optional[str] = None,
         workspace_id: Optional[str] = None,
     ) -> Dict[str, Any]:
-        item = self._review_queue.get(item_id, workspace_id=workspace_id)
-        if item.get("source") != "change_proposal":
-            raise KeyError(f"not a change proposal: {item_id}")
-        payload = item.get("payload") or {}
-        kind = item.get("kind")
-        path = str(payload.get("path") or "")
-        target = self._resolve_path(path)
-        if kind == "file_update":
-            target.parent.mkdir(parents=True, exist_ok=True)
-            target.write_text(str(payload.get("new_content") or ""), encoding="utf-8")
-        elif kind == "file_delete":
-            if target.is_file():
-                target.unlink()
-        else:
-            raise ValueError(f"unknown change proposal kind: {kind}")
-        approved = self._review_queue.approve(item_id, workspace_id=workspace_id)
+        """Apply the staged change exactly as reviewed — but only if the file
+        on disk still matches the base snapshot the reviewer looked at.
+
+        Raises :class:`ProposalConflictError` (→ HTTP 409) when the target
+        drifted since staging or the proposal was already resolved; nothing
+        touches disk in that case, so out-of-band user edits are preserved.
+        """
+        with self._apply_lock:
+            item = self._review_queue.get(item_id, workspace_id=workspace_id)
+            if item.get("source") != "change_proposal":
+                raise KeyError(f"not a change proposal: {item_id}")
+            payload = item.get("payload") or {}
+            kind = str(item.get("kind") or "")
+            path = str(payload.get("path") or "")
+            if kind not in ("file_update", "file_delete"):
+                raise ValueError(f"unknown change proposal kind: {kind}")
+
+            # Duplicate/concurrent approval guard: a resolved proposal must
+            # never re-apply (the disk may have moved on since it was applied).
+            status = str(item.get("status") or "pending")
+            if status not in ("pending", "snoozed"):
+                raise ProposalConflictError(
+                    reason=f"already_{status}", path=path, kind=kind,
+                    rebase_hint="이미 처리된 제안입니다. 다시 적용할 수 없습니다.",
+                )
+
+            self._check_base_unchanged(payload, path=path, kind=kind)
+
+            target = self._resolve_path(path)
+            if kind == "file_update":
+                self._atomic_write(target, str(payload.get("new_content") or ""))
+            else:  # file_delete — existence re-verified inside the lock
+                if target.is_file():
+                    target.unlink()
+            approved = self._review_queue.approve(item_id, workspace_id=workspace_id)
         self._audit(
             "change_proposal_applied", user_email=user_email,
             proposal_id=item_id, path=path, kind=kind,
         )
         return {"item": approved, "applied": True, "path": path, "kind": kind}
 
+    def _check_base_unchanged(
+        self, payload: Dict[str, Any], *, path: str, kind: str
+    ) -> None:
+        """Compare the disk state *now* against the staged base snapshot."""
+        if "base_sha256" not in payload or "base_exists" not in payload:
+            # Legacy proposal staged before base snapshots existed — keep the
+            # historical apply-as-reviewed behavior rather than rejecting it.
+            return
+        base_exists = bool(payload.get("base_exists"))
+        base_sha256 = str(payload.get("base_sha256") or "")
+        current_exists, current_content = self._snapshot(path)
+        current_sha256 = _sha256_text(current_content) if current_exists else ""
+        if not base_exists:
+            if current_exists:
+                raise ProposalConflictError(
+                    reason="file_created_since_proposal", path=path, kind=kind,
+                    current_sha256=current_sha256,
+                )
+            return
+        if not current_exists:
+            raise ProposalConflictError(
+                reason="file_deleted_since_proposal", path=path, kind=kind,
+                base_sha256=base_sha256,
+            )
+        if current_sha256 != base_sha256:
+            raise ProposalConflictError(
+                reason="file_modified_since_proposal", path=path, kind=kind,
+                base_sha256=base_sha256, current_sha256=current_sha256,
+            )
+
+    @staticmethod
+    def _atomic_write(target: Path, content: str) -> None:
+        """Write via a same-directory temp file + ``os.replace`` so readers
+        never observe a partially written proposal."""
+        target.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(
+            dir=str(target.parent), prefix=f".{target.name}.", suffix=".staged"
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                handle.write(content)
+            os.replace(tmp_name, target)
+        except BaseException:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+            raise
+
     def reject(
         self, item_id: str, *, user_email: Optional[str] = None,
         workspace_id: Optional[str] = None, reason: str = "",
@@ -319,4 +461,4 @@ class ChangeProposalService:
         return {"item": dismissed, "applied": False, "reason": reason}
 
 
-__all__ = ["ChangeProposalService"]
+__all__ = ["ChangeProposalService", "ProposalConflictError"]

package/latticeai/services/product_readiness.py

@@ -18,7 +18,7 @@ from typing import Any, Dict, List
 
 from latticeai.services.architecture_readiness import architecture_readiness
 
-PRODUCT_VERSION_TARGET = "9.8.0"
+PRODUCT_VERSION_TARGET = "9.9.0"
 
 
 @dataclass(frozen=True)

package/latticeai/services/tool_dispatch.py

@@ -21,6 +21,7 @@ from latticeai.core.agent_prompts import (
     PLANNER_PROMPT,
 )
 from latticeai.core.policy import role_has_capability
+from latticeai.core.tool_governor import classify_tool_call
 from latticeai.core.tool_registry import ToolPermission, ToolPolicy
 from latticeai.tools import AGENT_ROOT, DEFAULT_TOOL_REGISTRY, ToolError, ensure_agent_root
 
@@ -122,6 +123,22 @@ class ToolDispatchService:
                 detail=f"'{tool_name}' 툴에는 '{capability}' capability가 필요합니다.",
             )
 
+    def _governed_path_exists(self, path: str) -> bool:
+        """Best-effort existence check for governance classification.
+
+        Resolves workspace-relative paths under ``AGENT_ROOT`` and honors
+        absolute paths (home-sandbox writes). Never raises — an unresolvable
+        path is treated as non-existent (additive), which the fail-closed
+        guard only escalates when the target actually exists.
+        """
+        try:
+            candidate = Path(path)
+            if not candidate.is_absolute():
+                candidate = Path(AGENT_ROOT) / candidate
+            return candidate.exists()
+        except Exception:
+            return False
+
     def user_role(self, current_user: str) -> str:
         users = self.load_users()
         try:
@@ -162,6 +179,22 @@ class ToolDispatchService:
                 status_code=403,
                 detail=f"'{tool_name}' 툴은 파괴적 작업으로 차단되었습니다.",
             )
+        # Fail-closed governance: a call that would rewrite existing content but
+        # cannot be staged as a reviewable proposal is blocked, never applied
+        # silently. New-file (additive) calls are unaffected.
+        verdict = classify_tool_call(
+            tool_name, args or {},
+            policy=dict(policy), path_exists=self._governed_path_exists,
+        )
+        if verdict.get("fail_closed"):
+            raise HTTPException(
+                status_code=409,
+                detail=(
+                    f"'{tool_name}' 툴은 기존 콘텐츠를 변경하지만 검토 가능한 제안으로 "
+                    "적용할 수 없어 차단되었습니다. 새 파일 이름으로 생성하거나 "
+                    "지원되는 편집 도구(write_file/edit_file)를 사용하세요."
+                ),
+            )
         if (
             require_auto_approval
             and not trusted_admin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "9.8.0",
+  "version": "9.9.0",
   "description": "Lattice AI — local-first Digital Brain that keeps your knowledge durable across any AI model.",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
@@ -24,10 +24,12 @@
     "build:assets": "vite build && node scripts/build_frontend_assets.mjs",
     "build:python": "node scripts/run_python.mjs -m build",
     "check:python": "node scripts/run_python.mjs scripts/check_python.py",
-    "lint": "npm run lint:python && node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:frontend && npm run frontend:openapi:check && node scripts/check_i18n_literals.mjs && npm run test:browser-extension",
+    "lint": "npm run lint:python && node --check tests/visual/mock_server.cjs && node --check tests/visual/v3.spec.js && npm run lint:frontend && npm run frontend:openapi:check && node scripts/check_i18n_literals.mjs && npm run check:bundle && npm run test:browser-extension",
     "lint:python": "node scripts/run_python.mjs -m ruff check .",
     "lint:frontend": "node scripts/lint_frontend.mjs",
-    "docs:check-links": "node scripts/check_markdown_links.mjs",
+    "check:bundle": "node scripts/check_bundle_budget.mjs",
+    "docs:check-links": "node scripts/check_markdown_links.mjs && node scripts/check_doc_status.mjs",
+    "docs:check-status": "node scripts/check_doc_status.mjs",
     "docs:check-current": "node scripts/check_current_release_docs.mjs",
     "typecheck": "npm run typecheck:frontend && cd vscode-extension && npm run build",
     "typecheck:frontend": "npx tsc -p tsconfig.json --noEmit",