mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/vocabulary/__init__.py

@@ -0,0 +1 @@
+"""vocabulary."""

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/vocabulary/alias_projection.py

@@ -0,0 +1,331 @@
+"""Plan and apply DB-to-YAML alias projections."""
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pydantic import Field, StrictBool, StrictStr
+
+from mednotes.domains.wiki.batch_state import file_sha256
+from mednotes.domains.wiki.capabilities.notes.raw_chats import atomic_write_text
+from mednotes.domains.wiki.capabilities.vocabulary.link_terms import normalize_key
+from mednotes.domains.wiki.capabilities.vocabulary.vocabulary_map import ProjectionAlias, VocabularyMap
+from mednotes.kernel.base import ContractModel, JsonObject, JsonObjectAdapter
+
+ALIAS_PROJECTION_PLAN_SCHEMA = "medical-notes-workbench.alias-projection-plan.v1"
+ALIAS_PROJECTION_RECEIPT_SCHEMA = "medical-notes-workbench.alias-projection-receipt.v1"
+
+
+class _AliasProjectionOperationPayload(ContractModel):
+    operation_id: StrictStr = ""
+    note_path: StrictStr = Field(min_length=1)
+    before_hash: StrictStr = ""
+    after_aliases: list[StrictStr] = Field(default_factory=list)
+    preserved_contextual_aliases: list[StrictStr] = Field(default_factory=list)
+    blocked_aliases: list[StrictStr] = Field(default_factory=list)
+    requires_backup: StrictBool = False
+    backup: StrictBool = False
+    changed: StrictBool = False
+
+
+class _AliasProjectionReceiptPayload(ContractModel):
+    status: StrictStr
+    blocked_reason: StrictStr = ""
+    note_path: StrictStr = ""
+    before_hash: StrictStr = ""
+    after_hash: StrictStr = ""
+    backup_path: StrictStr = ""
+
+
+@dataclass(frozen=True)
+class AliasProjectionReceipt:
+    status: str
+    blocked_reason: str = ""
+    note_path: str = ""
+    before_hash: str = ""
+    after_hash: str = ""
+    backup_path: str = ""
+
+    def as_dict(self) -> JsonObject:
+        return _AliasProjectionReceiptPayload(
+            status=self.status,
+            blocked_reason=self.blocked_reason,
+            note_path=self.note_path,
+            before_hash=self.before_hash,
+            after_hash=self.after_hash,
+            backup_path=self.backup_path,
+        ).to_payload()
+
+
+@dataclass
+class AliasProjectionPlan:
+    note_path: Path
+    before_hash: str
+    after_aliases: list[str]
+    preserved_contextual_aliases: list[str]
+    changed: bool
+    backup: bool = False
+    requires_backup: bool = False
+    blocked_aliases: list[str] = field(default_factory=list)
+
+    def as_operation(self) -> JsonObject:
+        return _AliasProjectionOperationPayload(
+            operation_id=f"alias_projection.update:{self.note_path}",
+            note_path=str(self.note_path),
+            before_hash=self.before_hash,
+            after_aliases=self.after_aliases,
+            preserved_contextual_aliases=self.preserved_contextual_aliases,
+            blocked_aliases=self.blocked_aliases,
+            requires_backup=self.requires_backup,
+            backup=False,
+            changed=self.changed,
+        ).to_payload()
+
+    def apply(self) -> AliasProjectionReceipt:
+        current_hash = _file_hash(self.note_path)
+        if current_hash != self.before_hash:
+            return AliasProjectionReceipt(
+                status="blocked",
+                blocked_reason="alias_projection.stale_note_hash",
+                note_path=str(self.note_path),
+                before_hash=self.before_hash,
+            )
+        original = self.note_path.read_text(encoding="utf-8")
+        updated = replace_aliases_in_frontmatter(original, self.after_aliases)
+        if updated != original:
+            atomic_write_text(self.note_path, updated)
+        return AliasProjectionReceipt(
+            status="applied",
+            note_path=str(self.note_path),
+            before_hash=self.before_hash,
+            after_hash=_file_hash(self.note_path),
+            backup_path="",
+        )
+
+
+def plan_alias_projection(vocab: VocabularyMap, *, note_path: Path, backup: bool = True) -> AliasProjectionPlan:
+    candidates = vocab.note_aliases.get(str(note_path), [])
+    selected = _dedupe_aliases(candidates)
+    note_text = note_path.read_text(encoding="utf-8")
+    title_key = normalize_key(_h1_title(note_text) or note_path.stem)
+    after_aliases = [
+        item.text
+        for item in selected
+        if item.visible_in_yaml and item.link_policy in {"direct", "requires_context"}
+        and item.normalized_surface != title_key
+    ]
+    contextual = [
+        item.text
+        for item in selected
+        if item.link_policy == "requires_context" and item.visible_in_yaml and item.normalized_surface != title_key
+    ]
+    blocked = [item.text for item in selected if item.visible_in_yaml and item.link_policy in {"blocked", "no_link"}]
+    current = _current_aliases(note_text)
+    return AliasProjectionPlan(
+        note_path=note_path,
+        before_hash=_file_hash(note_path),
+        after_aliases=after_aliases,
+        preserved_contextual_aliases=contextual,
+        changed=current != after_aliases,
+        backup=False,
+        requires_backup=False,
+        blocked_aliases=blocked,
+    )
+
+
+def build_alias_projection_plan(vocab: VocabularyMap, *, backup: bool = True) -> JsonObject:
+    operations: list[JsonObject] = []
+    for raw_path in sorted(vocab.note_aliases):
+        note_path = Path(raw_path)
+        if not note_path.is_file():
+            continue
+        operations.append(plan_alias_projection(vocab, note_path=note_path, backup=backup).as_operation())
+    changed_count = sum(1 for item in operations if item.get("changed"))
+    return {
+        "schema": ALIAS_PROJECTION_PLAN_SCHEMA,
+        "status": "planned",
+        "db_path": str(vocab.db_path) if vocab.db_path else "",
+        "operation_count": len(operations),
+        "changed_count": changed_count,
+        "operations": operations,
+    }
+
+
+def apply_alias_projection_plan(plan: JsonObject) -> JsonObject:
+    if plan.get("schema") != ALIAS_PROJECTION_PLAN_SCHEMA:
+        return {
+            "schema": ALIAS_PROJECTION_RECEIPT_SCHEMA,
+            "status": "blocked",
+            "blocked_reason": "alias_projection.invalid_plan_schema",
+            "applied_count": 0,
+            "blocked_count": 0,
+            "receipts": [],
+        }
+    receipts: list[JsonObject] = []
+    db_path = Path(str(plan.get("db_path") or ""))
+    operations = plan.get("operations", [])
+    if not isinstance(operations, list):
+        operations = []
+    for operation in operations:
+        if not isinstance(operation, dict):
+            continue
+        projection_plan = _plan_from_operation(operation)
+        receipt = _AliasProjectionReceiptPayload.model_validate(projection_plan.apply().as_dict())
+        if (
+            receipt.status == "applied"
+            and receipt.before_hash != receipt.after_hash
+            and db_path.is_file()
+        ):
+            _sync_note_hash(db_path, projection_plan.note_path, receipt.after_hash)
+        receipts.append(receipt.to_payload())
+    typed_receipts = [_AliasProjectionReceiptPayload.model_validate(item) for item in receipts]
+    blocked_count = sum(1 for item in typed_receipts if item.status == "blocked")
+    applied_count = sum(
+        1
+        for item in typed_receipts
+        if item.status == "applied" and item.before_hash != item.after_hash
+    )
+    return {
+        "schema": ALIAS_PROJECTION_RECEIPT_SCHEMA,
+        "status": "blocked" if blocked_count else "completed",
+        "blocked_reason": "alias_projection.blocked_operations" if blocked_count else "",
+        "operation_count": len(receipts),
+        "applied_count": applied_count,
+        "blocked_count": blocked_count,
+        "receipts": receipts,
+    }
+
+
+def _plan_from_operation(operation: JsonObject) -> AliasProjectionPlan:
+    typed = _AliasProjectionOperationPayload.model_validate(JsonObjectAdapter.validate_python(operation))
+    return AliasProjectionPlan(
+        note_path=Path(typed.note_path),
+        before_hash=typed.before_hash,
+        after_aliases=list(typed.after_aliases),
+        preserved_contextual_aliases=list(typed.preserved_contextual_aliases),
+        changed=typed.changed,
+        backup=False,
+        requires_backup=False,
+        blocked_aliases=list(typed.blocked_aliases),
+    )
+
+
+def _sync_note_hash(db_path: Path, note_path: Path, content_hash: str) -> None:
+    if not content_hash:
+        return
+    with sqlite3.connect(db_path) as conn:
+        conn.execute(
+            """
+            UPDATE notes
+            SET content_hash = ?, updated_at = CURRENT_TIMESTAMP
+            WHERE path = ? AND status = 'active'
+            """,
+            (content_hash, str(note_path)),
+        )
+
+
+def replace_aliases_in_frontmatter(text: str, aliases: list[str]) -> str:
+    frontmatter, body = _split_frontmatter(text)
+    if frontmatter is None:
+        alias_block = _format_aliases(aliases)
+        return f"---\n{alias_block}---\n{body.lstrip(chr(10))}" if alias_block else body
+    lines = frontmatter.splitlines(keepends=True)
+    out: list[str] = []
+    idx = 0
+    replaced = False
+    while idx < len(lines):
+        key = _key_for(lines[idx])
+        if key == "aliases":
+            if aliases:
+                out.append(_format_aliases(aliases))
+            replaced = True
+            idx += 1
+            while idx < len(lines) and _key_for(lines[idx]) is None:
+                idx += 1
+            continue
+        out.append(lines[idx])
+        idx += 1
+    if aliases and not replaced:
+        out.insert(0, _format_aliases(aliases))
+    rendered = "".join(out)
+    if not rendered.strip():
+        return body.lstrip("\n")
+    return f"---\n{rendered}---\n{body.lstrip(chr(10))}"
+
+
+def _dedupe_aliases(candidates: list[ProjectionAlias]) -> list[ProjectionAlias]:
+    best: dict[str, ProjectionAlias] = {}
+    for candidate in candidates:
+        key = candidate.normalized_surface
+        existing = best.get(key)
+        if existing is None or _alias_score(candidate) > _alias_score(existing):
+            best[key] = candidate
+    return sorted(best.values(), key=lambda item: (_is_acronym(item.text), item.order, item.text.casefold()))
+
+
+def _alias_score(candidate: ProjectionAlias) -> tuple[int, int, int, int]:
+    policy_score = {"direct": 3, "requires_context": 2, "no_link": 1, "blocked": 0}.get(candidate.link_policy, 0)
+    return (policy_score, *_display_score(candidate.text))
+
+
+def _display_score(value: str) -> tuple[int, int, int]:
+    return (
+        int(any(ord(char) > 127 for char in value)),
+        int(_is_acronym(value)),
+        sum(1 for char in value if char.isupper()),
+    )
+
+
+def _is_acronym(value: str) -> bool:
+    return value.isupper() and len(value) <= 8
+
+
+def _file_hash(path: Path) -> str:
+    return "sha256:" + file_sha256(path)
+
+
+def _h1_title(text: str) -> str:
+    match = re.search(r"(?m)^#\s+(.+?)\s*$", text)
+    return match.group(1).strip() if match else ""
+
+
+def _split_frontmatter(text: str) -> tuple[str | None, str]:
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return None, text
+    for idx in range(1, len(lines)):
+        if lines[idx].strip() == "---":
+            return "".join(lines[1:idx]), "".join(lines[idx + 1 :])
+    return None, text
+
+
+def _key_for(line: str) -> str | None:
+    match = re.match(r"^([A-Za-z0-9_-]+)\s*:", line)
+    return match.group(1) if match else None
+
+
+def _format_aliases(aliases: list[str]) -> str:
+    if not aliases:
+        return ""
+    return "aliases:\n" + "".join(f"  - {json.dumps(alias, ensure_ascii=False)}\n" for alias in aliases)
+
+
+def _current_aliases(text: str) -> list[str]:
+    frontmatter, _body = _split_frontmatter(text)
+    if not frontmatter:
+        return []
+    inline = re.search(r"(?m)^aliases\s*:\s*\[(.*?)\]\s*$", frontmatter)
+    if inline:
+        return [item.strip().strip("'\"") for item in inline.group(1).split(",") if item.strip()]
+    block = re.search(r"(?m)^aliases\s*:\s*\n((?:\s*-\s*.*(?:\n|$))+)", frontmatter)
+    if not block:
+        return []
+    aliases: list[str] = []
+    for line in block.group(1).splitlines():
+        match = re.match(r"^\s*-\s*(.*?)\s*$", line)
+        if match:
+            aliases.append(match.group(1).strip().strip("'\""))
+    return aliases

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/vocabulary/link_terms.py

@@ -0,0 +1,151 @@
+"""Shared term, alias, and catalog helpers for Wiki graph/linker code."""
+from __future__ import annotations
+
+import os
+import re
+import unicodedata
+from pathlib import Path
+from typing import Any
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL | re.MULTILINE)
+CATALOG_CONTAINER_KEYS = ("entities", "entidades", "notes", "notas", "items", "catalog", "catalogo")
+TARGET_KEYS = ("target", "target_file", "arquivo", "file", "filename", "nota", "note", "path", "caminho")
+ALIAS_KEYS = ("aliases", "alias", "sinonimos", "sinônimos", "synonyms", "siglas", "acronyms", "termos", "terms")
+TITLE_KEYS = ("titulo", "title", "nome", "name")
+INDEX_TARGET_KEYS = {"_indice_medicina"}
+INDEX_TAG_KEYS = {"indice"}
+
+
+def normalize_key(value: str) -> str:
+    value = unicodedata.normalize("NFKD", value)
+    value = "".join(char for char in value if not unicodedata.combining(char))
+    return re.sub(r"\s+", " ", value).strip().casefold()
+
+
+def obsidian_target_name(value: str) -> str:
+    target = str(value or "").strip().replace("\\", "/")
+    if not target:
+        return ""
+    name = target.rsplit("/", 1)[-1].strip()
+    return name[:-3] if name.casefold().endswith(".md") else name
+
+
+def is_index_target(value: str) -> bool:
+    return normalize_key(obsidian_target_name(value)) in INDEX_TARGET_KEYS
+
+
+def extract_tags(content: str) -> list[str]:
+    tags: list[str] = []
+    match = FRONTMATTER_RE.search(content)
+    if not match:
+        return tags
+    yaml_block = match.group(1)
+
+    list_match = re.search(r"tags:\s*\[(.*?)\]", yaml_block, re.IGNORECASE)
+    if list_match:
+        tags.extend(clean_yaml_scalar(item).lstrip("#") for item in list_match.group(1).split(",") if item.strip())
+
+    multi_line_match = re.search(r"tags:\s*\n((?:\s*-\s*.*(?:\n|$))+)", yaml_block, re.IGNORECASE)
+    if multi_line_match:
+        for line in multi_line_match.group(1).strip().split("\n"):
+            item = re.sub(r"^\s*-\s*", "", line).strip()
+            if item:
+                tags.append(clean_yaml_scalar(item).lstrip("#"))
+
+    return [tag for tag in tags if tag]
+
+
+def is_index_note_content(content: str) -> bool:
+    return any(normalize_key(tag) in INDEX_TAG_KEYS for tag in extract_tags(content))
+
+
+def is_index_note(path: Path, content: str) -> bool:
+    return is_index_target(path.stem) or is_index_note_content(content)
+
+
+def expand_path(value: str | os.PathLike[str]) -> Path:
+    return Path(os.path.expandvars(str(value))).expanduser()
+
+
+def clean_yaml_scalar(value: str) -> str:
+    return value.strip().strip("'\"").strip()
+
+
+def extract_aliases(content: str) -> list[str]:
+    aliases: list[str] = []
+    match = FRONTMATTER_RE.search(content)
+    if not match:
+        return aliases
+    yaml_block = match.group(1)
+
+    list_match = re.search(r"aliases:\s*\[(.*?)\]", yaml_block, re.IGNORECASE)
+    if list_match:
+        aliases.extend(clean_yaml_scalar(item) for item in list_match.group(1).split(",") if item.strip())
+
+    multi_line_match = re.search(r"aliases:\s*\n((?:\s*-\s*.*(?:\n|$))+)", yaml_block, re.IGNORECASE)
+    if multi_line_match:
+        for line in multi_line_match.group(1).strip().split("\n"):
+            item = re.sub(r"^\s*-\s*", "", line).strip()
+            if item:
+                aliases.append(clean_yaml_scalar(item))
+
+    return [alias for alias in aliases if alias]
+
+
+def as_list(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    return [value]
+
+
+def string_values(value: Any) -> list[str]:
+    return [item.strip() for item in as_list(value) if isinstance(item, str) and item.strip()]
+
+
+def catalog_entries(data: Any) -> list[tuple[str, dict[str, Any]]]:
+    if isinstance(data, list):
+        return [("", item) for item in data if isinstance(item, dict)]
+    if not isinstance(data, dict):
+        return []
+
+    for key in CATALOG_CONTAINER_KEYS:
+        value = data.get(key)
+        if isinstance(value, list):
+            return [("", item) for item in value if isinstance(item, dict)]
+        if isinstance(value, dict):
+            return [(str(k), item) for k, item in value.items() if isinstance(item, dict)]
+
+    return [(str(key), value) for key, value in data.items() if isinstance(value, dict)]
+
+
+def target_from_entry(entry: dict[str, Any], fallback_key: str = "") -> str | None:
+    for key in TARGET_KEYS:
+        value = entry.get(key)
+        if isinstance(value, str) and value.strip():
+            return obsidian_target_name(value.strip())
+    if fallback_key:
+        return obsidian_target_name(fallback_key)
+    for key in TITLE_KEYS:
+        value = entry.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def aliases_from_entry(entry: dict[str, Any]) -> list[str]:
+    aliases: list[str] = []
+    for key in ALIAS_KEYS:
+        aliases.extend(string_values(entry.get(key)))
+    return aliases
+
+
+def terms_from_entry(entry: dict[str, Any], target: str) -> list[str]:
+    terms = [target]
+    terms.extend(aliases_from_entry(entry))
+    for key in TITLE_KEYS:
+        terms.extend(string_values(entry.get(key)))
+    return terms

package/.opencode/mednotes/src/mednotes/domains/wiki/capabilities/vocabulary/llm_disambiguation.py

@@ -0,0 +1,182 @@
+"""Gemini CLI seam for contextual body-link disambiguation."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from mednotes.kernel.base import ContractModel, JsonObject, JsonObjectAdapter
+
+CONTEXTUAL_ALIAS_SCHEMA = "medical-notes-workbench.contextual-alias-disambiguation.v1"
+_WINDOWS_PROMPT_FILE_THRESHOLD = 6000
+
+
+class LinkDisambiguationError(RuntimeError):
+    """Raised when contextual alias disambiguation cannot get valid JSON."""
+
+
+class LinkDisambiguationRequiresOrchestrator(LinkDisambiguationError):
+    """Raised when direct Gemini CLI disambiguation is disabled for UX safety."""
+
+
+class _ContextualAliasResponseFields(ContractModel):
+    """Typed response envelope required from contextual alias disambiguation."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True, validate_assignment=True)
+
+    schema_id: str = Field(alias="schema")
+    decisions: list[JsonObject]
+
+
+def call_contextual_alias_disambiguator(
+    requests: list[dict[str, Any]],
+    *,
+    model: str,
+    timeout_seconds: int,
+) -> dict[str, Any]:
+    if not _direct_gemini_disambiguation_allowed():
+        raise LinkDisambiguationRequiresOrchestrator(
+            "desambiguação contextual por gemini -p direta está desativada; use orquestração por agente"
+        )
+    prompt = _build_prompt(requests)
+    raw = _call_gemini(prompt, model=model, timeout_seconds=timeout_seconds)
+    return _parse_response(raw)
+
+
+def _direct_gemini_disambiguation_allowed() -> bool:
+    return os.getenv("MEDNOTES_ALLOW_INTERNAL_GEMINI_DISAMBIGUATION", "").strip().lower() in {"1", "true", "yes"}
+
+
+def _build_prompt(requests: list[dict[str, Any]]) -> str:
+    payload = {
+        "schema": "medical-notes-workbench.contextual-alias-disambiguation-request.v1",
+        "instructions": [
+            "Você decide links de termos médicos ambíguos no corpo de notas Obsidian.",
+            "Escolha somente um dos candidatos fornecidos em cada ocorrência.",
+            "Nunca invente alvo, nota, meaning_id ou alias.",
+            "Se o contexto for insuficiente, responda action=defer.",
+            "Se o termo claramente não deve ser linkado, responda action=no_link.",
+            "Use confidence entre 0 e 1.",
+            f"Responda apenas JSON com schema {CONTEXTUAL_ALIAS_SCHEMA}.",
+        ],
+        "requests": requests,
+        "response_shape": {
+            "schema": CONTEXTUAL_ALIAS_SCHEMA,
+            "decisions": [
+                {
+                    "occurrence_id": "copie da requisição",
+                    "action": "link|no_link|defer",
+                    "chosen_meaning_id": "meaning id do candidato escolhido, se action=link",
+                    "chosen_target": "target do candidato escolhido, se action=link",
+                    "confidence": 0.0,
+                    "reason_code": "curto_sem_espacos",
+                    "rationale_summary": "resumo redigido, sem copiar trecho clínico bruto",
+                }
+            ],
+        },
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _call_gemini(prompt: str, *, model: str, timeout_seconds: int) -> str:
+    binary = os.getenv("MEDNOTES_GEMINI_BINARY", "gemini")
+    cmd = [_resolve_gemini_binary(binary), "--skip-trust", "-m", model]
+    if _prompt_needs_file(prompt):
+        return _invoke_with_prompt_file(cmd, prompt, timeout_seconds=timeout_seconds)
+    return _invoke([*cmd, "-p", prompt], timeout_seconds=timeout_seconds)
+
+
+def _resolve_gemini_binary(binary: str) -> str:
+    expanded = os.path.expandvars(os.path.expanduser(binary))
+    if _is_pathish(expanded):
+        return expanded
+    found = shutil.which(expanded)
+    if found:
+        return found
+    if expanded.lower() in {"gemini", "gemini.cmd"}:
+        for candidate in _npm_gemini_candidates():
+            if candidate.is_file():
+                return str(candidate)
+    return expanded
+
+
+def _is_pathish(value: str) -> bool:
+    return "/" in value or "\\" in value or (len(value) >= 2 and value[1] == ":")
+
+
+def _npm_gemini_candidates() -> list[Path]:
+    candidates: list[Path] = []
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        candidates.append(Path(appdata) / "npm" / "gemini.cmd")
+    prefix = os.environ.get("NPM_CONFIG_PREFIX")
+    if prefix:
+        prefix_path = Path(prefix)
+        candidates.extend([prefix_path / "gemini.cmd", prefix_path / "bin" / "gemini"])
+    return candidates
+
+
+def _prompt_needs_file(prompt: str) -> bool:
+    return os.name == "nt" and len(prompt) >= _WINDOWS_PROMPT_FILE_THRESHOLD
+
+
+def _invoke_with_prompt_file(cmd: list[str], prompt: str, *, timeout_seconds: int) -> str:
+    with tempfile.TemporaryDirectory(prefix="mednotes-link-disambiguation-") as tmp:
+        prompt_path = Path(tmp) / "prompt.md"
+        prompt_path.write_text(prompt, encoding="utf-8")
+        return _invoke([*cmd, "--include-directories", str(prompt_path.parent), "-p", f"@{prompt_path}"], timeout_seconds=timeout_seconds)
+
+
+def _invoke(cmd: list[str], *, timeout_seconds: int) -> str:
+    try:
+        proc = subprocess.run(
+            _subprocess_command(cmd),
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=timeout_seconds,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise LinkDisambiguationError(f"gemini CLI excedeu timeout de {timeout_seconds}s") from exc
+    except FileNotFoundError as exc:
+        raise LinkDisambiguationError("gemini CLI não encontrado para desambiguação contextual") from exc
+    except OSError as exc:
+        raise LinkDisambiguationError(f"gemini CLI não pôde ser iniciado: {exc}") from exc
+    if proc.returncode != 0:
+        raise LinkDisambiguationError(f"gemini CLI falhou (rc={proc.returncode}): {proc.stderr.strip()}")
+    return proc.stdout
+
+
+def _subprocess_command(cmd: list[str]) -> list[str]:
+    if not cmd:
+        return cmd
+    suffix = Path(cmd[0]).suffix.lower()
+    if os.name == "nt" and suffix in {".cmd", ".bat"}:
+        return [os.environ.get("COMSPEC") or "cmd.exe", "/d", "/s", "/c", *cmd]
+    return cmd
+
+
+def _parse_response(raw: str) -> JsonObject:
+    stripped = raw.strip()
+    if stripped.startswith("```"):
+        lines = stripped.splitlines()
+        if lines and lines[0].startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].startswith("```"):
+            lines = lines[:-1]
+        stripped = "\n".join(lines).strip()
+    try:
+        payload = json.loads(stripped)
+    except json.JSONDecodeError as exc:
+        raise LinkDisambiguationError(f"resposta Gemini não é JSON válido: {exc}") from exc
+    payload = JsonObjectAdapter.validate_python(payload)
+    fields = _ContextualAliasResponseFields.model_validate(payload)
+    if fields.schema_id != CONTEXTUAL_ALIAS_SCHEMA:
+        raise LinkDisambiguationError(f"resposta Gemini precisa usar schema {CONTEXTUAL_ALIAS_SCHEMA}")
+    return payload